Mel Rothman, CEO of Mel Rothman, Inc., wrote these tools when he was an IBM employee in the IBM Custom Technology Center in Rochester, Minnesota.

Mel continues to enhance and support CGIDEV2 on a voluntary, as-available basis. Enhancements and fixes are contributed to IBM at no charge and are distributed by IBM via its Easy400 web site.

IBM is CGIDEV2's owner and copyright holder.

Dr. Giovanni Perotti, IBM Italy, used CGIDEV2 to build the IBM Easy400 site, which contains CGIDEV2 and many additional tools and tutorials written by him.

All the materials on the Easy400 site are available at no charge.

Contents

• Getting and parsing the browser's input
• Externally described output HTML
• Externally described HTML subprocedures
• Externally described HTML - maximums
• Subprocedures for formatting and sending HTML messages to the browser
• Subprocedures for creating and reading HTTP cookies
• Environment variable subprocedures
• Debugging subprocedures
• Error detection and reporting
• General purpose counter subprocedure
• Data handling subprocedures
• Persistence subprocedures
• CL commands subprocedures
• Random number and random string subprocedures
• Saving and restoring state information
• User space subprocedures
• IFS subprocedures

• XXXCGIPARS ZhbGetInput, ZhbGetVarCnt, ZhbGetVar, ZhbGetVarUpper, ZhbGetVarPtr, ZhbCountAllVars, ZhbGetVarDetails
• XXXCGIVARS CgiVarCnt, CgiVarVal, CgiVarValUpper
• XXXCOOKIES CrtCookie, GetCookieByName
• XXXCOUNT Countp
• XXXCVTDB CvtDb
• XXXDATA Char2Hex, Hex2Char, C2N, C2N2, ChkNbr, xlatWCCSIDs, Uppify
• XXXDEBUG IsDebug, SetNoDebug, WrtDebug, WrtPsds, WrtJobDbg
• XXXDOCMD DoCmd
• XXXENVVARS GetEnv, PutEnv, ContLen
• XXXERRNO Errno, Errnotxt
• XXXFIXMIXED FixMixed
• XXXHTMLMSG AddMsg, CfgMsgs, ClrMsgs,
• XXXIFS ChkIfsObj2
• XXXINPUT GetInput
• XXXPERSIST GetSessionId
• XXXRANDOM GetRandom
• XXXTIME TimerStart, TimerElapsed
• XXXUSRSPC CrtUsrSpc, RtvUsrSpcPtr
• XXXWRKHTML ClrHtmlBuffer, CrtTagOpt, Encode, Encode2, EncodeBlanks, GetHtml, GetHtmlBytesBuffered, GetHtmlIfs, GetHtmlIfsMult, RtvHtmlRcd, RtvSubsVarInfo, UpdHtmlVar, WrtHtmlToStmf, WrtNoSection, WrtSection

Object List

Tips

• PDM user defined options to create modules, programs, etc.

DISCLAIMER

The following applies to each CGIDEV2 library source code member.

This material is provided by IBM for illustrative purposes only and has not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of this material. IBM provides no program services for this material. All material contained herein is provided to you "AS IS" without any warranties of any kind. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY DISCLAIMED. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSIONS MAY NOT APPLY TO YOU. IN NO EVENT WILL IBM BE LIABLE TO ANY PARTY FOR ANY DIRECT, INDIRECT, SPECIAL OR OTHER CONSEQUENTIAL DAMAGES FOR ANY USE OF THIS MATERIAL, INCLUDING, WITHOUT LIMITATION, ANY LOST PROFITS, BUSINESS INTERRUPTION, LOSS OF PROGRAMS OR OTHER DATA ON YOUR INFORMATION HANDLING SYSTEM OR OTHERWISE, EVEN IF WE ARE EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

COPYRIGHT NOTICE

Licensed Materials - Property of IBM

Purpose and benefits

CGIDEV2 provides tools that make it easier to write, test, debug, and maintain ILE CGI programs.

Two types of tools are included:

