Frequently Asked Questions About CSP

The web server must be configured to serve .js files through the CSP Gateway. This is not done by the Caché installer, even when the option to configure the external webserver is selected, due to security concerns. For details, see CSP Gateway Configuration Guide. Find the section for your operating system and your configuration option. Then within your option, find one or both of the sections (depending on the option) called “Mapping the CSP File Extensions” and “Registering Additional File Types with CSP.”

On an Apache web server, add the following to the httpd.conf file (there are a few other ways, but this is easiest):

<Location /csp>
CSP On 
SetHandler csp-handler-sa 
</Location>

On IIS7, do the following:

1. Open the Control Panel. Select Admin Tools > IIS Manager.

2. On menu at left, expand yourcomputername > Sites > default website and click csp

3. On the right side of the screen, double-click handler mappings.

4. Scroll through the existing mappings, and make sure there is one with *.js in the path column.

If *.js is not there, you need to add it, as follows:

1. Click Add Module Mapping .

   Request Path: *.js 
   Module: CSPms 
   Name: CSP_js (or whatever else you want – any unused name works) 
   

2. Click Request Restrictions.

   Mapping: Uncheck Invoke handler only if request is mapped to
   Verbs: Select All verbs
   Access: Select Script
   

3. Repeat the above steps for *.gif, *.jpg, and *.svg.

On IIS6, do the following:

1. Open the Control Panel. Select Admin Tools > IIS Manager.

2. On menu at left, expand yourcomputername > WebSites > default website and click csp

3. Right-click CSP > properties.

4. On the Virtual tab, click Configuration.

5. Scroll through the list, and make sure that *.js is there.

If *.js is not there, you need to add it, as follows:

1. Click Add Module Mapping .

   Request Path: *.js 
   Module: CSPms 
   Name: CSP_js (or whatever else you want – any unused name works) 
   

2. Click Request Restrictions.

   Mapping: Uncheck Invoke handler only if request is mapped to
   Verbs: Select All verbs
   Access: Select Script
   

3. Repeat the above steps for *.gif, *.jpg, and *.svg.

Use the built-in Studio Debugger described in the chapter Using the Studio Debugger in the book Using Studio.

Don’t set breakpoints with Debug > View Breakpoints, as this seems error prone.

1. To debug CSP pages, you must check the option Tools > Options > Compiler > Keep Generated Source Code.

2. Open your Workspace window and add your CSP pages to the CSP folder, if they are not already there.

3. Compile your CSP and click the View Other Code icon in the toolbar (or select View > View Other Code). This lets you see the .cls and .int files. For example, the file A.CSP generates CSP.A.CLS and CSP.1.INT.

4. In the .cls or .int file, right click the line of code where you want a breakpoint and select Debug > Breakpoints > Toggle Breakpoint (or select the line and press F9).

5. Select Debug > Debug Target > ZEN or CSP page. From the dropdown, select the target CSP page on which the debugger will run and click OK. (If you dragged your CSPs to the Workspace window, they appear in the dropdown list.)

6. Click Go on the Debug toolbar.

For example, if you have a flow: A -> B; that is, display page A and then follow a link to page B. And there is a bug in page B, you would do the following:

1. Check that A.CSP and B.CSP are in the Workspace window.

2. Compile both.

3. Select View > Toolbars > Debug to open the Debug toolbar.

4. Select Debug > Debug Target > ZEN or CSP page. From the dropdown, select A.CSP and click OK.

5. Open B.CSP and select View > View Other Code to open csp.B.CLS.

6. In csp.B.CLS, right click the first line in the OnPageBODY() method and select Debug > Breakpoints > Toggle Breakpoint.

7. Click Go on the Debug toolbar.

8. Page A is displayed.

9. Click the link that brings up page B.

10. The debugger stops on the breakpoint in B

When compiling a CSP page with runat="server" in a script tag, the compiler runs the ObjectScript and converts it into HTML to display on the page. However, after encountering a <script language="cache" runat="server"> tag, it looks for the </script> end tag to signify the end of the ObjectScript code, which, in this case, it finds in the write statement. To get this to compile, break the </script> tag into two write statements:

