Contributed by: remy Saturday, 18 June 2016, 16:08 @ CEST
General Rules (DISPLAY external-form-item)
(1) An external form is called an output form if the IDENTIFIED BY clause is used to associate it with an HTML template file. If the IDENTIFIED BY clause is omitted, it is called an "input form". For example, the following is an input form:
01 CGI-FORM IS EXTERNAL-FORM.
03 CGI-VAR1 PIC X(10).
03 CGI-VAR2 PIC X(10).
And here is an output form:
01 HTML-FORM IS EXTERNAL-FORM IDENTIFIED BY "tmplate1".
03 HTML-VAR1 PIC X(10).
03 HTML-VAR2 PIC X(10).
The DISPLAY verb treats input and output forms differently. Input forms are discussed in rule (7), below. For output forms, DISPLAY merges the data contained in the elementary items into the associated HTML template file and sends the result to the standard output stream in conformance with the CGI specification. To do this, DISPLAY scans the HTML template file for data names delineated by two percentage signs on either side (i.e. %%data-name%%). It then replaces those data names with the contents of the associated elementary items from the output form, stripping trailing spaces.
(2) The maximum length of a single line in the template file is 256 bytes. The maximum length of a single HTML output line is 512 bytes. No conversion is performed on the output form items before they are merged with the HTML template file.
(3) You may specify a directory for locating HTML template files. To do this, use the HTML_TEMPLATE_PREFIX configuration variable. It specifies a directoriy to be searched for the desired HTML template file. A directory must be a valid name. The current directory can be indicated by a period (regardless of the host operating system).
You may omit the template file suffix if it is .tpl. If the suffix is omitted, DISPLAY first appends .tpl to the specified file name and tries to open it. If the attempt fails, there will be no error message and nothing will be output to the standard output stream in HTML format:
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 HTML template files. For example, if your template files are in the same directory as your CGI programs, then 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--see rule 5 below).
(4) 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".
(5) 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"
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).
(6) You may use as many HTML template files as you like in a single program. A common way to use multiple HTML template files is to have three output forms: a header, body, and footer. Each of these has a corresponding HTML 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.
(7) 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 HTML format. 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.