Using Caché Server Pages (CSP)
Frequently Asked Questions About CSP
[Home] [Back] 
InterSystems: The power behind what matters   
Class Reference   
Search:    

This Question and Answer Set includes the following topics:
  • Commands and Syntax
  • Configuration
  • Miscellaneous
  • Sessions and Licenses
  • Troubleshooting

  • Troubleshooting
    Question:
    How do I fix a Zen error about zenutils.js or other js file?
    Answer:
    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. Request Path: *.js 
      Module: CSPms 
      Name: CSP_js (or whatever else you want – any unused name works) 
    2. 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. Request Path: *.js 
      Module: CSPms 
      Name: CSP_js (or whatever else you want – any unused name works) 
    2. 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.
    Question:
    How do I debug a CSP page?
    Answer:
    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
    Question:
    Why does the following code not compile?
    <script language="Cache" runat="server">
        write "<script language=javascript>", !
        write "int x = 10; alert(x);", !
        write "</script>"
    </script>
    Answer:
    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>
    Question:
    When I use &js<alert(“Error!”);> to display an alert box, the text alert(“Error!”) is displayed instead of an alert box. Why?
    Answer:
    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.
    Question:
    How can I include ObjectScript variables in an alert message?
    Answer:
    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.Page class returns a properly quoted JavaScript string. It also correctly escapes any quotes contained within the returned result.
    Question:
    I am getting the following error:
    HTTP Request failed. Unable to process hyperevent.
    What does this mean?
    Answer:
    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.csp (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.csp), 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>
    Question:
    I received an error message that suggests a problem in a line of my routine, but I can’t find the INT routine. Where is it?
    Answer:
    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:
    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.
    Question:
    When I run my CSP page, #(variable)# shows up in the browser. Why isn’t this being replaced with the data in the variable?
    Answer:
    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.
    Question:
    Why am I getting Invalid Character error messages when I try to load my CSP page?
    Answer:
    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 a 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().
    Question:
    Why aren't my CSP tags being parsed?
    Answer:
    Your web server is not properly passing your CSP page to the CSP Gateway for parsing.
    Question:
    Does CSP log errors? How can I increase logging and where does the log exist?
    Answer:
    Question:
    When I try to load a CSP page, the following error appears:
    ERROR #5924: An error occurred and the specified error page could not be displayed - please inform the web master.
    What does this mean and how can I solve it?
    Answer:
    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, go to the View Application Error Log page in the Management Portal ([Home] > [System Logs] > [View Application Error Log]) 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
    Question:
    I try to display a CSP page and nothing comes up at all, or I get a login screen, enter a valid username/password, and it will not let me in. What is wrong? I am pretty sure that the CSP gateway is configured to talk to the correct Caché instance, or I am using private Apache install that came with Caché so it is preconfigured.
    Answer:
    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.
    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.
    Sessions and Licenses
    Question:
    Why do I have to log in so often?
    Answer:
    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:
    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.
    Question:
    How do I end a CSP session?
    Answer:
    To end a CSP session, set the %session.EndSession property to 1 in a ObjectScript method. If your CSP application times out, the session is ended automatically by your CSP class.
    Question:
    I closed my CSP session, but Caché still reports that I am using a license. Why?
    Answer:
    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:
    The following table summarizes how and when licenses are released:
    Case User has visited one page User has visited multiple pages
    The code explicitly sets %session.EndSession to 1 (for example, when the user clicks Logout) The session receives the grace period. The license is released when the grace period expires. The license is released immediately
    The browser is open and the session has not timed out The license is retained The license is retained
    The user closed the browser but the session has not timed out The license is retained The license is retained
    The session has timed out The session receives the grace period. The license is released when the grace period expires. The license is released immediately
    Here are some examples of how the grace period works when you have visited a single page:
    Question:
    How can I change the timeout for my applications?
    Answer:
    The default timeout on applications is set in each namespace to 900 seconds (15 minutes).
    Question:
    I want to perform cleanup or logging when a user CSP session times out. How can I do this?
    Answer:
    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:
    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).
    Question:
    How can I pass information between pages?
    Answer:
    There are a number of ways to pass information:
    Question:
    I want to forward the user to another web page if the session times out. How can I do this?
    Answer:
    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>
    
    Question:
    I want my page to automatically refresh every 60 seconds. How should I do this?
    Answer:
    In the head of your CSP page, use the following metatag:
    META HTTP-EQUIV="REFRESH" CONTENT="60; URL=mypage.csp">
    Commands and Syntax
    Question:
    How can I display a Caché variable or expression on my CSP page?
    Answer:
    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
    Question:
    What is the difference between “#(var)#” and “##(var)##”?
    Answer:
    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.
    Question:
    What is the difference between “#include” and “CSP:Include”?
    Answer:
    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.
    Question:
    How can I compile CSP pages?
    Answer:
    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. For example:
      SAMPLES> do $System.CSP.LoadPage("/csp/samples/james.csp", "ck") 
    Note:
    The “k” flag tells the compiler to “Keep generated source code.”
    Question:
    What are the flags and qualifiers?
    Answer:
    For a list of flags, run the following command in the Terminal:
     Do $System.OBJ.ShowFlags()
     
    Note:
    When using the f flag, after the compilation, the existing objects are no longer valid. Use the v flag if you want the objects to be valid after class compilation.
    For a list of qualifiers, run the following command in the Terminal:
     Do $System.OBJ.ShowQualifiers()  
     
    Question:
    There are a few utility methods I call all the time. How can I avoid using ##class(Package.Class).method()?
    Answer:
    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">
    Question:
    What is a private page?
    Answer:
    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>
    Question:
    I have a set of JavaScript functions and a header that I want on all my pages. How should I include this?
    Answer:
    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.
    Question:
    I want to use the <csp:search> tag, but I want to allow the user to search on fields other than ID. Can I do this?
    Answer:
    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.
    Configuration
    Question:
    How do I configure a CSP application to serve pages in a subdirectory?
    Answer:
    By using the Management Portal as follows:
    1. From the Caché cube, click Management Portal. Log in, if necessary.
    2. In the Management Portal, on the Web Applications page ([Home] > [Security] > [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.
    Question:
    I want my users to load my CSP application by pointing their browsers to: http://mydomain.com/banking/login.csp; I do not want /csp/ in the URL. How can I do this?
    Answer:
    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).
    Question:
    I have Caché on a different machine than my web server. How can I configure this?
    Answer:
    See the Connecting to Remote Servers chapter of the Caché System Administration Guide.
    Miscellaneous
    Question:
    Can I use frames in my CSP application?
    Answer:
    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.
    Question:
    How do I use a character set with CSP?
    Answer:
    Question:
    What HTTP header information is sent to the browser?
    Answer:
    You can view header information in two ways:
    Question:
    In addition to CSP, I am running Crystal Reports which also uses a .csp extension. How can I make my Caché Server Pages work?
    Answer:
    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.