Brief comments on CGI routines

• include file cgi.inc
  defines a couple of COMMON blocks (separate for character and numbers), containing a CGISTRING buffer used to hold the query string, and an additional work buffer. These are sized by a PARAMETER statement.
  Additionally contain the CGI method used, the Content-length where defined, and the debug flag used to allow some writes in the other routines.
  Additionally some commonly used HTML strings can be defined as PARAMETERs at the end of the file.

  You do not need to refer to this in the main program, unless you want to set the CGIDEBUG flag to .TRUE.

  ---

• get_named_variable.f

  Use this routine to get the value of a variable you know by name.
  Since the name may contain special characters, it has to be URL-encoded before trying to match its name in the query string. One looks for a string encodedname=value& and then extracts the value and URL-decodes it. In the process of encoding and decoding, as well as copying to the target string, truncation may occur. This and other errors are returned as non-zero error codes (documented in the source). Negative error codes are presumably severe, while positive ones can probably be considered as warnings (this includes the case of a null value, code 1).

  ---

• get_next_variable.f

  Use a sequence of calls to this routine to get the name and value of each variable in order.
  The routine looks for name=value& strings, extracts and URL-decodes the name, and then extracts and URL-decodes the value. In the process of decoding and copying to the target strings, truncation may occur. This and other errors are returned as non-zero error codes (documented in the source) similar to the previous routine. In addition a code of -1 means the end of the query string has been encountered.

  ---

  both above routines call the next one internally

  ---

• cgiretrieve.f

  deals with POST and GET method and retrieves the run string. Any call after the first one are no-op.

  The REQUEST_METHOD, CONTENT_LENGTH and QUERY_STRING are retrieved from environment variables, while for the POST method the query string is read from stdin with an A format. Detection of a method other than POST or GET is an irrecoverable error (although I noted that browsers or httpd daemons tend to prevent this forcing a valid method).

  ---

• cgiheader.f
  Self-explanatory routine used to produce the header for the HTML output. Note the way of producing a null line separating header and body.

  ---

• cgitoken.f
  Self-explanatory routine

  ---

• urldecode.f
  Called internally by the get_xxx_variable routines, will replace pluses with blanks and %hh hexadecimal encodings with the corresponding character.

  ---

• urlencode.f
  Called internally by get_named_variable to perform the reverse encoding of the above

  ---

  The routines below are not part of CGILIB, but of other libraries of mine. A link to them is provided, since it is simpler than making the entire libraries available.

  ---

• portable service routines

  true_length.f returns the length of the non-blank part of a string (trimmed length).

  bindex.f is a variant of the intrinsic INDEX function, which returns the absolute offset in a string of subsequent occurrences of a substring.

  upcase.f is a trivial routine converting a string to upper case.

  ---

• system-dependent environment interface

  get_global_default.f is a system-independent front-end for environment variable retrieval. It returns an user-specified default value even it the variable is not present. It calls in turn the next, system-dependent routine

  z_get_global.f is the Unix system-dependent incarnation of a routine used to retrieve an environment variable. There is also a VAX VMS incarnation. The Unix one in turn calls a zc_getenv.c C jacket routine, while the VMS one is standalone.

  For reasons too long to explain here, this approach was preferred to calling routines getenv or similar provided on some systems in their Fortran library. It shall be noted also that the routines are overdone for general use, so you should replace them with whatever you like or simplify them : in particular you should at least remove the reference to routine z_initenv, and the code which looks for a variable named XAS_NAME before NAME (such thing is irrelevant and unnecessary in CGIs, while it was peculiar of the XAS environment for which the routine was originally written).
  Similarly you should replace the references to voscommon.inc (defines a couple of variables to hold error codes, replace with local variables) and errors.inc (assigns system-independent parameter constant values to error codes).