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

  • Troubleshooting
    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 Caché ObjectScript and converts it into the appropriate HTML to display on the page. However, after encountering a <script language="cache" runat="server"> tag, it simply looks for the first </script> tag to signify the end of the Caché ObjectScript code. If you wish to write code this way, there is a simple solution. Separate the </script> tag into two write statements as follows.
    <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 send an alert box to the user, the line alert(“Error!”) is simply written in the page. 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 Caché ObjectScript variables in an alert message?
    Answer:
    Use #()# syntax. From inside your Caché 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:
    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 Caché Terminal, issue the following command:
     d ^%ER
    To view the resultant error log, open the Caché Control Panel, expand Logs, Application Errors, and then 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.
    Question:
    I am getting the following error:
    HTTP Request failed. Unable to process hyperevent.
    What does this mean?
    Answer:
    Essentially, hyperevent errors occur when the browser needs to communicate with the CSP broker applet but cannot. This could be related to the code or your configuration. To quickly decide if the problem is your code, try loading http://localhost:1972/csp/samples/zipcode.csp. If Caché is installed remotely, replace localhost with the IP address or machine name. 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 it is likely a coding error.
    There are two important things to look for if the problem appears to be coding related. 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 Caché 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:
    By default, we do not keep the source code when we compile a CSP page. CSP pages are automatically compiled when you attempt to load them into a browser. To force Caché to maintain this source code, you can do one of two things:
    Once you have compiled your CSP page and requested that Caché keep the source code, you can find it as follows:
    Open Caché Studio and verify that you are in the correct namespace. On the File menu, click Open. In the Open dialog box, in the Files of type list, click Intermediate Routine (*.int). The file is named 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.
    For a list of all flags that can be added to the LoadPage command see the answer to the What are the flags? question.
    Question:
    When I run my CSP page, things like #(variable)# show 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 you are running your pages through your Web server as follows: http://localhost/csp/<namespace>/page.csp.
    If you are attempting to view your page from the Preview feature of Dreamweaver or by double clicking it in Windows Explorer, your CSP page is not parsed by the CSP Compiler. CSP pages cannot be viewed in this way. If you are not running a Web server, such as IIS or Apache, you need to get one. If you have problems setting it up, please contact the InterSystems Worldwide Response Center (WRC).
    Question:
    Why am I getting Invalid Character error messages when I attempt to load my CSP page?
    Answer:
    If you are not loading your page through your Web server, this error is common as the browser does not know how to represent your CSP syntax. If your URL looks something like C:/Cachesys/csp/user/mypage.csp, you are not loading through your Web server.
    Your URL should be something like http://localhost:1972/csp/user/mypage.csp.
    These messages may also result from #server()# calls which are not correctly translated to a Caché 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 it is properly formed as follows: #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 should be 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:
    Sessions and Licenses
    Question:
    How do I end a CSP session?
    Answer:
    CSP sessions can be ended by setting the %session.EndSession property to 1 in a Caché 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 merely closed the browser, CSP sessions do not expire until after the timeout period you have specified. Accordingly, licenses are not freed up until the session has expired. For more information about timeouts, see the next answer regarding changing the timeout.
    CSP also uses grace periods to allow users to recapture the same license if they come back within a set amount of time. The grace period is 5 minutes following %session.EndSession being set to 1. However, each license must be allocated to a CSP application for a minimum of ten minutes. Setting %session.EndSession to 1 can be done automatically following a timeout or manually by the application, for instance when the user clicks Logout.
    Examples:
    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 Webpage if their 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:
    Using “#()#”, replaces the expression inside the parenthesis with its run time value. Using “##()##”, 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 only changes when the page is recompiled.
    Question:
    What is the difference between using #server(..method())# and #call(..method())#?
    Answer:
    Both #server and #call directives must be called using JavaScript events or code.
    The #server directive relies on the CSP Event Broker to call a method on the server. It is dependent on this Java applet and therefore, may be browser dependent. Information can be sent back to the CSP page by quitting it from the method. It provides a synchronous method call. The user cannot do anything else on the page until the #server method has returned.
    Statements in the #call directive are executed via a hidden iFrame within your CSP page. Since it is not based on Java, it is not browser dependent. The #call mechanism provides an asynchronous method call and does not allow methods to quit/return values. The user can continue to work and even make changes to fields on the CSP page while a method called via #call is working in the background.
    For an example of using both #call and #server, see http://localhost:1972/csp/samples/zipcode.csp. For more detailed information, see Server-Side Methods in the “Tag-Based Development with CSP” chapter of Using Caché Server Pages (CSP).
    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, CSP pages are automatically compiled when loaded into the browser if they have changed (determined from a timestamp comparison.) You can also manually compile your CSP pages using Caché Studio or from the Caché Terminal.
    To compile your CSP pages using Studio:
    1. On the Tools menu, click Options, and then click the Class 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 use the “k” flag, which also tells the compiler to “Keep generated source code.”
    1. From the Terminal, ensure you are in the correct namepace. If not, change namespaces by entering:
      zn "<namespace>"
    2. For example:
      SAMPLES> do $System.CSP.LoadPage("/csp/samples/james.csp", "ck") 
    Question:
    What are the flags?
    Answer:
    For the most up-to-date and complete listing of the flags, run the following command at the Terminal:
     Do $System.OBJ.ShowFlags()
    Which outputs:
        a - Include application classes. This flag is set by default.
        b - Include sub classes.
        c - Compile. Use this flag while loading a CDL file will cause the 
            classes loaded to be compiled as well.
        d - Display. This flag is set by default.
        e - Delete extent.
        f - Force. Force a compilation even when classes are in use.
        h - Generate help.
        i - Validate XML export format against schema on Load.
        k - Keep source.  When this flag is set, source code of
            generated routines will be kept.
        l - Use lock while compilation classes.  This flag is set by default.
        p - Include percent classes.
        q - SQL-only compilation.
        r - Recursive.  It means include all the classes that are
            dependency predecessors.
        s - Include system classes.
        u - Update only.  It means do not compile classes that are up-to-date.
        v - Keep valid.  When combined with "f" flag, also keeps the objects valid
            after the compilation of the new classes.
        y - Include classes that are related to the current class in the way that
            they either reference to or are referenced by the current class in 
            SQL usage.
        4 - Export CDL compatible with version 4 from later version.
        o1- Optimize ..Property to i%Property where possible.
        o2- Optimize calls within this class, no incremental compile support.
        o3- Optimize calls within this class and to system classes.
        o4- Optimize calls to all classes, only works from CompileAll entry point.
    
    Default flags for this namespace =adlo1
    You may change the default flags with the SetFlags(flags,system) call
    
    Note:
    When using the “f” flag, after the compilation, the existing objects are no longer valid. The “v” flag is used in those cases where the user desires the objects to still be valid after class compilation.
    Question:
    There are a few utility methods I call all the time. How can I avoid using ##class(Package.Class).method()?
    Answer:
    If you place these methods in a particular class, you can have your CSP page inherit from that class. Your CSP page then has access to its methods 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:
    Using the Caché Configuration Manager:
    1. Click the CSP tab.
    2. Click Applications.
    3. If your application directory is not listed, click Add and enter the directory path in the Add New CSP Application dialog box.
    4. In the expanded list of settings for your application, set Recurse to “Yes”.
    5. Click OK and then Activate your changes when you exit the Configuration Manager.
    Question:
    I have Macromedia Dreamweaver MX for Windows. How do I configure it to work with CSP?
    Answer:
    Use the Macromedia Extension Manager to install the CSP extensions file (C:\CacheSys\Dev\csp\dreamweaver\CacheServerPagesMX.mxp) for use with Dreamweaver. Detailed instructions on how to install and use these extensions are contained in the Using CSP with Macromedia Dreamweaver appendix of Using Caché Server Pages (CSP).
    Question:
    I have Macromedia Dreamweaver version 4.0 or later for Windows. How do I configure it to work with CSP?
    Answer:
    Use the Macromedia Extension Manager to install the CSP extensions file (C:\CacheSys\Dev\csp\dreamweaver\CacheServerPages.mxp) for use with Dreamweaver. Detailed instructions on how to install and use these extensions are contained in the Using CSP with Macromedia Dreamweaver appendix of Using Caché Server Pages (CSP).
    Question:
    I have Macromedia Dreamweaver 3.0. How do I configure it to work with CSP?
    Answer:
    Download the Macromedia Extension Manager located at http://www.macromedia.com/exchange/dreamweaver/ and then follow the instructions in the Using CSP with Macromedia Dreamweaver appendix of Using Caché Server Pages (CSP) to install the CSP extensions file.
    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 Caché Configuration Manager 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:
    Please see the technical article entitled Using Caché Server Pages with a Remote Web Server.
    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.
    Calling your frameset page index.csp results in a single session and therefore 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:
    Please see the technical article on Character Sets and CSP.
    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:
    Since CSP and Crystal Reports both use the .csp file extension, there is a conflict with running 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 on the Crystal virtual directory and choose Properties.
      If Crystal Reports was installed last, right click on 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.