This chapter covers the following topics:
For more information on installing and configuring the CSP Gateway with your Web server, reference Installing and Configuring the CSP Gateway.
CSP Components
The proper operation of CSP requires the cooperation of three individual components: the Web Server, the CSP Gateway, and the CSP Server:
CSP Components
You should be aware of these components, their roles, and how they are configured. This is summarized in the following table:
CSP Components
Component Roles Configuration
Web Server Grants access permission. Serves static (non-CSP) content. Virtual directories. Access control. Location of static content.
CSP Gateway Dispatches CSP requests to selected CSP Server. CSP Server(s) to connect to. Timeout and failover info.
CSP Server Processes CSP requests. Generates CSP classes from CSP files. URI directory to “application” mapping. Location of CSP files. Default settings for CSP applications.
These components are discussed in more detail in the following sections.
CSP Applications
CSP configuration is based on the concept of a “CSP application”. A CSP application is defined as the set of pages or classes that are addressed using a given URI path.
For example, all the CSP sample pages are considered to be part of the “/csp/ samples” application. An application may contain subdirectories, for example /csp/samples/cinema.
The following sections contain descriptions of how to configure a new CSP application, “/myapp”.
Web Server Configuration
Within a CSP application, the role of the Web server is to accept incoming HTTP requests, enforce access control (check permissions), serve static (non-CSP) content, and send any requests for CSP content (any file with a .csp or .cls extension) to the CSP Gateway installed on the Web server.
Configuration details vary among the different Web servers. Some, such as Microsoft IIS, use a directory-based permission scheme. Others, such as Apache, rely on the permissions defined by the executable programs used to serve data.
Apache Web Server
The Apache Web server is configured so that all requests for .csp and .cls files are redirected to the CSP Gateway. This is done within the Apache configuration file: /etc/httpd/conf/httpd.conf.
You do not have to reconfigure the Apache Web server if you add any new CSP applications; the default configuration is sufficient.
Microsoft IIS Web Server
Microsoft IIS, as well as Personal Web Server (PWS), is configured by defining a series of “virtual directories.” Each virtual directory consists of a name (which corresponds to the directory portion of a URI); a physical directory (the local directory in which static content, such as .html or .jpg files, is stored); and a set of permissions (such as “read” or “execute” ).
Any request (URI) for CSP content includes a directory name. This directory name must correspond to either a virtual directory defined by the Web server or a subdirectory of a virtual directory. This virtual directory must have at least “read” and “execute” privileges defined in order for CSP content to be served.
The “physical” directory defined for the virtual directory is used by the Web server to find any static content (such as .html or .jpg files) on the file system of the machine on which the Web server is running. Note that this physical directory is not used to locate .csp files; those are stored within the file system of the machine on which the Caché server is running. If both the Web server and Caché are running on the same machine (as may be the case during application development, for example) then both may coincidentally use the same location for static content and .csp files. This is how Caché configures both itself and the local Web server upon installation.
Upon installation, Caché detects if an IIS server is running and attempts to configure it to define a virtual directory named “/csp”. This is how requests to both “/csp/samples” and “/csp/user” (which are subdirectories of “/csp” ) are both sent to the local Caché installation.
If you decide to add a new CSP application, you do not have to perform any IIS configuration if the URI path for the new application also starts with “/csp”. For example, “/csp/myapp”, uses the IIS virtual directory defined for “/csp”. If you do not want your URI path to start with “/csp”, then you need to define a new virtual directory for IIS that corresponds to your URI path.
For example, to define a CSP application that uses the URI path “/myapp”, do the following:
  1. Invoke the IIS manager (note: every version of Windows has a unique way to do this; typically this is available via the Windows Control Panel).
  2. Define a virtual directory called “/myapp”
  3. Grant “read” and “execute” permissions for this directory.
  4. Specify the physical directory in which you plan to store static, non-CSP content.
    You also have to perform additional CSP Gateway and CSP Server configuration as described in the following sections.
