Environment Variables

Environment variables are system variables that exist within a particular computer user’s environment. With regard to a web server, the full set of environment variables is recreated each time a CGI process is executed. You can think of these variables as placeholders that a web server uses to pass data about an HTTP request from the server to the CGI-processing application, i.e., your CobolScript program.

With CobolScript, environment variables are accessed with the GETENV command:

GETENV USING <environment variable> <cobolscript variable>.

The names for environment variables are system-specific. Fortunately, most web servers have adopted many of the same names. Here are a few of the standard ones; experiment with these variables in the GETENV statement to determine the formats of the contents of each of these variables:

Environment Variable

Description

CONTENT_LENGTH

Size of the attached incoming CGI data in bytes (characters).

CONTENT_TYPE

The MIME type of the incoming CGI data

PATH_INFO

Path to be interpreted by the CGI application.

PATH_TRANSLATED

The virtual-to-physical mapping of the file on the system.

QUERY_STRING

The URL-encoded string that was submitted to the web server

REMOTE_ADDR

The IP address of the agent making the CGI request.

REMOTE_HOST

The fully qualified domain name of the requesting agent.

REMOTE_IDENT

Data reported about the agents’ connection to the server.

REMOTE_USER

The User ID sent by the client agent.

REQUEST_METHOD

The request method used by the client. For CobolScript applications, this should be “POST”.

SCRIPT_NAME

The path identifying the CGI application requested.

SERVER_NAME

The server name of the requested URL. This will either be the IP address of the server or the fully qualified domain name.

SERVER_PORT

The port where the client request was received by the server.

SERVER_PROTOCOL

The name and revision of the request protocol.

Environment Variable

Description

SERVER_SOFTWARE

The name and version of the server software. For example: “OmniHTTPd/1.01 (Win32; I386)”

Some web servers do not support all of these environment variables. You should consult your web server documentation to find out what environment variables are supported by your specific web server.

All normal web servers support the CONTENT_LENGTH environment variable. Because of this, we recommend getting this variable when your CobolScript application is first invoked via a web server, like this:

GETENV USING `CONTENT_LENGTH` content_length.

IF content_length > 0

ACCEPT DATA FROM WEBPAGE

END-IF.

By doing this, you will know if a form was submitted to your application or not. If your application was called directly from a typed URL, outside of a form submission, the value of CONTENT_LENGTH would be 0 and you would not need to accept CGI data from the web server. Normally, when the ACCEPT DATA FROM WEBPAGE statement is executed, CobolScript will begin reading data from the CGI stream and place the contents in the appropriate CobolScript variables. Of course, it’s not necessary to do this if no CGI data has been sent to the web server.

Sometimes, web servers are configured to not populate certain environment variables such as REMOTE_HOST. This is often done because there is a time cost in resolving the IP addresses of each client as it makes a request. However, you can still resolve these IP addresses by using the GETHOSTBYNAME command. Simply get the REMOTE_ADDR environment variable that contains the IP address of the client, and use this as the argument to GETHOSTBYNAME:

GETENV USING `REMOTE_ADDR` download_ip.

GETHOSTBYNAME USING download_ip.

MOVE TCPIP-HOSTENT-HOSTNAME TO download_host.

The GETHOSTBYNAME command will resolve the IP address to its fully qualified domain name, and the result will be placed in the TCPIP-HOSTENT-HOSTNAME variable. If the DNS server cannot resolve the IP address, the TCPIP-HOSTENT-HOSTNAME will be spaces. Also, for completeness, the TCP/IP return code values should always be examined after executing GETHOSTBYNAME to determine whether the command executed successfully or not.