• Sample programs that can be copied and modified to create new programs
• a service program, CGISRVPGM2, containing powerful subprocedures that simplify writing CGI programs.

• provide examples of CGI program logic and flow
• extensively use the service program's subprocedures, thus providing examples of their use

• Make the IBM provided CGI application programming interfaces easy to use. For example, getting input from the browser is reduced to one ILE RPG statement.
• Enable you to store most output HTML in an IFS stream file or in a source physical file, thus separating it from the CGI program. At run time, this "externally defined HTML" is used like a display file:
  • The HTML is organized into "named sections," analagous to DDS record formats.
  • "Substitution variables" in the HTML data records, analagous to DDS field names, are replaced at run time with values specified by the programmer.
  As a result, just as with native display files, most display changes can be made without modifying or recompiling the CGI program.
• Debugging tools
• Parsing tools
• Data conversion tools
• Character entity encoding tools
• Data editing and message formatting tools.
• Tools that make it easy to store and retrieve CGI program state information from user spaces.
• Timing tools
• Tools to execute CL commands, handle CGI persistence, count CGI page hits, generate random numbers and random strings, and many more.

Distribution

CGIDEV2 is distributed without charge from IBM's Easy400 web site.

Support for CGIDEV2 and other EASY400 Tools

• First level support is provided at the Easy400 web site .
  Here are a few useful direct links into the site:
  • Deliverables
  • RPG-ILE CGI Tutorial
  • FAQ: Frequently Asked Questions
  • PROTOTYPEB ILE-RPG Source Member
    the definitive source for CGISRVPGM2 service program's subprocedure documentation
  • Index
  • Site Map
  • Easy400 Testimonials
• 
  
• Second level support is provided via the Yahoo EASY400 group. owned by Giovanni Perotti and co-moderated by him and Mel Rothman.

  This is the place for EASY400 users to ask and answer questions, and to share their experiences.

  User questions often are answered by searching the group's archive.

  If the answer isn't found in the archive, a newly posted question is frequently answered quickly and accurately by other users without involving Giovanni or Mel.

• Third level support is provided by Dr. Giovanni Perotti via e-mail at gb_perotti@it.ibm.com

• Fourth level support is provided jointly by Mel Rothman and Giovanni Perotti when Giovanni deems that Mel's assistance is required.
  Please do not contact Mel directly.

Prerequisites

• OS/400, V5R1M0 or later
• IBM HTTP Server for iSeries or AS/400, V5R1M0 or V5R2M0 or IBM HTTP Server Powered by Apache for iSeries or AS/400, V5R1M0 or later
• ILE RPG for iSeries or AS/400, V5R1M0 or later.

  Note: RPG IV is the name of the language that implements RPG in the ILE environment on iSeries and AS/400 systems. Many people use the terms ILE RPG and RPG IV interchangeably. Although this document consistently uses the term ILE RPG, it could have used RPG IV as well.

Sample Programs

The sample programs are:

• TEMPLATE, a CGI program that parses its input with the QtmhCvtDb API and gets its externally described HTML from a source physical file.

  This is one of the earliest samples and it is not recommended for new development.

• TEMPLATE2, a CGI program, similar to TEMPLATE that parses its input with RPG subprocedures and gets its externally described HTML from a source physical file.

  This is one of the earliest samples and it is not recommended for new development.

• TEMPLATE3, a CGI program, similar to TEMPLATE that parses its input with the QzhbCgiParse API and gets its externally described HTML from a source physical file.

  Because it does not read its externally described HTML from the IFS, it is not recommended for new development.

• TEMPLATE4, a CGI program, identical to TEMPLATE3, except that it gets its externally described HTML from an IFS stream file.

  Because it uses GetHTMLIFS, which supports using only one stream file and does not return any error information, it is not recommended for new development.

• TEMPLATE5, a CGI program, identical to TEMPLATE4, except that it gets its externally described HTML from multiple IFS stream files and is written using free-form calculations. If you prefer fixed-form calculations, the source for the fixed-form version of this program is distributed in QRPGLESRC source member TEMPLATE5F.

  This is the best of the five TEMPLATE programs to use as the basis for new development for free-form aficionados.

