Crystal Reports 8.

5 (Developer Edition only)

Managing RDC Licenses within your ASP Applications

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

Copyright 2002 Crystal Decisions, Inc. All Rights Reserved.

Page 1

Crystal Reports 8.5 (Developer Edition only)

Managing RDC Licenses within your ASP Applications

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

Web Reporting Methods

It is important to identify which method of web reporting you are using before preceding any further with this document. If you have installed Crystal Enterprise 8 from the second CD contained in the box and are running your reports through one of the following methods: Your web page hyperlinks to an report (.RPT) file Your application is written using Crystal Server Pages (.CSP) files ePortfolio is used to access reports Crystal Management Console is used to administer the system The Web Component Server and Page Server services are used to deliver reports

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

Copyright 2002 Crystal Decisions, Inc. All Rights Reserved.

Page 2

cr85_asp_licensing.pdf

Crystal Reports 8.5 (Developer Edition only)

Managing RDC Licenses within your ASP Applications

Licenses and the Developer version of Crystal Reports 8.5

With version 8.0 of Crystal Reports there was free runtime limited to 5 concurrent connections but the limitation was not "technical" (i.e. the application still functioned with more than 5 licenses being used.). However, with version 8.5 the ASP Server is "technically" limited to 5 concurrent connections and the 6th concurrent user will be denied access to the application (unless additional licenses are purchased and added to the default installation). Therefore, version 8.5 ASP applications must be able to effectively manage this new concurrent access.

What does Concurrent mean?

The licenses that come with Crystal Reports 8.5 are called Concurrent Access Licenses (CALs). These enable 5 web browsers to be viewing reports at the same time. Any number of users can have access to web reports, but only 5 at a time can be viewing. It is even possible for a single user to consume multiple licenses simply by opening multiple browsers and viewing reports in each one. You may find it necessary to educate users of your application not to open multiple instances of the browser.

How do I check on our number of licenses?

The number of users permitted to view reports at the same time is controlled using key codes. You will receive key code(s) from Crystal Decisions when you purchase your product, and you enter these key codes during installation. You can check your key codes and licenses using a Windows application that Crystal installs on your web server. Select Start > Programs > Crystal Reports Tools > Crystal Reports License and the Crystal Reports License screen should be displayed as seen below:

Crystal Reports License screen

4/25/2003
Copyright 2002 Crystal Decisions, Inc. All Rights Reserved.

Page 3

cr85_asp_licensing.pdf

Crystal Reports 8.5 (Developer Edition only)

Managing RDC Licenses within your ASP Applications

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.

Concurrent license status

The following two lines are the heart of the application that produces the RDC Runtime License Status report seen above: Set oApp = Server.CreateObject("CrystalRuntime.Application")

ASP APPLICATION HINT

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

Copyright 2002 Crystal Decisions, Inc. All Rights Reserved.

Page 4

cr85_asp_licensing.pdf

Crystal Reports 8.5 (Developer Edition only)

Managing RDC Licenses within your ASP Applications

Out of Licenses screen

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.

Managing License Usage within CR ASP Applications

The Crystal Reports Report Designer Component (Craxdrt.dll) is the engine used to run Crystal Reports from ASP pages. The Application and Report RDC objects must be created by your ASP application prior to actually running the report. A concurrent access license is used every time an instance of the Report object (oRpt) is created in memory. Conversely, destroying this session object (or taking it out of memory) will release the license again.
NOTE
Currently Crystal Decisions does not officially support using the RDC over the web without the use of session variables.

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

Crystal Reports 8.5 (Developer Edition only)

Managing RDC Licenses within your ASP Applications

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.

Releasing Licenses from your ASP application

When a user has finished viewing a report in your ASP application they will either leave the browser open and navigate to another website, leave the browser open in the background and use another application, or just close the browser. It is essential that the license that the user is holding during their session be released when they are finished with your application so that the next user can start to use it. There are basically three ways licenses can be released.

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

Crystal Reports 8.5 (Developer Edition only)

Managing RDC Licenses within your ASP Applications

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.

Session.Abandon side effects

If your application uses session variables that you require to stay in memory after releasing the license, Session.Abandon will destroy them. Workarounds to consider are: Store the session variables you need to keep in memory after releasing the license in a cookie. After your application calls Session.Abandon you can recreate your session variables and restore values from the cookie(s). This will only work for session variables that can be stored as strings. Keep the ASP pages that use the Crystal Reports session variables in one virtual directory, and your applications other ASP pages in another virtual directory. When Session.Abandon is called, only the session variables in the same virtual directory will be destroyed. However, because of this isolation, the session variables cannot be shared between the pages in the two virtual directories. This means that sharing information will need to be done by passing query strings or using cookies.

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

Crystal Reports 8.5 (Developer Edition only)

Managing RDC Licenses within your ASP Applications

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..

Further RDC Licensing Information

As the Out of Licenses message says, additional licensing can be purchased from Crystal Decisions through the eStore. It is important to note that Server Licenses can be purchased. Server Licenses enables an unlimited number of users (assuming your web server is robust enough) can view reports concurrently from a web server. If you have a Server License you dont have to be concerned about releasing viewer licenses efficiently. It is also possible to create ASP applications that enable your users to create new and alter existing reports using the RDC. This functionality requires alternate licensing. Contact your sales representative for more information or visit our website for contact information.

Contacting Crystal Decisions for Technical Support

We recommend that you refer to the product documentation and that you visit our Technical Support web site for more resources.
Self-serve Support:

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

Copyright 2002 Crystal Decisions, Inc. All Rights Reserved.

Page 8

cr85_asp_licensing.pdf