Netscape Web Server
The NetScape Web server is configured so that all requests for .csp and .cls files are redirected to the CSP Gateway. This is done within the NetScape configuration file: <webserverdir>/httpd/config/obj.conf.
You do not have to reconfigure the NetScape Web server if you add any new CSP applications; the default configuration should be sufficient.
Caché HTTP Server
Caché includes a light-weight, built-in HTTP server. This HTTP server listens for, and responds directly to (without going through a Web server or the CSP Gateway), HTTP events on the default Caché TCP port (1972). The built-in HTTP server is included so that Web-based Caché services can run on systems on which there is no Web server present. These services include the Caché online documentation, the class reference, and Studio templates. In addition, you can use the built-in HTTP server to run the CSP sample applications and for testing CSP pages during development. You do not need to perform any configuration to enable the built-in HTTP server; simply make an HTTP request to the default Caché TCP port (1972):
http://localhost:1972/csp/samples/menu.csp
The built-in HTTP server supports only the most basic HTTP services and is not optimized for use by multiple users. CSP sessions are not supported by the built-in HTTP server; the Caché page is a separate session.
Note:
The built-in Caché HTTP Server is not intended for use as a Web Server; if you are developing Web-based applications or Web services, you should use a full-featured Web server, such as Apache. Moreover, in an actual deployment, you should place your Caché server behind a firewall; this makes the built-in HTTP server inaccessible to Internet clients.
CSP Gateway Configuration
The CSP Gateway is a DLL or shared library installed on and loaded by the Web server.
The CSP Gateway detects any requests for files with a .csp or .cls extension and sends them to a defined Caché server for processing.
CSP Gateway Manager
You can configure the CSP Gateway using the CSP Gateway Manager or by editing its configuration file directly. The CSP Gateway Manager is a small Web application that you can use from your browser. The URI used to locate the CSP Gateway Manager depends on the Web server you are using as listed below:
Note that you must replace “localhost” with the actual IP address of your Web server.
Note:
The links to the Gateway Manager listed above only work if you have the appropriate Web server installed on your system, and your Web server is on your local machine (localhost). If the links do not work, then enter the appropriate Gateway Manager URI within the address field of your browser.
Server Access
The CSP Gateway configuration lets you define a list of Caché servers. Each server is given a logical name, a TCP/IP address, a TCP/IP port number (the default is 1972), and a flag indicating whether the particular server is enabled or disabled. In addition, you can configure the minimum and maximum number of connections made to this Caché server as well as timeout and logging values.
By giving each server a logical name, the CSP Gateway makes it easy to connect applications to particular servers by name and later change the characteristics of a server in one place without having to reconfigure every application using the server.
Upon initial installation, the CSP Gateway has one logical server defined, “LOCAL”, which is defined to connect to the local copy of Caché.
Application Access
The CSP Gateway lets you configure how a particular CSP application connects to a Caché server. CSP considers all files within a particular URI directory (or subdirectory thereof) to be part of the same application.
Upon initial installation, the CSP Gateway has one application defined, “/csp”, which is defined to send all CSP requests to the logical server “LOCAL”. This is how requests to both “/csp/samples” and “/csp/user” are both sent to the local Caché installation.
If you decide to add a new CSP application, you do not have to perform any CSP Gateway configuration if the URI path for the new application also starts with “/csp”. For example, “/csp/myapp”, uses the CSP application defined for “/csp”. If you do not want your URI path to start with “/csp”, then you need to define a new CSP application within the CSP Gateway that corresponds to your URI path.
For example, to define a CSP application that uses the URI path “/myapp”, do the following:
  1. Invoke the CSP Manager page.
  2. Select “Application Access” from the menu to display the “Configure Application Access” page.
  3. Press the “Add Application” button to display the “Configure Application” page.
  4. Type “/myapp” into the “Application Path” field.
  5. Press the Submit button to save this new application configuration.
