IS EXTERNAL-FORM Clause

General Format

[ IS EXTERNAL-FORM [ IDENTIFIED BY template-file-name ] ]
[ IS IDENTIFIED BY external-name ]

Syntax Rule

template-file-name and external-name are alphanumeric literals or unqualified data names. If a data name is used, it must refer to an unambiguous data item.

General Rules

1. The EXTERNAL-FORM clause associates a group item with HTML data using the Common Gateway Interface (CGI) specification. It allows you to define input and output records for HTML forms. The EXTERNAL-FORM clause affects the way ACCEPT and DISPLAY process the data item. It does not put any restrictions on the way that the data item may be used in your program.
2. An EXTERNAL-FORM data item is called an output form if the IDENTIFIED BY clause is used in the description of the group item. This clause associates the data item with an HTML template file. If the IDENTIFIED BY clause is omitted from the group item, the EXTERNAL-FORM data item is called an input form.
3. For input forms, the IDENTIFIED BY clause establishes an association between an elementary data item and a CGI variable. The value of external-name is the name of the CGI variable. If the IDENTIFIED BY phrase is omitted, then data item's own name (data-name) is used as the name of the CGI variable. If both the IDENTIFIED BY phrase and data-name are omitted, then the data item has no corresponding CGI variable.
4. CGI variables are case-sensitive. The runtime matches CGI names according to their case. However, if a CGI variable is not found using a case-sensitive match, then the runtime tries a case-insensitive match. Note that data-name is always treated as if it were upper case regardless of the case used in the COBOL source. The case of the value specified by the IDENTIFIED BY phrase is preserved.
5. The ACCEPT verb treats input forms and output forms in the same manner. ACCEPT sets the value of each elementary item, in order, to the value of its associated CGI variable. The CGI data is retrieved from the program's standard input. ACCEPT automatically decodes and translates the CGI input data before moving it to the elementary data item. The value of each CGI variable is converted to the appropriate COBOL data type when it is moved. If the CGI variable is empty or does not exist, ACCEPT sets the value of numeric data items to zero, and nonnumeric data items to spaces.
6. To receive a CGI variable that is repeated (this occurs when multiple items have been selected in a choose many list), you should use an elementary data item that is part of a table. Each occurrence of the data item receives one of the repeated values. The first occurrence receives the first repeated CGI item; the second occurrence receives the second repeated item; and so forth. Occurrences that do not correspond to repeated CGI items are set to zero if the data item is numeric, or spaces otherwise.
7. Data items are matched to CGI variables immediately before the particular CGI data item is retrieved. Thus it is possible for a form to have CGI variable names supplied by the CGI input itself. Consider:

   01  MY-FORM IS EXTERNAL-FORM
       03  CGI-VAR1 PIC X(20) IDENTIFIED BY "Name".
       03  CGI-VAR2 PIC X(50) IDENTIFIED BY CGI-VAR1.

   In this example, an ACCEPT MY-FORM statement would first locate the CGI variable called "Name" and move its value to CGI-VAR1. It would then locate a CGI variable identified by that value and move the corresponding value to CGI-VAR2. Note that, for this to work, you must specify CGI-VAR1 before CGI-VAR2 in MY-FORM, because ACCEPT updates the elementary data items in order.

8. The DISPLAY verb treats input and output forms differently. 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. There is virtually no limit to the length of a single HTML output line. No conversion is performed on the output form items before they are merged with the HTML template file.
9. 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.
10. template-file-name specifies the name of the HTML template file. You can 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).
11. You can omit the 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"

12. 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 it 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).
    
    ACCEPT CGI-DIRECTORY FROM ENVIRONMENT "PATH_TRANSLATED"
    SET CONFIGURATION "HTML_TEMPLATE_PREFIX" TO
       CGI-DIRECTORY.

13. The output from a CGI program must begin with a response header. DISPLAY automatically generates a Content-Type response header when template-file-name specifies a local file (i.e., not a URL - see rule #16 below).
14. 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 template-file-name. 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.

15. You may also specify a complete URL in template-file-name. 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 template-file-name is a URL, DISPLAY scans it for the string "://". DISPLAY does not apply HTML_TEMPLATE_PREFIX when 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).

16. 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.
17. Data items that do not have EXTERNAL-FORM specified are treated as regular data items by ACCEPT and DISPLAY, even if they are subordinate to an external form. For example:

    01  MY-FORM IS EXTERNAL-FORM.
        03  CGI-VAR1  PIC X(10)
        03  CGI-VAR2  PIC 9(5).

    Using this data structure, an ACCEPT of MY-FORM would fill in CGI-VAR1 and CGI-VAR2 with CGI data. An ACCEPT of CGI-VAR1 would simply get data from the user just as it does for any regular data item.