Using Caché Server Pages (CSP)
Introduction to Caché Server Pages
[Back] [Next]
Go to:

Caché Server Pages (CSP) is both an architecture and toolset used to build an interactive CSP application. CSP technology allows you to build and deploy high-performance, highly scalable web applications. CSP lets you dynamically generate web pages, typically using data from a Caché database. “Dynamically” means that the same page may deliver different content each time it is requested from recently changed data sources.

CSP is versatile. It can
CSP is well-suited for database applications. In addition to providing rapid access to the built-in Caché database, it provides a number of features essential for Web-based database applications including
CSP supports two styles of web development.
CSP and Zen
Zen is an application framework for quickly creating data-rich web applications that is included with Caché and Ensemble. If you are building a new web-based application or enhancing an existing CSP-based application, look at the Zen framework in Using Zen.
To run Zen-based applications, it is necessary that you enable the Serve Files option and properly configure your web server. See the section Static Files in this book for more information.
Before You Start
This book assumes that you have a web server and Caché installed. This section describes what you need to do to be ready to create CSP applications.
Production Web Server and Caché-supplied Private Web Server
Caché supplies a minimal web server that runs the Management Portal, sometimes called the private web server. The private web server can also display the supplied CSP samples and run CSP pages. It cannot run robust CSP applications in a production environment. For that, you need to install a separate, full installation of a supported web server, such as Apache web server, Microsoft's IIS web server, or a Sun web server.
The private web server is based on a minimal build of the Apache web server. It is configured to listen on a non-standard TCP port, by default port number of 57772 (or another port that is not the usual, well-known, HTTP server port of 80). The private web server does not interfere with any other web server installation operating on the same host.
Private Web Server Not Provided on OpenVMS.
A private web server is not provided for OpenVMS. To access any CSP pages on an OpenVMS instance of Caché, an external web server must be configured. If you do not use the Caché installer to configure the web server (by selecting that option), you need to configure an external web server manually. For details, see Step #5 in the section “Installation on OpenVMS (All Connectivity Options)” in the CSP Gateway Configuration Guide.
If you are using a web server on a different operating system to access the Management Portal on the OpenVMS system, this external web server needs to be configured to serve static files through the CSP Gateway. For details, see the CSP Gateway Configuration Guide and find the section called “Registering Additional File Types with CSP” for the relevant operating system and option.
Configuring the Web Server and the CSP Gateway
The Caché installation performs web server and CSP Gateway configuration for common web servers and operating systems.
After installing Caché and the CSP Gateway, consult the CSP Gateway Configuration Guide to map file extensions for your system. This book also has configuration information for atypical CSP Gateway configurations.
To install the CSP Gateway on a remote server (that is, a system that is not running an instance of Caché), you can use one of two methods. On the remote server, you can run the
After installing the CSP Gateway, consult the CSP Gateway Configuration Guide to map file extensions for your system.
To prevent runtime errors, for High Availability configurations running over CSP, InterSystems recommends that you use a hardware load balancer with sticky session support enabled. For more information, see the section CSP Gateway Considerations in the Caché High Availability Guide.
What You Should Know
To be productive with CSP, you should have some familiarity with the following:
Some useful resources for learning HTML and JavaScript include:
CSP Samples
Caché comes with a set of sample CSP pages. To view these:
  1. Start Caché.
  2. To view the CSP samples, make sure that the web server on your machine is running.
  3. Start your browser and go to the CSP Samples Menu (Use either the private web server at: http://localhost:57772/csp/samples/menu.csp or your external web server at: http://localhost/csp/samples/menu.csp.
  4. If you installed Caché with normal or locked security features, a login page might be displayed. If so, log in.
  5. Caché displays a list of sample CSP pages along with a short description of each. Click on any that interest you.
CSP Documentation
Documentation on CSP can be found here:
To set up or configure CSP, see the following:
Creating Your First CSP Page
This section describes how to create a Hello, World CSP page in two different ways:
Creating a Class-based CSP Page
Create a CSP page by creating a subclass of %CSP.Page and overriding its OnPage method. Any output written to the principal device by this method is automatically sent to a web browser and displayed as a web page.
To create a Hello, World CSP page programmatically, do the following:
  1. Start Caché Studio.
  2. Select File > New Project to create a new project in the local database USER namespace.
  3. On the first page of the Wizard, enter Test as the package name and Hello as the class name
  4. On the second page, select CSP as the class type.
  5. Click Finish. You see the new CSP class definition in the Studio Class Editor:
    Class Test.Hello Extends %CSP.Page [ ProcedureBlock ]
        ClassMethod OnPage() As %Status
            ;To do...
            Quit $$$OK
  6. In the OnPage method, replace the comment:
     ; To do...
    With a Write statement:
     Write "<b>Hello, World</b>",!
  7. Save and compile the new class with Build > Compile.
You see Hello, World displayed in the browser.
This CSP page, which is also a CSP application works as follows:
  1. The browser sends a request for Test.Hello.cls to the local web server in the specified namespace.
  2. The web server passes this request to the CSP Gateway which passes the request to a Caché CSP server. In our case, the browser, the web server, and the Caché Application server are all running on the same machine. In a real deployment, these would probably be on separate machines.
  3. The CSP server looks for a class called Test.Hello and invokes its OnPage method.
  4. Any output that the OnPage method writes to the principal device (using the Write command), is sent back to the browser (via the CSP Gateway and the web server).
These example shows the heart of CSP; the rest of CSP's functionality is built on top of this behavior.
The following is an example of adding more code. Insert the following lines after the line containing Hello, World:
 Write "<ul>",!
 For i = 1:1:10 {
    Write "<LI> This is item ", i,!
 Write "</ul>",!
Now your page contains an unordered (bulletted) list of 10 items. Note that, in this context, Caché uses the exclamation point (!) character to write a carriage return to the principal device.
Creating an HTML Tag-based CSP Page
Another way to create a CSP page is to create an HTML file and let the CSP compiler transform it into a CSP class.
To create a Hello.World page using an HTML file, do the following:
  1. Start Caché Studio and select File > New > CSP File > Caché Server Page.
  2. Replace the contents of the new CSP file with the following:
    <b>Hello, World!</b>
  3. Select File > Save.
  4. In the displayed Save As window, double-click csp/usr, the default CSP application.
  5. Enter the filename Hello.csp and click Save As to save the file.
  6. In the Studio window, select View > Web Page.
As with the previous example, you see Hello, World! displayed in the browser.
A CSP application can consist of a single CSP page or a set of pages. A CSP application acts as a unit, using settings that apply to the whole application. The system provides csp/user as the default CSP application. For more information on CSP applications, see the section “CSP Application Settings” in this book.
You can also create an HTML file using a text editor or HTML editor. Save this file as Hello.csp in the local directory cachesys/csp/user (where cachesys is where you installed Caché).
The Hello.csp page works as follows:
  1. The browser sends a request for Hello.csp to the local web server
  2. The web server passes this request to the CSP Gateway (connected to the web server) which, in turn, passes the request to a Caché CSP server.
  3. The Caché CSP server looks for the file Hello.csp, and hands it to the CSP compiler.
  4. The CSP compiler creates a new class called csp.Hello with an OnPage method that writes out the contents of the Hello.csp file. (It actually generates a set of methods each of which are, in turn, called from the OnPage method). This compilation step only occurs when the .csp file is newer than the generated class; subsequent requests are sent directly to the generated class.
  5. The CSP server invokes the newly generated OnPage method and its output is sent to the browser as in the previous example.
As with the case of programmatic development, this is a purposefully oversimplified example included for pedagogical reasons. The CSP compiler is actually a specialized XML/HTML processing engine that can:
As with the programmatic example, you can make this page more interesting by adding programming logic. For example:
<b>Hello, World!</b>
<script language="Cache" runat="server">
 // this code is executed on the server
 Write "<ul>",!
 For i = 1:1:10 {
    Write "<li> This is item ", i,!
 Write "</ul>",!
As with the programmatic example, the resulting page displays an unordered (bulletted) list of 10 items.