For details on the other fields on the “Configure Application” page, refer to its help page.
You also have to perform additional Web server and CSP Server configuration as described in their respective sections.
CSP Gateway Parameters
The CSP Gateway has a number of parameters that you can adjust. These include timeout values, failover and load-balancing characteristics, and CGI environment variables your application may be interested in.
For more details on these parameters refer to the help pages provided by the CSP Gateway Manager.
CSP Server Configuration
When a CSP Server receives an incoming HTTP request, it uses the local Caché CSP configuration settings to determine how this request should be processed. These settings are stored in the Caché configuration file (.cpf file) and be modified using the CSP tab within the Caché Configuration Manager.
The CSP Server configuration displays a tree of CSP applications organized by application name (URI directory). The tree is split into “Applications” (information about user applications) and “System” (information about the CSP-based utilities included with Caché).
For each application, the configuration holds the following information:
CSP Server Configuration Options
Field Description
Namespace The Caché namespace in which pages for this application are run.
Caché Physical Path The physical path (directory) on the Caché server in which CSP source files are stored. This path is relative to the <cachesys>/csp/ directory on the Caché server system.
Recurse Specifies whether to include subdirectories within this application. If UPath is the URI Path and PPath is the Physical Path, then with Recurse turned on, UPath/xxx/yyy looks for CSP files in PPath/xxx/ yyy. If Recurse is turned off, only files directly contained in UPath are used.
Auto Compile Specifies whether the CSP Server should automatically compile CSP source files or not. If this is turned on, then when a CSP file is more recent than its compiled class, it is recompiled. This is normally something you would turn on in development environments and turn off in production environments.
Event Class Specifies the default name of the CSP class (a subclass of %CSP.Page ) whose methods are invoked for CSP application events, such as a timeout or session termination. You can override this value using the EventClass property of the %CSP.Session object.
Default Timeout The default session timeout in seconds. You can override this value using the AppTimeout property of the %CSP.Session object.
Default Super Class The name of the default superclass used by the CSP Compiler for classes created from CSP files. If this field is not specified, the default value of “%CSP.Page” is used.
Use Cookies for Session Specifies how CSP keeps track of which session a browser is in. CSP tracks sessions by using a session cookie or by rewriting URIs sent to the client. This option lets you choose whether you want to a) always use cookies, b) never use cookies, c) use cookies unless the client browser has disabled cookies (auto-detect). Note that this option has nothing to do with whether or not an application uses cookies; it merely controls how CSP manages sessions.
Session Cookie Path Scope of the session cookie. This determines which URIs the browser will use to send the session cookie back to Caché. If your application name is “myapp”, it defaults to /myapp/ meaning it will only send the cookie for pages under /myapp/. You should restrict this to only what is required by your application to prevent this session cookie being used by other CSP application on this machine, or from being seen by any other application on this web server.
Serve Files Built-in Web server only. Allows the Web server built into Caché to serve up static content, e.g., .html or .jpg files, from this application path. This also allows the CSP stream server to serve files from this path.
Default Page Built-in Web server only. For the Web server built into Caché, this is the default page to display when you go to the root of this application URI and do not specify which page to show.
Custom Error Page The name of a .csp or .cls page that is displayed if an error occurs when generating a page within this application.
Package Name The name of an optional package prefix used by the CSP Compiler. This name is prepended to the package names used for classes created from CSP files. If this field is not specified, the default value of “csp” is used.
Defining a New Application on the CSP Server
To define a new CSP application named “/myapp” on a CSP Server, do the following:
  1. Run the Caché Configuration Manager and click the CSP tab.
  2. Click Applications and then click Add near the bottom of the dialog box.
  3. Type in the URI for the new application name, “/myapp” in this case, and click OK.
  4. Fill in the desired application properties (most are optional). The most important are the Caché Namespace in which this application is run and Caché Physical Path, the physical location of CSP files (if you are using HTML-based development).
  5. Exit from the Configuration Manager and click Activate Changes when you are prompted.
You also have to perform additional CSP Gateway and Web server configuration as described in the previous sections.
Copyright  © 1997-2010, InterSystems Corp.          Last updated: 2005-05-17 22:00:16 Source: GCSP_config.xml