Web Development

Chapter 11 . HTTP Variables

As HTTP servers and Web clients exchange data, the HTTP protocol sends a series of header fields containing information about the data being transferred over the Web. These header fields can, in turn, be passed to any program on your HTTP server. Because the information in these variables can be useful in your Prolifics Web application, Prolifics converts some of these header fields to global variables that can be accessed through JPL procedures or C functions.

An HTTP header field has a corresponding Prolifics HTTP variable. The Prolifics variable name begins with @cgi_ followed by the HTTP field name in lower case. The Prolifics HTTP variables are read-only and are automatically reset on each GET or POST of a Prolifics screen. Because Prolifics updates these variables automatically, copy their values elsewhere if you need them for a subsequent POST.

Common uses of the HTTP variables include:

For example, this JPL procedure builds a URL for a link with @cgi_server_name and @cgi_script_name. 

proc build_link
// This procedure sets dynamic label's
// default_link property
home->default_link = "http:://" ## \ 
	@cgi_server_name ## \ 
	@cgi_script_name ## "/home.scr"
return 0

A Prolifics Gallery sample entitled HTTP Variables is accessible from the Web application server at: 

http://server-name/cgi-bin/jwsamp/main

Definitions

@cgi_auth_type
The authentication method required to authenticate a user who desires access to a protected script.

@cgi_content_length
The length of the data message if POST is used to submit data back to the server.

@cgi_content_type
The MIME Content-Type of the data if POST is used to submit data back to the server. For Prolifics, this variable is set to: 
application/x-www-form-urlencoded

The basic MIME types are listed in the following table:

MIME type Description

application

Binary data that can be executed or used by another application

audio

Sound data

image

Image data

message

Encapsulated mail message

multipart

Multiple parts possibly consisting of many data types

text

Textual data

video

Video data

@cgi_gateway_interface
The version of the CGI specification to which this server complies in the following format: 
CGI/version-number

A sample value would be: 

CGI/1.1

@cgi_http_accept
A comma-separated list of MIME Content-Types that are acceptable to the client. They are listed in the following format:

type/subtype

You can use the contents of this variable to determine which image formats a browser can accept. For example, Netscape 2.x includes the following string, to indicate that it can display GIF, XBM, JPEG and Progressive JPEG images: 

image/gif, image/x-xbitmap, image/jpeg, image/pjpeg

@cgi_http_cookie
A list of all the returned cookie values, separated by semi-colons. The cookie values are returned when the browser requests a document from the same HTTP server that set the cookie.

@cgi_http_referer
The URL of the document where the request originated. This can be a partial URL, in which case it is interpreted relative to the URL of the document being requested.

For Prolifics applications, this information is only useful on GET events. If the user enters a Prolifics application from elsewhere, for example from another Web site, this variable will specify that location, which can then be logged if desired.

@cgi_http_user_agent
Information about the browser software making the request. This variable identifies the browser type. Even though there is no standard format, this information usually appears in the following format: 
software/version comments

You can determine the format for a particular browser only by experimentation. For example, the value sent from Netscape 2.02 running on a Windows 95 PC is: 

Mozilla/2.02 (Win95;I)

@cgi_path_info
Any extra path information found in the URL. Generally, this is the relative path to a resource.

Prolifics uses this information to determine which Prolifics screen to open. For the example, this variable would be: 

/vbiz/vidlist.scr

@cgi_path_translated
The absolute path on the local system for a resource. This is done by pre-pending the server's document root directory, or DOCROOT, to the path specified in @cgi_path_info.

If the server's DOCROOT directory is /usr/local/htdocs, the variable would have the following value for the screen listed in the example: 

/usr/local/htdocs/vbiz/vidlist.scr

@cgi_query_string
A URL-encoded search string. This string is separated from the URL by a question mark. For the example, this variable would be: 
start=top

For more information on URL encoding, refer to "Encoding Parameters in the URL."

@cgi_remote_addr
The numeric IP address of the remote computer making the request. This is not necessarily the address of the client, but could be the address of the host machine where the browser is running.

@cgi_remote_host
The Internet domain name of the host machine making the request. This host machine is where the browser is running. If the domain name is unavailable, this field is left blank.

@cgi_remote_ident
The remote user name retrieved by the server using the idntd identification daemon.

@cgi_remote_user
The authenticated name of the user.

@cgi_request_method
The method associated with the request. For HTTP servers accessing Prolifics, this will be either GET or POST. The GET method is used when the user enters a specific URL or activates a hyperlink. The POST method is used when the user submits a form. Using this variable, you can choose which portions of your code to execute for each method.

@cgi_script_name
The path and name of the CGI script being accessed, as it is referenced in a URL. Note that this is only the path that appears in the URL; it is not the actual, complete path of the CGI program. For the example, this value is: /cgi-bin/webdev

@cgi_server_name
The Internet domain name of the HTTP server. If the domain name is not available, the numerical IP address is used. This is useful if the HTTP server is acting as home for multiple domains, and they each call the same Prolifics executable. In the example, the domain name is vbiz.com.

@cgi_server_port
The port number receiving the browser request.

This is 123 in the example. Port numbers are useful if there are multiple servers running on the same machine, each calling the same Prolifics executable.

@cgi_server_protocol
The name and version of the information protocol for the incoming request using the following format: 
protocol/version-number

A sample value for this variable would be: 

HTTP/1.0

@cgi_server_software
The name and version of the HTTP server software invoking the external program. The format is: 
software-name/version

The following examples are typical values: 

NCSA/1.5
Netscape-Communications/1.1