Introduction to Caché Server Pages

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.

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:

• HTML v4.0.1 SpecificationOpens in a new tab

• HTML & XHTML: The Definitive GuideOpens in a new tab, published by O’Reilly.

• JavaScript: The Definitive GuideOpens in a new tab, published by O’Reilly.

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:

• Using Caché Server Pages describes how to create CSP pages

• Using ZEN describes how to use ZEN, a package that works on top of CSP for even more rapid web application development using prebuilt page objects. Zen documentation includes Using Zen Components, Developing Zen Applications, and Using Zen Reports.

• CSP HTML Tag Reference, a reference to all CSP tags

• CSP Samples Menu, shows many samples of CSP pages.

• Caché Server Pages Quick Start Tutorial gets you started.

• CSP Web Applications Tutorial is an in-depth tutorial.

• Class reference information for these classes:

  — %CSP.PageOpens in a new tab

  — %CSP.SessionOpens in a new tab

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