DISPLAY external-form-item

Format 16

DISPLAY external-form-item merges data into an HTML template file and sends the result to standard output.

DISPLAY external-form-item

Syntax Rules

external-form-item is an output record for an HTML 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. It may have one or more elementary items associated with HTML template fields. The association is made with the IS IDENTIFIED BY clause.

external-form-item may also be an input record for an HTML 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. See the General Rules below for more details. See Data Description Entry for information about how to declare external forms.

General Rules

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.
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.
You may specify a series of directories for locating HTML template files. To do this, use the HTML_TEMPLATE_PREFIX configuration variable. This variable is similar to FILE-PREFIX and CODE-PREFIX. It specifies a series of one or more directories to be searched for the desired HTML template file. The directories are specified as a sequence of space-delimited prefixes to be applied to the file name. All directories in the sequence must be valid names. 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 either .html or .htm. If the suffix is omitted or is something other than .html or .htm, 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 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 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).
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 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.
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.