DISPLAY external-form-item merges data into an HTML template file and sends the result to standard output.
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.
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.
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).
01 WEB-PAGE-1 IS EXTERNAL-FORM IDENTIFIED BY "webpage1". ... DISPLAY WEB-PAGE-1.
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).