• TEMPLATE5F, a CGI program (source only, it is not compiled into a program object), identical to TEMPLATE5, except that it gets its externally described HTML from multiple IFS stream files and is written using fixed-form calculations. If you prefer free-form calculations, the free-form version of this program is distributed in QRPGLESRC source member TEMPLATE5.

  This is the best of the five TEMPLATE programs to use as the basis for new development or fixed-form aficionados.

• PERSIST, a persistent CGI program that gets and parses its inputs with the zhbGetInput, zhbGetVarCnt, and zhbGetVar subprocedures and gets its externally described HTML from the IFS using getHtmlIfsMult.

  Persistent CGI should be used only when commitment control is absolutely necessary.

• DSPENCODE2, a CGI program that uses the encode2 subprocedure to display the character entity encoding that results when the encode2 subprocedure is used with either the default IFS file or a user specified IFS file. This program is written using ILE RPG free-form syntax.

• STATE, a CGI program that uses the CrtUsrSpc and RtvUsrSpcPtr subprocedures to save and restore state information into and from a user space.
  
  It creates its user spaces in a library called CGIDEV2USP. If the library does not exist, STATE creates it.
  
  It uses the Encode2 subprocedure to convert the special HTML characters ", &, <, and >, to their corresponding HTML character entities &quot;, &amp;, &lt;, and &gt;.
  
  It uses the EncodeBlanks subprocedure to convert blanks to non-breaking spaces, &nbsp;.

The sample programs extensively use the subprocedures contained in the CGISRVPGM2 service program.

Because most of the required CGI functions are performed by the CGISRVPGM2 service program, the mainline sample programs' source members are compact.

The CGIDEV2's library's source file members are commented to assist you in understanding their functions. You might want to concentrate on the following QRPGLESRC members:

• TEMPLATE5, which uses the latest and best subprocedures,
• PROTOTYPEB, which contains heavily commented prototypes for all the service program's subprocedures, and ;
• finally, the XXX* members, which contain the service program's implementations.

The CGISRVPGM2 Service Program

Prototypes for CGISRVPGM2's subprocedures are in QRPGLESRC, member PROTOTYPEB.

Binding source is in QSRVSRC, member CGISRVPGM2.

Getting and parsing the browser's input

ZhbGetInput and its related subprocedures are recommended because they take advantage of the latest and best IBM APIs, are the easiest to use, and are designed to handle up to 16 MB of input from the browser.

It is recommended that you not write CGI programs that expect anywhere near this much input!

The following table describes how ZhbGetInput, GetInput, and their related subprocedures work, and how parsing is performed for each.

Escape sequence handling

Skip this section if you are not using %%MIXED%% mode. It is here only because the code is still included for compatibility reasons. Nobody should be using %%MIXED%% mode!

