Skip to main content

This is documentation for Caché and Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

Please read this important announcement about the future of Caché and Ensemble maintenanceOpens in a new tab. Contact your account team to migrate to InterSystems IRIS.

Introduction to Caché Server Pages

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

  • Display inventory data that changes minute by minute.

  • Support web communities with thousands of active users.

  • Personalize pages based on user information stored in the Caché database.

  • Customize pages based on the user data to different users, depending on their requirements and their security permissions.

  • Serve HTML, XML, images, or other binary or textual data.

  • Deliver fast performance, because it is tightly coupled to the high-performance Caché database.

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

  • Session management

  • Page authentication

  • Ability to perform interactive database operations from in a web page.

CSP supports two styles of web development.

  • To develop applications using classes, CSP provides an object framework.

  • To develop applications using HTML files, CSP provides an HTML-based markup language that allows the inclusion of objects and server-side scripts within web pages. You can combine these two techniques within an application for maximum flexibility.

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.

Note:

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.

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

  • Caché installation script and select to install Web Server only or

  • Standalone CSPGateway installation script. The script asks for information about the remote Caché server: name, address, port, and optional password. The script automatically configures csp.ini based on this information.

After installing the CSP Gateway, consult the CSP Gateway Configuration Guide to map file extensions for your system.

Note:

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.

What You Should Know

To be productive with CSP, you should have some familiarity with the following:

  • Caché objects and ObjectScript

  • HTML

  • JavaScript

  • SQL

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.cspOpens in a new tab or your external web server at: http://localhost/csp/samples/menu.cspOpens in a new tab.

  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:

  • CSP Web Gateway Documentation, online help on configuring the CSP Gateway, is available on the CSP Web Gateway Management page. In the Management Portal, navigate to System Administration > Configuration > CSP Gateway Management and click Help. By default, this takes you to the private web server. To see the CSP Web Gateway Management page for your production web server, substitute localhost or localhost:<port_no> for localhost:57772 in the URL, for example:

    http://localhost/csp/bin/Systems/Module.cxw

  • CSP Gateway Configuration Guide, when you install Caché, the CSP Gateway is installed automatically and works for most sites. If you need to configure the CSP Gateway manually, use the advanced configuration guide.

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 with web page objects.

  • Creating an HTML-based CSP page using a marked-up HTML file.

Creating a Class-based CSP Page

Create a CSP page by creating a subclass of %CSP.PageOpens in a new tab 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 Studio.

  2. Select File > New Project to create a new project in the local database USER namespace.

  3. Select File > New > New Class Definition.

  4. On the first page of the Wizard, enter Test as the package name and Hello as the class name

  5. On the second page, select CSP as the class type.

  6. 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
    {
        &html<<html>
        <head>
        </head>
        <body>>
        ;To do...
        &html<</body>
        </html>>
        Quit $$$OK
    }
}

  7. In the OnPage method, replace the comment:

     ; To do...

    With a Write statement:

     Write "<b>Hello, World</b>",!

  8. Save and compile the new class with Build > Compile.

  9. Select View > Web Page

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 Studio and select File > New > CSP File > Caché Server Page.

  2. Replace the contents of the new CSP file with the following: 

    <html>
<body>
<b>Hello, World!</b>
</body>
</html>

  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:

  • Process server-side scripts and expressions in an HTML page

  • Perform server-side actions when certain HTML tags are recognized.

As with the programmatic example, you can make this page more interesting by adding programming logic. For example:

<html>
<body>
<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>",!
</script>
</body>
</html>

As with the programmatic example, the resulting page displays an unordered (bulletted) list of 10 items.

CSP ArchitectureNext section
Previous sectionAbout this Book
FeedbackOpens in a new tab