synopsis.
There is a small cluster of subroutines for web ("www") functions at level 7:

• z_CGI_loadenv_to_namevalue()
• z_CGI_loadenv_to_dbag()
• z_CGIquerystr_to_dbag()
• z_CGIquerystr_to_nameval()
• z_CGIqstr_nextpair()
• z_CGIqstr_nextchunk()
• z_CGI_to_cleartext()
• z_cleartext_to_CGI(): encodes regular text according to the [older] RFC 3986 encoding, which changes a space (' ') to a plus ('+').
• z_URLenc_to_cleartext()
• z_cleartext_to_URLenc(): encodes regular text suitable for URLs, which converts a space (' ') to "%20". This function is very similar to z_cleartext_to_CGI().

[C] functions (aka subroutines):

z_CGI_loadenv_to_namevalue()
SIGNATURE: int z_CGI_loadenv_to_namevalue (namevalue_set_o &kv, boolean addpath, int *pie)
SYNOPSIS:
this subroutine is intended to be called from within a CGI program that was initiated by a web server, typically after a form on a web page was submitted by a user. It searches the program's environment for CGI-specific variables such as DOCUMENT_ROOT or QUERY_STRING. If found, they are loaded into the provided [output] container "kv".
RETURNS: the return value of this subroutine is basically whatever namevalue_set_o::load() returns. This should invariably be 0.
 

z_CGI_loadenv_to_dbag()
SIGNATURE: int z_CGI_loadenv_to_dbag (list_dbag_o &lbag, boolean addpath, int *pie)
SYNOPSIS:
this subroutine searches the environment for CGI-specific variables and loads them into the list databag object "lbag". This routine is logically equivalent to z_CGI_loadenv_to_namevalue(), except for the recipient container type.
RETURNS: 0
 

z_CGIquerystr_to_dbag()
SIGNATURE: int z_CGIquerystr_to_dbag (list_dbag_o &bag, const string_o &eqs, int *pexi)
SYNOPSIS:
This subroutine parses the query-string part of a URL and loads each name-value pair from this string into a list databag.
PARAMETERS

• bag: [output] a list databag containing a list of simple databags, one for each name-value pair found in 'eqs'.
• eqs: [input] an encoded query string
• pi: [output] an error indicator output 'flag' variable. values:
  0: currently this is the only value used

RETURNS: 0
 

z_CGIquerystr_to_nameval()
SIGNATURE: int z_CGIquerystr_to_nameval (namevalue_set_o &kv, const string_o &eqs, int *pi)
SYNOPSIS:
This subroutine parses the query-string part of a URL and loads each name-value pair from this string into a name-value set object.
This function is analogous to z_CGIquerystr_to_dbag(). The only logical difference is the target container type, which is a name-value set object instead of a list databag object.
PARAMETERS

• kv: [output] the container object, populated with name-value pair objects representing the contents of 'eqs'.
• eqs: [input] the encoded string
• pi: [output] an error indicator output 'flag' variable. values:
  0: currently this is the only value used

RETURNS:
0: success
-1: error
 

z_CGIqstr_nextpair()
SIGNATURE: int z_CGIqstr_nextpair (string_o &s, string_o &nam, string_o &val, int *pi = NULL)
SYNOPSIS:
this subroutine extracts the next query string "chunk" from input parameter 's', which is expected to be in URL-encoded format. The chunk is removed from the string and its components put into the output string variables 'nam' and 'val'.
PARAMETERS

• s: [input] a string encoded as the query string of a URL. this string is modified after this function call. Each call to z_CGIqstr_nextpair() removes the next "chunk".
• nam: [output] the (decoded) name part of the next chunk
• val: [output] the (decoded) value part of the next chunk
• pi: [output] an error indicator output 'flag' variable. values:
  0: currently this is the only value used

RETURNS: 0
 

z_CGIqstr_nextchunk()
SIGNATURE: string_o z_CGIqstr_nextchunk (string_o &es, int *pi)
SYNOPSIS:
This function extracts the next URL-encoded name-value pair from the parameter string 'es' and returns this string, as-is, as the return value of this function. It simply looks for an '&' character, which serves as a separator for query string "chunks".
This function is extremely simple and primitive. It exists mainly as a support routine for interesting (/involved) functions, such as z_CGIqstr_nextpair().
PARAMETERS

• es: [input & output] the "query" part of a URL-encoded string. These strings typically look like this example string:
  hl=en&btnG=Google+Search&gbv=1
  Note that spaces are converted to '+' characters, and "chunks" are delimited by '&' characters (except the last chunk).
• pi: [output] an error indicator output flag variable. values:
  0: success
  zErr_IsEmpty: 'es' is an empty string;
  zErr_Data_BadFormat: no '=' character found in the next chunk.

RETURNS: a string containing the next encoded "chunk" from input parameter 'es'. If an error occurs, an empty string ("") is returned.
 

z_CGI_to_cleartext()
SIGNATURE: int z_CGI_to_cleartext (const string_o &sin, string_o &sot, int *pi = NULL)
SYNOPSIS:
converts a string encoded into a URL syntax to its clear-text (normal, unencoded) equivalent. For example, the encoded string "q=iimPlay%28%29+iMacros+example" is converted to "q=iimPlay() iMacros example".
PARAMETERS

• sin: [input] the encoded string
• sot: [output] the resultant decoded string
• pi: [output] an error indicator output 'flag' variable. values:
  0: currently this is the only value used

RETURNS: 0
 

z_cleartext_to_CGI()
SIGNATURE: int z_cleartext_to_CGI (const string_o &sin, string_o &sot, int *pi = NULL)
SYNOPSIS:
converts a clear-text (normal, unencoded) string into an encoded format used by URLs. this subroutine is the converse of z_CGI_to_cleartext().
RETURNS: 0
 

z_URLenc_to_cleartext()
SIGNATURE: int z_URLenc_to_cleartext (const string_o &is, string_o &s, int *pi = NULL)
SYNOPSIS: this subroutine is not implemented. Do not use it.
PARAMETERS

• is: [input] string
• os: [output] string
• pi: [output] an error indicator output 'flag' variable. values:
  zErr_ThisCall_NotImpl: indicates that this function does not work.

RETURNS: 1
 

z_cleartext_to_URLenc()
SIGNATURE: int z_cleartext_to_URLenc (const string_o &is, string_o &os, int *pi = NULL)
SYNOPSIS:
This converts all characters that are not alphanumeric or one of "$-_.!*'()," (not encluding the enveloping double-quotes) to the hexadecimal numeric equivalent representation, so that the resultant string is suitable to be used as part of a URL. Space characters (" ") are converted to "%20".
PARAMETERS

• is: [input] a ["normal"] string
• os: [output] the resultant encoded string
• pi: [output] an error indicator output 'flag' variable. values:
  0: currently this is the only value used

RETURNS:
0: success
-1: error