This section addresses a problem that existed in very early versions of the HTTP server, when the only CGI_MODE was %%MIXED%% (it didn't even have a name then).

HTTP (HyperText Transfer Protocol), requires that requesters (browsers) send certain characters as 3-character escape sequences (%HH), where HH is the two hexadecimal characters for the ASCII character.

For example, a comma is %2C, where 2C is the comma's ASCII code point. If the CGI_MODE environment variable is %%MIXED%% or %%MIXED/MIXED%%, the HTTP server does not translate the %2C to %6B, the comma's EBCDIC code point. When %2C subsequently is converted to an EBCDIC character, it is not a comma.

The FixMixed subprocedure corrects this problem.

Although FixMixed is not directly referenced by the sample programs, it can be used if necessary.

Externally described output HTML

This feature allows CGI programs to build dynamic HTML using externally described data in a manner similar to display file DDS. The external data, which can be in a stream files or source physical file members, contains named sections, the equivalent of record formats.

The records within a section, contain substitution variables, which like DDS variables, are filled in at run time when the section is written.

The externally described HTML is processed by the service program subprocedures described below under "Externally described HTML subprocedures."

Most HTML changes can be made in the stream files or source members without modifying or recompiling the CGI program.

A section record, which defines where a section begins, starts with a section delimiter in column 1, followed immediately by the section name. An optional end section delimiter can follow the section name. The default section delimiter is /$ without an ending section delimiter. Different delimiters can be used by passing them as optional parameters to the GetHtmlIfsMult, GetHtmlIfs, or GetHtml subprocedure.

The default section delimiter was decided upon during the early development of CGIDEV, CGIDEV2's predecessor. /$ sometimes fails with CCSIDs (coded character set identifiers) other than those used in the United States.

Delimiters that make the section record into a valid HTML comment work much better. For example:

  <!-- _top -->

uses

'<!-- _'

' -->'

as the ending delimiter.

A special section name, noname, is used for any records that appear before the first section record in the first file.

Substitution variable names are enclosed between two delimiters. The defaults are /% and %/; different delimiters can be used by passing them as optional parameters to the GetHtmlIfsMult, GetHtmlIfs, or GetHtml subprocedures.

Substitution variable values are set with the UpdHtmlVar or UpdHtmlVar2 subprocedure.

Variable substitution is performed by the WrtSection subprocedure. If a substitution variable's value has not been set, WrtSection substitutes either the default string, **Missing Data**, unless overridden by a string passed via WrtSection's NoDataString parameter.

In the following example, when the HTML in the tablerow section is written, the string /%days%/ is replaced by the value of the days field and the string /%hours%/ is replaced by the value of the hours field.

Note that section names and substitution variable names are not case-sensitive.

RPG source

callp     UpdHtmlVar('DAYS':days)
callp     UpdHtmlVar('hours':hours)
callp     WrtSection('tablerow')

HTML source

Note that in this example, the default section delimiter, /$, is being overridden by <AS400>.

<AS400>tablerow
<TR>
<TD>/%days%/</TD><TD>/%HOURS%/<TD>
</TR>
...next section

Externally described HTML subprocedures

• GetHtmlIfsMult , GetHtmlIfs , and GetHtml read and process externally described HTML from multiple IFS stream files, a single IFS stream file, or a single source physical file member, respectively. The HTML records and information about any substitution variables are stored in dynamically allocated arrays inside the service program.

  It is recommended that externally described HTML stream files be placed in directories not being served or cached by the HTTP server.

  Sample program TEMPLATE4 uses stream file /CgidevExtHtml/talk2ifs.html.

  Sample program TEMPLATE5 uses multiple stream files from the /CgidevExtHtml directory.

• UpdHtmlVar stores substitution variable information in dynamically allocated arrays in the service program. If a variable already exists in the arrays, its value is changed. Otherwise, the variable name and value are added to the arrays. An optional parameter can be used to clear the arrays.

• UpdHtmlVar2 works like UpdHtmlVar. However, while UpdHtmlVar is limited to 1000 bytes of substitution data, UpdHtmlVar2 supports up to 16 MB of substitution data by passing a pointer to the data and the data's length.

• Encode converts the four most commonly used special HTML characters, ", & < and >, to their character entity equivalents: &quot; &amp; &lt; and &gt;. Use this subprocedure on data being passed to UpdHtmlVar or UpdHtmlVar2 to ensure that the browser does not process as HTML, data that is intended for display only.

• Encode2 converts a much larger list of characters to their character entity equivalents. Use this subprocedure on data being passed to UpdHtmlVar or UpdHtmlVar2 to ensure that the browser does not process as HTML, data that is intended for display only.

  Information about the characters to be encoded and their character entities is read from an IFS file, either the default, /cgidevexthtml/encode2Fil.txt, or a file specified when encode2 is called.

• EncodeBlanks converts blanks to non-breaking spaces (&nbsp;). Use this subprocedure on data being passed to UpdHtmlVar when you do not want the browser to convert two or more consecutive blanks to a single blank. Alternatively, the <pre> and </pre> tags can be used.

• WrtNoSection writes data without using a section name and without performing variable substitution.

  This subprocedure can be used when a large block of data is to be written. This is more likely to happen when writing non-textual data such as images.

  WrtNoSection's input parameters are the address of the data to be written and the number of bytes to write.

  In order to maximize performance, data are written into a dynamically allocated buffer and are not sent to standard output until the user writes the fictitious *fini section.

  WrtNoSection does not automatically insert newline characters.

• WrtSection writes one or more HTML sections, performing variable substitution, as required. In order to maximize performance, data are written into a dynamically allocated buffer and are not sent to standard output until the user writes the fictitious *fini section.

  WrtSection automatically appends a newline character (x'15') to the end of each HTML record unless optional parameter, nonewline, is specified with a value of *on. This parameter is useful when binary data are being sent to the client (for example, when using HTTP tunneling).

• WrtHtmlToStmf sends all buffered HTML output to a stream file instead of to standard output.

  This subprocedure is designed for use in non-CGI programs. If used in CGI programs, the programs will fail.

  WrtHtmlToStmf is useful for producing static pages that change from time to time (minutes, hours, days, etc.). Periodically recreating static pages for repeated serving performs much better than running a similar CGI program for each request. In addition, static pages can be cached by the HTTP server.

  For an example, see program RANDOMNBR in QRPGLESRC.

• ClrHtmlBuffer clears any HTML output that has been buffered but has neither been sent to the browser nor written into a stream file.

  It is a good idea to call ClrHtmlBuffer in each CGI program before any uses of WrtSection or WrtNoSection. This practice prevents sending to the browser any buffered HTML from a previous, abnormally ended use of the program.

• GetHtmlBytesBuffered returns the number of bytes that have been buffered but have neither been sent to the browser nor written into a stream file.

• CrtTagOpt creates a fully formatted HTML <OPTION> tag.

• RtvHtmlRcd retrieves a record's contents from the externally described HTML.

  Inputs are the section name (or *NONE) and a relative record number.

  If a section name is specified, the relative record number is its position within the section.

  If the section name is *NONE, the relative record number is its position among all the records, regardless of its section.

  A return code indicates whether the record was found, and if not, why not.

  "Why not" reasons include record not found (out of range), section not found, and record part of a duplicate, and therefore ignored, section.

  RtvHtmlRcd can be used to analyze your HTML, to produce reports about it, and to implement various automated tools.

• RtvSubsVarInfo retrieves information about substitution variables in your externally described HTML.

  Inputs are the section name (or *NONE) and a sequence number.

  If a section name is specified, the sequence number is the substitution variable's position within the section.

  If the section name is *NONE, the sequence number is its position among all sections.

  A return code indicates whether the record was found, and if not, why not.

  "Why not" reasons include sequence number out of range and section not found.

  An output data structure parameter is used to return the substitution variable's name, length of its name, its section's name, and the starting position in the HTML record where it was found.

Externally described HTML subprocedures - maximums

Subprocedures for formatting and sending HTML messages to the browser

When errors are found in the user's input, it is often necessary to send one or more messages to the browser. Formatting and outputting such messages can be tedious, repetitive, and error-prone.

• WrtMsgs sends to the browser all the messages previously placed into a set of arrays stored in the service program.

  
  

  The messages are written to the browser using sections of externally described HTML.

  A standard set of sections is provided in IFS files /CgidevExtHtml/Talk2Ifs.Html and /CgidevExtHtml/Talk2Stuff.Html, and in the sample HTMLSRC file member, TALK2.

  Sample ILE RPG message formatting code is in QRPGLESRC file members TEMPLATE5, TEMPLATE4, TEMPLATE3, TEMPLATE2, and TEMPLATE.

• AddMsg adds a message's text and formatting level (1, 2, or 3) to the service program's arrays.

• GetMsgCnt returns the number of messages currently stored in the arrays and can be used to condition calling WrtMsgs.

• ClrMsgs clears the messages stored in the arrays and sets their count to zero.

• CfgMsgs optionally overrides the default externally described HTML names used by WrtMsgs:

  • message text field name (msgtxt),
  • starting section name (msgstart),
  • level 1 section name (msgl1),
  • level 2 section name (msgl2),
  • level 3 section name (msgl3),
  • ending section name (msgend).

Subprocedures for creating and reading HTTP cookies

• CrtCookie returns a cookie header in the form:
  Set-Cookie: NAME=VALUE; expires=DATE; path=PATH; domain=DOMAIN_NAME; secure

• GetCookieByName retrieves a cookie's value given its name and occurrence.

Environment variable subprocedures

• GetEnv returns the value of a user-specified environment variable. It uses the HTTP server's QtmhGetEnv API.

• PutEnv creates or changes an environment variable. It uses the HTTP server's QtmhPutEnv API.

• ContLen returns the integer value of the CONTENT_LENGTH environment variable.

Debugging subprocedures

The debugging subprocedures use physical file CGIDEBUG, which has two fields: a time stamp and a 500 byte text field.

• IsDebug returns a value to indicate whether debugging is on ('1') or off ('0').

• SetNoDebug accepts an indicator variable. *on turns all debugging off; *off, allows debugging to operate normally, including the honoring of forced debugging output requests.

  Normally, CGIDEV2 programs spend considerable time in the debugging routines. Running subprocedure SetNoDebug *On can significantly reduce this overhead and improve performance at the cost of losing all debugging output.

  Note that SetNoDebug sets a global variable in the service program. If multiple CGI programs are running in the same named activation group, all those programs are affected in the same way by the most recent execution of SetNoDebug.

• WrtDebug writes into the debugging physical file, CGIDEBUG, the text passed to it as a parameter. WrtDebug is used by several of the service program's subprocedures. You can use it, as desired. No output is generated unless debugging output has been turned on by the CGIDEBUG *ON command, or the optional parameter, force, has been set to *on.

• WrtJobDbg writes the qualified job name, into the debugging file.

• WrtPsds receives the program status data area and unconditionally writes it in a formatted manner into the debugging file.

Error detection and reporting

The sample programs and the service program, use a program status data structure template and a program status subroutine to trap and report program status errors. They:

• Use two HTML sections, top and pssr, to inform the user that an error has occurred. You can modify the contents of these sections to meet your needs.

• Call a special debugging procedure, WrtPsds, that unconditionally formats and writes the contents of the program status data structure into the debugging file, CGIDEBUG.

• Other error handling subprocedures

  • Errno returns C's errno environment variable as an integer.

  • ErrnoTxt returns the text associated with a C errno.

General purpose counter subprocedure

Data handling subprocedures

• Char2Hex converts a character string to its hexadecimal representation
• Hex2Char converts a character string in hexadecimal format to its character representation
• ChkNbr accepts a character string and an optional parameter specifying the maximum number of digits to the left of the decimal point.

  Additional optional parameters are available to request that any errors found should be formatted as messages and added to the service program's message arrays, the text that should be used to describe the field in the messages, and whether a message should be sent if the field's value is less than zero.

  ChkNbr returns a structure containing seven indicators. The indicators and their meaning when *on are:

  1. One or more errors occurred. This indicator is set on only if one or more of indicators 2 through 6 is set on. It is not set on when only indicator 7 (value is negative) is on.
  2. Non-numeric characters (includes minus sign in wrong place)
  3. Multiple decimal points
  4. Multiple minus signs (both leading and trailing)
  5. Zero length input or no numeric characters
  6. Any of the following:
     • More than 21 digits to the left of the decimal point
     • More than 9 digits to the right of the decimal point
     • More digits to the left of the decimal point than specified in the maximum number of digits parameter
  7. Value is less than 0. This indicator is used only to cause a message to be sent. It does not cause indicator 1 to be set on.
• C2N2 converts a character string to a packed 30,9 number.

  It is recommended that you check the string with ChkNbr before calling C2N2.

  C2N2 performs more than 10 times faster than C2N and has none of C2N's floating point precision problems. Therefore, it is recommended that you use C2N2 instead of C2N.

• C2N (old, NOT recommended) converts a character string to a floating point number.

  It is recommended that you check the string with ChkNbr before calling C2N.

  Because floating point numbers often have precision problems, it is recommended that you use C2N2, which returns a packed 30,9 number and performs more than 10 times faster.

• xlatWCCSIDs uses CCSIDs to translate varying length strings up to 32767 characters in length.
  

  If optional parameters fromCCSID and toCCSID are specified, they are used for the translation and the toebcdic parameter is ignored.

  Otherwise, translation between ASCII and EBCDIC is performed using the CCSIDs found in the CGI_EBCDIC_CCSID and CGI_ASCII_CCSID environment variables with the direction of translation determined by the toebcdic parameter: *ON = ASCII to EBCDIC; *OFF = EBCDIC to ASCII.

• Uppify converts all the characters in a string to upper case.

Persistence subprocedures

• GetSessionId returns a 15-character string comprising the six characters of the job number followed by 9 random digits. This string can be used as the value passed with the Accept-HTSession header when programming persistent CGIs.

CL commands subprocedures

• DoCmd uses QCMDEXC to execute a user-specified CL command.

Random numbers subprocedures

• random returns a random integer between two user-specified integers.
• randomString returns a random string built in accordance with caller specified rules.

Saving and restoring state information

• the HTTP protocol used by browsers and web servers is stateless (that is, the browser connects to the server, makes a request, receives the response, then disconnects from the server), and
• many complex transactions use multiple interactions with the browser in which
• state (intermediate data) needs to be stored somewhere, and
• the server is the best place to store state (because of security and/or performance reasons), and
• there is no way, other than persistent CGI (which has its own problems) to guarantee that the browser will return to the same server instance for each subsequent interaction

• Each user space can hold up to 16 MB of information
• System APIs are provided to create a user space, change its attributes (including making it automatically extendible), retrieve a pointer to it, etc.
• Once addressability to a user space (a pointer) has been established, based variables (including data structures) can be used to read and write its contents.
• Saving and restoring user state information can be accomplished as follows:
  • at the start of the transaction, create a uniquely named user space,
  • use based variable(s) to map the user's data into the space,
  • send an HTTP response to the user, including a hidden field containing the user space name,
  • when the user makes a request using the form that contains the hidden user space name, use that name to retrieve a pointer to the user space, thus restoring addressability to the user space's contents using the same based variables that were used to store them.

User space subprocedures

• CrtUsrSpc creates a new user space:
  • the user space is created in the library specified by the caller
  • either defaults or user specified values are used for public authority, text, initial size, and extended attribute
  • the user space's randomly generated name is returned as the subprocedure's value
  • a pointer to the user space is returned in a parameter,
  • a 7 character message ID is returned as a parameter. It contains blanks if no errors occurred; otherwise it contains a message ID.
• RtvUsrSpcPtr retrieves a pointer to an existing user space:
  • using a caller specified qualified user space name
  • if successful, returns a valid pointer
  • otherwise, returns a null pointer

IFS subprocedures

• ChkIfsObj2 checks for the existence of and access to an IFS object and optionally returns its type, size, and error information.
  • This subprocedure's name is ChkIfsObj2 in order to distinguish it from Giovanni Perotti's IFSTOOL's ChkIfsObj subprocedure.
  • To be accessible, the user needs *X authority to all the directories in the object's path. No authority to the object is required.
  • Returns an indicator: *on if the object exists and is accessible; otherwise, *off.
  • Input parameter is the full path to the file
  • Output parameters (all optional with options(****NOPASS))are:
  • • the object's type
    • the object's size in bytes
    • C's errno value
    • The text associated with C's errno value.

Modules and their subprocedures

The following table lists the source members that comprise CGISRVPGM2. Brief descriptions of each member's subprocedures are included.

Object List

Programs and commands

CGIDEBUG command, CGIDEBUG program, and CGIDEBUG data area; CLRDEBUG program.

The CGIDEBUG command controls the built-in debugging facilities (*ON *OFF *DSP *DSPDATA *CLRDATA). Program CLRDEBUG is used by CGIDEBUG to delete all records from the target debugging file when a file lock prevents CLRPFM from clearing it.

CGISRVPGM2 service program

Performs most of work done by its calling CGI programs. Many of its tools can also be used by non-CGI programs.

DSPENCODE2 program

CGI program that displays character entity data from files used by the encode2 subprocedure.

DSPVERSION program; VERSION data area

CGI program that displays CGIDEV2's current version

PERSIST program

Sample persistent CGI program.

RANDOMNBRS program and command

Sample non-CGI program and command that demonstrates how to create an HTML stream file using externally described HTML and CGIDEV2 subprocedures. This is useful for information that is updated periodically but remains static between updates. This technique avoids the performance costs of running a CGI program every time the information is requested. It uses HTMLSRC source physical file member RANDOMNBRS. To use this demonstration program, run the command from the command line or from a batch program to create a stream file in a directory served by your server. Then use a browser to display the stream file. Then repeat and observe the updated static page.

RMVSRCRCDS non-CGI program and command.

The RMVSRCRCDS command removes specified records from a source file member. The command processing CL program is RMVSRCRCDS. It calls RPG program RMVSRCRPG. Use the RMVSRCRCDS command to remove comments and/or code from copies of sample programs in order to use them as starting points for new programs.

STATE program

Sample non-persistent CGI program that uses a user space to save and restore state information.

TEMPLATE, TEMPLATE2, TEMPLATE3, TEMPLATE4, TEMPLATE5 programs

Sample non-persistent CGI programs. TEMPLATE5 is the preferred sample because it uses the latest, most functional, and best performing CGIDEV2 subprocedures and underlying IBM CGI programming APIs.

Source physical files

Member names and contents can be found in the source files themselves.

• HTMLSRC
• QCLSRC
• QCMDSRC
• QDDSSRC
• QRPGLESRC
  • members starting with XXX are components of the CGISRVPGM2 service program.
  • member PROTOTYPEB contains the prototypes required by programs using the CGISRVPGM2 service program.
  • member USEC contains a modified version of IBM's QUSEC standard error data structure
• QSRVSRC (Binding source file)

  Member CGISRVPGM2 contains binding language source for creating service program CGISRVPGM2. If you need to recreate this service program, use the following command:

   CRTSRVPGM SRVPGM(CGIDEV2/CGISRVPGM2) +
   MODULE(CGIDEV2/XXX*) +
   SRCFILE(CGIDEV2/QSRVSRC) TEXT('CGISRVPGM2 +
   service program') BNDSRVPGM(QHTTPSVR/QZHBCGI) +
   BNDDIR(QSYS/QC2LE)
  

• README file
  • member CGIDEV2, this file in HTML format
  • member CHANGES, list of changes to CGIDEV2

Data files

CGICOUNT

File used by Countp subprocedure (general purpose counter).

DATASTRUCT

Externally described data structure used by the TEMPLATE program.

HOURSOP

Hours of operations file used by sample programs TEMPLATE, TEMPLATE2, TEMPLATE3, TEMPLATE4, TEMPLATE5, and PERSIST programs.

CGIDEBUG

Debugging data file used to receive internally generated debugging output from CGIDEV2's subprocedures as well as output from your programs using the WrtDebug, WrtPSDS, and WrtJobDbg subprocedures.

Other objects

TEMPLATE2 *BNDDIR

Contains references to service programs QHTTPSVR/QZHBCGI and CGIDEV2/CGISRVPGM2. This binding directory is referenced in RPG source member HSPECSBND, which is copied into most of CGIDEV2's programs and programs you may derive from them.

VERSION *DTAARA

Contains the current version's date and time. Used to determine whether you have the latest version. CGI program DSPVERSION can be used to display the data area's contents.

Tips

PDM user defined options to create modules, programs, etc.