You can use the DISPLAY statement to display records from many types of forms, including HTML, WML, and XML forms. To do so, use the following syntax:
DISPLAY external-form-item
where external-form-item is an output record for the form when used in a Common Gateway Interface (CGI) program. It is a group data item (declared with the IS EXTERNAL-FORM and IDENTIFIED BY clauses) that may have one or more elementary items associated with fields in an HTML, WML, or XML template. The association is made using the IS IDENTIFIED BY clause.
External-form-item may also be an input record for a form. In this case, the group item is declared with only the IS EXTERNAL-FORM clause. This is used primarily when you are debugging your CGI program.
The DISPLAY verb treats input and output forms differently. For output forms, DISPLAY merges the data contained in the elementary items into the associated template file and sends the result to the standard output stream in conformance with the CGI specification. To do this, DISPLAY scans the template file for data names delineated by two percentage signs on either side (i.e., %%dataname%%). It then replaces those data names with the contents of the associated elementary items from the output form, stripping trailing spaces.
The maximum length of a single line in the template file is 256 bytes. The maximum length of a single output line is 512 bytes. No conversion is performed on the output form items before they are merged with the template file.
You may specify a series of directories for locating template files. To do this, use the HTML_TEMPLATE_PREFIX configuration variable, even if you are specifying a directory for locating XML or WML templates. See Creating a Runtime Configuration File for Your CGI Program for details. For related information about file content, see also the configuration variable CGI_CONTENT_TYPE.
When associating the template file with the IS IDENTIFIED BY clause, you may omit the template file suffix if it is either ".html" or ".htm"; otherwise, you must include the suffix. If the suffix is omitted, DISPLAY first appends ".html" to the specified file name and tries to open it. If that fails, DISPLAY appends ".htm" to the file name and tries to open it. If that fails, DISPLAY tries to open the file exactly as specified. If all these attempts fail, the following error message is sent to the standard output stream in HTML format:
Can't open HTML template "template-file-name"
When the Web server executes your CGI program, the current working directory depends on the configuration of the specific Web server that is running. In many cases the current working directory is the same as the Web server's "root" directory. As part of the CGI specification, when the Web server executes your CGI program, it sets an environment variable called PATH_TRANSLATED to the directory containing your CGI program. You may want to use this information to locate your template files.
For example, if your template files are in the same directory as your CGI programs, set the HTML_TEMPLATE_PREFIX configuration variable to the value of PATH_TRANSLATED as follows:
01 CGI-DIRECTORY PIC X(100) VALUE SPACES. ... ACCEPT CGI-DIRECTORY FROM ENVIRONMENT "PATH_TRANSLATED". SET CONFIGURATION "HTML_TEMPLATE_PREFIX" TO CGI-DIRECTORY.
The output from a CGI program must begin with a "response header". DISPLAY automatically generates a "Content-Type" response header if the specified template file is a local file (i.e., not a URL).
You may specify the EXTERNAL-FORM clause for an item that has no subordinate items. This is useful for displaying static Web pages. To do this, specify the name of the static Web page in the IDENTIFIED BY clause. For example, if you have a Web page called "webpage1.html", add the following lines to your COBOL program:
01 WEB-PAGE-1 IS EXTERNAL-FORM IDENTIFIED BY "webpage1" ... DISPLAY WEB-PAGE-1.
You may also specify a complete URL instead of a template file name in the IDENTIFIED BY clause. In this case, DISPLAY generates a "Location" response header that contains the URL. This header specifies that the data you're returning is a pointer to another location. To determine whether the template file name is a URL, DISPLAY scans it for the "://" string. DISPLAY does not apply the HTML_TEMPLATE_PREFIX when the template file name is a URL.
For example, if your program determines that the information the user has requested is on another Web server, and its URL is "http://www.theinfo.com", add the following lines to your COBOL program:
01 THE-INFO-URL IS EXTERNAL-FORM IDENTIFIED BY "http://www.theinfo.com" ... DISPLAY THE-INFO-URL.
The length of the URL must not exceed 256 bytes.
Only one response header is sent to the standard output stream. Your CGI program should exit immediately after sending a location header (i.e., after displaying an external form identified by a URL).
You may use as many template files as you like in a single program. A common way to use multiple template files is to have three output forms:
a header, body, and footer. Each of these has a corresponding template file. You first display the header form, then move each row of data to the body form and display it, and finally display the footer form.
When an input form is specified in a DISPLAY statement, the names and values of each elementary item are sent to the standard output stream in the format specified by the CGI_CONTENT_TYPE variable (HTML, WML, XML, etc.). One line is generated for each elementary item. The line consists of the name of the item followed by " = ", followed by the first 100 bytes of the item's value. This can be useful when you are testing and debugging your CGI program.