<script language="Cache" runat="server">
    write "<script language=javascript>", !
    write "int x = 10; alert(x);", !
    write "</script",">", !
</script>

It is possible that you put this line inside a runat=“server” code section or inside a method called from a runat=“server” block. To execute JavaScript as the page loads, add the <script language=“javascript”> tag as shown in the previous answer.

The code &js<alert(“Error!”)> works inside a server side method called via a JavaScript event from the loaded page.

Use #()# syntax. From inside your ObjectScript method, try something like this:

 s error = "Bad password"
 &js<alert(#(..QuoteJS(error))#);>

The QuoteJS method provided by the %CSP.PageOpens in a new tab class returns a properly quoted JavaScript string. It also correctly escapes any quotes contained within the returned result.

Hyperevent errors occur when the browser tries to communicate with the CSP broker applet but cannot. This could be related to the code or your configuration. To decide if the problem is your code, load http://localhost:57772/csp/samples/zipcode.cspOpens in a new tab (where 57772 is the Caché web server port number. Replace 57772 with the actual web server port, if necessary, or leave it out if you have an external web server running (http://localhost/csp/samples/zipcode.cspOpens in a new tab), or if Caché is installed remotely, replace localhost with the IP address or machine name.)

On the zip code page, click #server, and enter a zip code, such as 02142, in the Zip box and press Tab. If you do not receive a hyperevent error, you are properly configured and your hyperevent error is likely caused by a coding error.

If the problem appears to be coding related, there are two things to look for. Never use #server calls as the page is loading. This includes calling them in the OnLoad event of the <body> tag, either directly or from a JavaScript method called in OnLoad. It also includes calling them from inside an &js<> line of a runat="server" code block. If you need to call a method as the page loads, use ObjectScript syntax inside a runat="server" block.

<script language="cache" runat="server">
    // if method is located in the page or in a class the page inherits from
    d ..mymethod()
    // if class cannot be called using dot syntax
    d ##class(User.MyClass).mymethod()
</script>

Depending on your current settings, you might not keep the source code when you compile a CSP page. To force Caché to maintain this source code, you can do one of two things:

• Compile your CSP pages from the Studio with Keep Generated source code selected. In Studio, click Tools > Options > Compiler > General Flags. Select the Keep generated source code check box. Then, to compile your CSP page, click Build > Compile.

• Compile your CSP pages from the Terminal using the k flag to Keep generated source code. From the Terminal, verify you are in the correct namepace. (If not, change namespaces by entering: Zn “<namespace>”.) To compile your CSP page, enter: Do $System.CSP.LoadPage(“/csp/<namespace>/<pagename>.csp”, “ck”). For example:

   Do $System.CSP.LoadPage("/csp/samples/james.csp", "ck")
  

  

To find the generated source code:

Open Studio and verify that you are in the correct namespace. Click File > Open. In the Files of type list, click Intermediate Routine (*.int). Find csp.<csp_page_name>.x.INT, with x being the number of this routine in the series. Large CSP pages are broken into multiple INT routines. The number of the file containing the error is shown in the error message you originally received.

This indicates that your CSP page has not been properly parsed by the Caché CSP Compiler. Ensure that you are running your pages through your web server as follows: http://localhost/csp/<namespace>/page.csp.

If you are not loading your page through your web server, this error is common because the browser does not know how to represent your CSP syntax. If your URL looks something like C:/install-dir/csp/user/mypage.csp, you are not loading through your web server.

Your URL should be something like http://localhost:57772/csp/user/mypage.csp or http://localhost/csp/user/mypage.csp.

These messages can also result from #server()# calls which are not correctly translated to an ObjectScript method call. From your browser, right-click and view the source of your page. If the source still contains #server, your syntax may be incorrect. Ensure that it is properly formed as: #server(..methodname())#.

If you are passing strings to the method, they must be inside double quotes (“”). Once your CSP page is compiled into HTML, all #server()# calls are translated into a call to csprunservermethod().

Your web server is not properly passing your CSP page to the CSP Gateway for parsing.

• If there is an internal error, such as an error in your custom error page, it is logged to the BACK^%ETN error log. If you receive internal errors in this log that are not related to your custom error page, it may be a problem with the core CSP engine and you should contact the InterSystems Worldwide Response Center (WRC)Opens in a new tab.

• Other errors are logged by calling the user-defined error page where the user can add their own logging function.

This error can result from a number of different issues. View the error log to get more specific information about the actual error that occurred. In the Terminal, issue the following command:

 d ^%ER

To view the resultant error log, navigate to System Operation > System Logs > Application Error Log in the Management Portal and check the errors for the appropriate namespace. The errors are contained in folders by date.

If you set up a custom error page, this could mean that your custom error page has no mechanism to deal with an error in the page you are calling. It could also mean that your custom error page itself generated an error. One way to trace this error is to temporarily turn off your custom error page and attempt to load the CSP page.

If your CSP pages work locally, but not when called from another computer, it may be that you have a Single User version of Caché or do not have a Caché license. Calling CSP pages from a remote machine requires both a full version of Caché and a valid key with licenses available. Adding a Caché key to a version you have downloaded from the Internet does not give it full functionality. You still need to receive a full version. See also Error 5924 in Appendix B Error Notes

Make sure that auditing of security events is turned on from the %SYS namespace. At the very least, audit Login, Logout and LoginFailure.

1. In the terminal, in the %SYS namespace, enter Do ^SECURITY.

2. Select Auditing setup, Configure auditing events, and Create audit event.

3. Enter %SYSTEM/%Login/Login, %SYSTEM/%Login/Logout, and %SYSTEM/%Login/LoginFailure.

Try accessing the CSP page again and check the audit log to see if you can see any failures. Often this will tell you what the problem is - such as a disabled service, an incorrect password, or that you do not have permission to run this CSP application. For more information on auditing, see the chapter “Auditing” in the Caché System Administration Guide.

In previous releases, when applications shared a session, they could share authentication and data only via the session object.

There are two ways to share a session:

• Via the session cookie path.

• Putting CSPSHARE=1 in the link to the application page.

When the session times out, it is destroyed and its authentication is lost. If an existing page is reloaded, the user has to login again. For applications connected via the session cookie path, they are 'logged in' also, because when you go to a page from one of those applications you get the newly logged-in session.

Not so when sessions are shared via CSPSHARE=1. For example, start an application called SMP which is logged into session X. Now click a link to another application called EMP. That link contains CSPSHARE=1. EMP does not have to log in as it is put into authenticated session X. After a while session X times out and is destroyed. SMP and EMP are without sessions.

Now click a tab containing a page from SMP and, as before, we are asked to log in again. SMP is now in authenticated session Y. We then click a tab containing a page from EMP. There is now no connection between SMP and EMP. EMP is asked to log in again and is put in authenticated session Z.

CSPSHARE is a very fragile way to try to share sessions and is easily severed. Once severed, multiple logins can ensue.

In this release: Use session-sharing only if you decide that data must be shared via the session object. If you need only authentication sharing (and not data sharing), use other options.

Session—Sharing : If you require session sharing, it is best to name all applications with the same Session Cookie Path (which now must be an exact match). You may have to rename your applications, such as, /csp/sys/tool/smp and /csp/sys/tool/emp.

If you require session sharing and you can’t name all applications with the same Session Cookie Path, then use the CSPSHARE element. However, previous idiosyncrasies, such as multiple logins after time out, will contain to manifest themselves.Use CSPSHARE as a last resort.

Authentication-Sharing: If the design calls for sharing authentication information, but does not require sharing session data, use one of the new authentication features.

• Login Cookies [Share Authentication when Enter Application]

  Login Cookies hold information about the most-recently logged in user. When they are enabled, a newly— accessed application tries to use that authentication.

  For Login Cookies, each application is in a separate session. These sessions are independent once that session has been authenticated. So logging out or timing out in one session does not affect the other sessions.

  Unauthenticated logins are not saved in the Login Cookie. If application A logs in to user Q, then application B as unauthenticated, then application C uses login cookies, application C will be logged in as Q.

• Group-By-Browser [Share Authentication Continuously]

  If you want a group of applications to act as an authentication cluster, then use group-by-browser.

  All applications stay in authentication sync. If one logs out, they are all logged out. If one logs into user Q, they are all logged into user Q. (The only exception is that if any applications are unauthenticated, they are treated as pariahs and ignored as far as authentication is concerned.)

To end a CSP session, set the %session.EndSession property to 1 in an ObjectScript method. If your CSP application times out, the session is ended automatically by your CSP class.

If you have visited only a single page and you logout or the session times out, CSP provides a grace period of 5–10 minutes, during which it reserves the license for you, so that you can recapture the same license if you return quickly. The grace period is the longer of:

• 5 minutes from the end of the session (a timeout or a logout) or

• the amount of time that would ensure 10 minutes from when the session started (ensuring a minimum session of 10 minutes)

The following table summarizes how and when licenses are released:

Here are some examples of how the grace period works when you have visited a single page:

• The user logs in at 12:00 and logs out at 12:15. The grace period is 5 minutes, so the license is free at 12:20.

• The user logs in at 12:00 and logs out at 12:03. The minimum license use time is 10 minutes, so the license is free at 12:10.

• The user logs in at 12:00 and closes the browser at 12:10. The timeout is set to 15 minutes, so the session ends at 12:25. The grace period is 5 minutes, so the license is free at 12:30.

The default timeout on applications is set in each namespace to 900 seconds (15 minutes).

• To change the Timeout for all CSP pages within a certain namespace:

  1. From the Caché cube, click Management Portal. Log in, if necessary.

  2. On the main page of the Management Portal, navigate to System Administration > Security > Applications > Web Applications.

  3. On the Web Applications page, click Edit for the CSP application to configure.

  4. In the Default Timeout field, enter a new value (in seconds) and click Save.

• To change the Timeout for a specific application, put the following inside your page, where x is the timeout value in seconds.

  s %session.AppTimeout = x
  

  

1. Create an event class with an OnTimeout class method.

2. Specify this as the event class for your application in one of the following ways:

   • In the Management Portal, navigate to System Administration > Security > Applications > Web Applications, click Edit for the CSP application to configure. In the Event Class field, enter the class name to use, such as User.MyEventClass.

   • In your CSP page, use the %session.EventClass property:

     <script language="cache" runat="server">
     s %session.EventClass = "User.MyEventClass"
     </script>

     

3. In your OnTimeout method, log any information you wish to keep.

   Note:

   At this point you cannot send information back to the browser (alerts or redirects).

There are a number of ways to pass information:

• Put the information in the links to the next page as additional parameters. These are accessible from the %request object:

  http://myserver/csp/user/mypage.csp?id=3&name=bill
  

  

  To access the information, use %request.Get(“id”).

  To display the information directly on your page, use #(%request.Get(“name”))#.

• Use the %response.Context multidimensional property to define a set of name-value pairs that are automatically added to all links and forms by the CSP engine.

• Put the data in the %session object. This can cause problems if the user opens the application in two browsers at the same time.

The easiest way to accomplish this is to set up a redirection in a metatag to occur just after your timeout:

<html>
<head>
<META HTTP-EQUIV="REFRESH" CONTENT="910;
 URL=youhavetimedout.csp">
</head>
<body>
<script language="cache" runat="server">
        %session.AppTimeout = 900
</script>
</body>
</html>

In the head of your CSP page, use the following metatag:

META HTTP-EQUIV="REFRESH" CONTENT="60; URL=mypage.csp">

The %SYS.cspServer and %SYS.cspServer2 routines are the server routines that process CSP requests.

%SYS.cspServer3 handles asynchronous communication with the CSP Gateway, that is, whenever the Caché instance needs to exchange information with the gateway outside of the context of a user request. For example, this is needed for asynchronous web socket requests and interactions using the Gateway Manager interface (%CSP.Mgr.GatewayMgr, which is used by ^CSPGWMGR and CSPButtons).

There are two types of CSP Gateway processes:

• Processes that serve CSP requests (sometimes known as worker processes). These processes use %SYS.cspServer and %SYS.cspServer2. These processes are in %SYS.cspServer2 while they are idle and waiting for a new request; when serving a request, they can be in any routine.

• Processes that manage the gateway (sometimes known as server processes). These processes are in %SYS.cspServer3 while idle.

The number of worker or server processes that exist on the system vary. The number depend on the configuration of the web server(s) that are connected to Caché and the number of concurrent requests (that is, the load) that those web servers are receiving.

Typically, there is one server process for each web server process that has a connection to Caché. However, other factors can affect this:

• More than one web server can be connected to a single instance.

• Each web server can have multiple processes.

For example, for Apache, when using the Prefork Multi-Processing Module (MPM), the default behavior is to use one web server process for each connection. In contrast, the worker and event MPMs use multiple connections under the same webserver process; this is why these modules are recommended for use with CSP, rather than Prefork. On Windows, the IIS application pool typically runs in a single process, but it can be configured to use multiple processes.

A webserver has settings to control the number of worker processes. In CSP, each webserver worker process is associated with a connection to Caché and a Caché worker process (for example, a %SYS.cspServer2 process). The webserver dynamically scales up the number of workers (up to the configured limit) based on load. There are also settings to control when these workers are closed down, but this typically does not happen quickly. This is entirely controlled by the underlying webserver, not the Web Gateway.

It is important to note that the Caché worker processes can serve any incoming request and are not associated with a particular user session. (The exception to this rule is a CSP application using State Aware or Preserve mode sessions, which is a very old configuration option and is not recommended). The number of worker processes on a system roughly matches the maximum number of concurrent requests that the server has recently received. There is no relation between the number of worker processes and the current number of sessions. There can be many more worker processes than active sessions and there can be many more active sessions than worker processes — it all depends on the application behavior.

Note also that CSP worker and server processes do not consume a license. The license is associated with the CSP session.

No, the license is associated with the CSP session. CSP processes themselves, such as CSP worker and server processes, do not consume licenses.

A variable or expression can be incorporated into the page at runtime using “#(var)#” or “#(expression)#”. For example:

#(name)#, where name has been set

#($G(%request.Get(“Username”)))#, retrieves Username from the URL

#(2+7+3)#, displays 12 on the Webpage

The syntax “#()#” replaces the expression inside the parenthesis with its runtime value. The syntax “##()##” replaces the variable or expression with its value when the page is compiled.

To illustrate the difference, place the following code sample inside a CSP page:

Runtime: #($P($H,",",2))#
Compile Time: ##($P($H,",",2))##

Open the page in a browser and refresh it a few times. Notice that the Runtime value changes each time the page is refreshed. The Compile Time value retains the time the page was compiled; it changes only when the page is recompiled.

The #include directive allows you to include in your page any text: JavaScript, html, plain text, CSP.

The <csp:include> tag includes a properly formatted CSP page; it uses ServerSideRedirect to insert this page and then return to processing the original page.

By default, the browser automatically compiles CSP pages when it loads them, if the pages have changed (based on their timestamp). You can also manually compile your CSP pages in Studio or from the Terminal. In either case, you can control whether to keep the generated source code.

To compile your CSP page using Studio:

1. On the Tools menu, click Options, and then click the Compile tab.

2. Select the Keep generated source code check box and click OK.

3. Compile your CSP page from the Build menu by clicking Compile.

To compile your CSP page from the Terminal:

1. From the Terminal, ensure that you are in the correct namespace. If not, change namespaces by entering:

   zn "<namespace>"
   

   

2. Type: do $System.CSP.LoadPage(“/csp/<namespace>/<pagename>.csp", "ck")

   For example:

   SAMPLES> do $System.CSP.LoadPage("/csp/samples/james.csp", "ck") 
   

   

For a list of flags, run the following command in the Terminal:

 Do $System.OBJ.ShowFlags()

For a list of qualifiers, run the following command in the Terminal:

 Do $System.OBJ.ShowQualifiers()  

Place these methods in a particular class and have your CSP page inherit from that class. Your CSP page can then access these methods by using dot syntax. To do this, use the <csp:class> tag as follows:

<csp:class super="%CSP.Page,App.Utils">

A private page can only be viewed when called from another CSP page using the proper token. A private page cannot be bookmarked or arrived at by simply typing its URL into the browser. To set a page as private, use the <csp:class> tag as follows:

<csp:class private=1>

Use the new #include syntax:

<!--#include file="mystuff.inc"-->

This is a textual include, new in Caché 5. The text of the file is automatically included in the page before the page is compiled. Therefore, you can include code that needs to be compiled such as #()# variables, the results of <csp:query> queries and runat="server" code.

The <csp:search> tag has a WHERE attribute which allows you to specify a comma-delimited list of fields on which to search.

<csp:search name=mySearch where="Name,Gender" CLASSNAME="Sample.Person">

There are several other attributes you can use to customize your <csp:search> functionality. See the <CSP:SEARCH> entry of the CSP HTML Tag Reference guide.

By using the Management Portal as follows:

1. From the Caché cube, click Management Portal. Log in, if necessary.

2. In the Management Portal, navigate to System Administration > Security > Applications > Web Applications, click Edit for the CSP application to configure.

3. On the Web Applications page, click Edit for the CSP application to configure.

4. On the Edit Web Application page, set Recurse to Yes.

5. Click Save.

Use the Management Portal to set up a new CSP application called, for example, /myapp. This process is described in the “Defining a New Application on the CSP Server” section of the CSP Configuration chapter of Using Caché Server Pages (CSP).

See the “Connecting to Remote Servers” chapter of the Caché System Administration Guide.

Yes. However, you should name the frameset page with a .csp extension. If you create a page called index.html and load CSP pages into the left and right frames, you use two sessions and accordingly two Caché licenses, one for each CSP page. This can cause confusion if you use the session object to store information and you also use unnecessary licenses.

If you call your frameset page index.csp, the result is a single session, which uses one license for that application. Both CSP pages within the frames share this session and any information stored in it.

You can view header information in two ways:

• Display your page in the Terminal using the Show method:

    D $System.CSP.Show("/csp/user/mypage.csp")
  

  

  This displays the HTTP headers, as well as the generated HTML source for the page.

• Use the Head method of the %Net.HttpRequestOpens in a new tab class.

      set http = ##class(%Net.HttpRequest).%New()
      set http.server = "localhost"
      set http.Port = 57772
      do http.Head("csp/samples/loop.csp")
      do http.HttpResponse.OutputToDevice()
      set http = "" 
  

  

Because CSP and Crystal Reports both use the .csp file extension, there is a conflict if you run both through your web server. Whichever was installed later works, but the earlier application does not. To alleviate this conflict, configure your web server to run one virtual directory for CSP and another for Crystal Reports.

To configure virtual directories using the Internet Services Manager:

1. From the Start menu, point to Settings, Control Panel, Administrative Tools, and then click Internet Services Manager.

2. Expand the first node, and then expand Default Web Site.

3. If CSP was installed last, right-click the Crystal virtual directory and choose Properties.

   If Crystal Reports was installed last, right-click the csp virtual directory and choose Properties.

4. On the Virtual Directory tab of the Properties dialog box, click Configuration in the lower right portion of the box.

5. Click the App Mappings tab and scroll down to find the .csp mapping located near the bottom of this list.

6. If you installed CSP last, change the Executable Path for the .csp extension mapping to the location of the Crystal Reports DLL, WSCInSAPI.dll. It is located in the WCS directory of the Crystal install directory. (For example, C:\Program Files\Seagate Software\WCS)

   If you installed Crystal Reports last, change the Executable Path for the .csp extension mapping to the location of CSPms.dll, located in the /csp/bin directory of your Caché install directory. (For example, C:\CacheSys\CSP\bin).

7. Click OK.