Overview
If you are developing Crystal Reports Active Server Pages (ASP) applications with the Report Designer Component (RDC) it is vital that you manage license usage effectively. This will ensure that your applications function without errors and that you utilize your purchased licenses efficiently.
Contents
INTRODUCTION ............................................................................................ 2 WEB REPORTING METHODS ........................................................................ 2 LICENSES AND THE DEVELOPER VERSION OF CRYSTAL REPORTS 8.5............ 3 What does Concurrent mean?......................................................................3 How do I check on our number of licenses? ................................................3 M ANAGING LICENSE USAGE WITHIN CR ASP APPLICATIONS ....................... 5 RELEASING LICENSES FROM YOUR ASP APPLICATION .................................. 6 ASP Timeout ................................................................................................6 Session.Abandon ..........................................................................................6
Session.Abandon side effects............................................................................. 7
Session.Contents.Remove.............................................................................8 FURTHER RDC LICENSING INFORMATION ..................................................... 8 CONTACTING CRYSTAL DECISIONS FOR TECHNICAL SUPPORT ...................... 8
HTTP://WWW.CRYSTALDECISIONS.COM/CONTACT/SUPPORT.ASP .................... 8
4/25/2003 9:09 AM
Page 1
Introduction
The goal of this document is to explain how license usage is monitored within ASP (Active Server Pages) applications developed with the Crystal Reports 8.5 Developer Edition. It will also help you to design your applications so that they use your licenses as efficiently as possible.
NOTE
This paper will NOT discuss licensing for the Crystal Reports Designer or for Crystal Enterprise 8.0. A free copy of Crystal Enterprise 8.0 Standard (5 user concurrent license) is included as a separate CD in the box with your purchase of Crystal Reports 8.5 and you can read about this products licensing in Crystal Enterprise 8.0 Understanding License Usage found by searching for the file ce8_licensing.pdf at the following location:http://support.crystaldecisions.com/docs
Then you should consult Crystal Enterprise 8.0 Understanding License Usage found by searching for the file ce8_licensing.pdf at the following location:http://support.crystaldecisions.com/docs If you are running the report from an ASP application using the RDC (Craxdrt.dll) and Rptserver.asp then you have downloaded the correct document for your method of web reporting. To learn more about the different methods of web reporting read Tactical Guide to Understanding and Installing Crystal Web Reporting found by searching for the file ce8_introductory_tips.pdf at the following location: http://support.crystaldecisions.com/docs
4/25/2003
Page 2
cr85_asp_licensing.pdf
Page 3
cr85_asp_licensing.pdf
This screen will show you how many users can view reports through your ASP application at the same time. To add additional key codes (and therefore more concurrent users) enter the key code into the Add key code text box and click the Add button to its right. Check to see whether the number of licenses increased in the License Information window at the bottom of the screen. Note the button Concurrent license status. Clicking this runs an ASP script on your web server that queries the Crystal licensing engine and displays the number of licenses available, and the number in-use in real time in a browser window as seen below:
NOTE
In order to display the additional licenses after applying the new key code in the license manager, restart the web service. Restart the World Wide Web service either through the Services area of the Control Panel or through stopping and restarting the web server within the Internet Services Manager. For more information, go to http://support.crystaldecisions.com/kbase and search for knowledge base article c2011030.
bIsActive = oApp.GetLicenseStatus (nLicensed, nActive) Incorporating this script into your own ASP applications enables it to anticipate when youre out of licenses. Then you could have it display a Please Try Again Later message for your users. This would avoid your application displaying the standard Crystal message shown below.
4/25/2003
Page 4
cr85_asp_licensing.pdf
NOTE
The RDC Runtime License Status application is also a handy tool when you are trying to determine your licensing status during the development stage of your application. Keep it open in a browser while you test your application. Refresh the browser from time to time to see how you application is managing your licenses.
Here are examples of how these objects are created (from our ASP samples):
Set session("oApp") = Server.CreateObject("CrystalRuntime.Application") Set session("oRpt") = session("oApp").OpenReport(path & reportname, 1)
4/25/2003
Copyright 2002 Crystal Decisions, Inc. All Rights Reserved.
Page 5
cr85_asp_licensing.pdf
Its important that licenses are released promptly when users finish viewing reports or you wont be able to support the number of web users your licensing entitles you to. The following section outlines various ways the report object is destroyed, thereby releasing a license.
ASP Timeout
The first way that a license may be released is through Microsoft Internet Information Servers (IIS) Active Server Pages timeout value. By default, all session objects in ASP pages will expire and be destroyed after a set period. The default is 20 minutes in Microsoft Internet Information Server. You can alter this global setting (in IIS 5.0: Start > Settings > Control Panel > Administrative Tools > Internet Services Manager. Right-click on the website, choose Properties from the menu, click on the Configuration button in the Home Directory tab, highlight the .asp extension and click the App Options tab, now you can change the Session timeout value for ASP), or set a specific timeout value in your application using the Response objects timeout method. The problem with relying on this timeout is the amount of time users will spend viewing a report will vary widely. For example: Suppose you have 5 CALs, and you set the session timeout to 10 minutes. If users are viewing reports fairly quickly, 5 users could run your application, view a report, and close their browsers in less than 10 minutes. All 5 licenses are now in use. If a sixth user tries to run the application before the 10 minutes have elapsed, they will be refused a license, even though no one is currently viewing reports! They will have to try again later. On the other hand, if you reduce the session timeout to a very small interval (maybe 3 minutes) and the user wants to view a report for more than 3 minutes they will be unable to because at 3 minutes the Report object will be destroyed. To manage our licenses efficiently and also ensure our user experience is satisfactory we need a way to destroy the Report object and release the CAL at the precise point when the user is finished viewing the report.
Session.Abandon
Cleanup.asp, a Crystal Decisions ASP file contained in our samples on the CD and also in our samples available on-line (Aspxmps85.exe, downloadable from http://support.crystaldecisions.com/downloads), uses the "Session.Abandon" call to take oApp, oRpt, oPageEngine session objects out of memory. This is necessary as the concurrent access license is used when
4/25/2003
Copyright 2002 Crystal Decisions, Inc. All Rights Reserved.
Page 6
cr85_asp_licensing.pdf
the report object (oRpt) is created in memory and conversely destroying this session object will release the license. There is a set of ASP samples (Aspxmps85.exe) for Crystal Reports provides examples of various common operations like logging onto databases, setting parameters, etc. The 8.5 version of these samples has new functionality to detect when a user is no longer viewing the report and destroy the report object. Within the sample ASP applications you will find the file, SmartViewerActivex.asp. View the code of this file by opening it in Windows Notepad. Scan the code until you see the following line:
<BODY ONUNLOAD="CallDestroy();">
The ONUNLOAD option on this BODY tag directs the browser to call the function CallDestroy when the page is unloaded (web browser is closed or the user is browsing to another page). CallDestroy runs the ASP page Cleanup.asp in order to release the license that was being used. This will cause the session variables to be destroyed when IIS does its garbage collection. This method of releasing licenses works very well. As the contents of Cleanup.asp is server-side script and is being called from a client-side function, it must reside in a separate file and you will notice that this may cause a brief flicker as the license is released.
NOTE
The amount of time IIS takes to get around to garbage collection varies widely. To force this garbage collection to take effect immediately, Session.Abandon is used.
If these workarounds are not acceptable and you are developing your application with ASP version 3.0 on a Windows 2000 server you may want to consider the Session.Contents.Remove method to release licenses.
4/25/2003
Copyright 2002 Crystal Decisions, Inc. All Rights Reserved.
Page 7
cr85_asp_licensing.pdf
Session.Contents.Remove
In version 3.0 of ASP, the new method, Remove, was added to the Session.Contents object. Since ASP 3.0 was released with Windows 2000 and IIS version 5, applications running on Windows NT and IIS4 server will not be able to use this method. This new method allows you to remove session variables without abandoning the entire session. This makes it easy to remove the Crystal Reports session variables, free up the CAL, and leave the rest of the session variables intact. For more information on this method reference the Knowledgebase Article, c2009964, found by searching at http://support.crystaldecisions.com/kbase. This article provides the syntax for the method Session.Contents.Remove, and also provides the script for the modified Cleanup.ASP that is required..
http://support.crystaldecisions.com/
Email Support:
http://support.crystaldecisions.com/support/answers.asp
Telephone Support:
http://www.crystaldecisions.com/contact/support.asp
4/25/2003
Page 8
cr85_asp_licensing.pdf