The IS EXTERNAL-FORM clause associates a group item with HyperText Markup Language (HTML) data using the Common Gateway Interface
(CGI) specification. It allows you to define input and output records for HTML forms and is useful when your COBOL code is
part of an Internet-based application.
[ IS EXTERNAL-FORM [ IDENTIFIED BY template-file-name ] ]
[ IS IDENTIFIED BY external-name ]
external-name are alphanumeric literals or unqualified data names. If a data name is used, it must refer to an unambiguous data item.
- 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.
- 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 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
- 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).
- You can omit the suffix if it is either
.htm. If the suffix is omitted or is something other than
.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 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
- 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).
- 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".
- 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
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).
- 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.
- 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.