Switch to Italian Language
Giovanni's logo
CGIDEV2 Tutorial
this means Version 2
index power search
blue line
1. Getting acquainted
2. Basic demos
3. Setup commands
4. CGI services available through CGIDEV2 service program
5. Apache HTTP error codes and CGI debugging tips
6. Error number meanings
7. Performance tips
8. About persistent CGI
9. ZIP and UNZIP commands
10. CGIDEV2 updates
11. XSS vulnerability

1. Getting acquainted

If you are not yet familiar with CGI programming and with CGIDEV2 service program, please read the following:

2. Basic Demos

Our demos are the best way to learn in practice how to develop RPG-ILE CCGI programs. After reading about CGIDEV2 service program functions, we recommend you visit them.

3. Set up commands

You should not develop your CGI's in one of the libraries (e.g. CGIDEV2) downloaded from our site. Installing a refresh would delete your developments.
You should instead develop your CGI's in your (source and object) libraries. The problem of copying all the pieces needed for development and for execution of your CGI's is solved through some commands. We have commands to easy your setups:
  • cgidev2/setcgilib to set up your source and production libraries for CGI development
  • cgidev2/crtcgisrc to create a running example of CGI source.
Then we have prepared for you some ILE-RPG source members that you may include in your sources, thus saving coding time.

4. CGI services available through CGIDEV2 service program

For a comprehensive walk through all the features of CGIDEV2 service program, you may go to Mel Rothman's Readme page.

We recommend however you go through the following scheme, which provides you with a smooth learning path:

Main functions
  • Read input from client browser
  • Map input string into program variables
  • Multiple occurrences of an input variable
  • Use an externally defined HTML script
    to write HTML output
Other functions
  • Handling cookies
  • Message handling
  • Maintain and retrieve page counts
  • Retrieve environment variables
  • Other environment variables functions
  • Timing functions
  • IFS subprocedures
  • IFS commands
  • Uploading PC files
  • Sending a stream file to the browser
    (Downloading a stream file)
  • CGI debug file
  • Debugging functions
Coding facilities
  • Data conversion functions
  • Execute a command
  • Encrypting strings and stream files
Dynastatic pages
  • Write HTML to a stream file
MS Office Interface Program state support Persistent CGI support
  • Get a random integer
  • Assign a Session ID ("handle")


5. Apache HTTP error codes and CGI debugging tips

  • If you have problems understanding the meaning of an Apache HTTP error code, go to this page to find out its meaning.
  • If not familiar with HTTP error code 500, go to page Debugging tips and learn how to debug CGI programs.

6. Error number values

In some circumstances some subprocedures of the service programs may end with non-zero return codes. Usually such error codes are also reported in the CGIDEBUG file. The guess would be about the meaning of such codes. To find out about them:

7. Performance tips

In order to obtain the best performance from your CGI's, you may want to adopt the following tips:
  1. use a named activation group (a different activation group for each CGI, see FAQ number 26)
  2. return without setting LR on
      Note. By returning with LR set to *off provides you with another great performance advantage. The next time the program is called and tries to reload the external HTML, the service program will find that the HTML is still in core, and will skip its loading, thus saving some relevant amount of time.
  3. open files just the first time through, never close them
  4. each time the program runs
    • re-initialize variables
    • do not rely on files being positioned on the first record; reposition with SETLL, or SETGT, or any other appropriate way
  5. After programs are thoroughly tested, use CALLP SetNoDebug(*ON) to turn all debugging off.
      Note.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.

8. About persistent CGI

So far, without mentioning them, we have being talking about non persistent CGI. Traditionally, CGI programs are not persistent, that is, a CGI program, the next time it is called, does not remember (or, better, must not remember - as no guarantee exists that it is called by the same client as before) what values where left in its variables, and where files are positioned. This fact of course has a relevant impact in program design, because the values of the variables which are important for a program at the time it is invoked must be saved in the previous response HTML (usually as hidden fields) and sent with the program invocation request.

Since V4R3, however, persistent CGI have been implemented for OS/400 HTTP.
A persistent CGI returns without raising LR, that is, the next time it is called, it finds its status as it was left.
The obvious problem with persistent CGI, is that for a given program there are potentially several copies waiting to be called back, and each copy is related to a different user. You would not like to have such responsibilities be randomly mixed up. To solve this problem, it is a program responsibility to give a "ticket" (technically speaking, a "handle") to each next program invocation.
The next problem is that a persistent CGI cannot wait forever to be called back. An HTTP controlled timeout will kill any persistent CGI session waiting over a given number of seconds. At this point, the user may need to re-start his transaction cycle from the beginning.

Because of this second problem, the implementation of persistent CGI is not very frequent and left to cases where a COMMIT technique is mandatory.

Our recommendation is not to use persistent CGI, unless strictly necessary. Persistent CGI

  • do not perform faster than non-persistent CGI
  • require much more skill and testing
  • may not provide a user-friendly solution

However, should you like to know more on this subject, this is your page.

9. ZIP and UNZIP commands

Library CGIDEV2 includes commands ZIP and UNZIP.
These commands allow to compress and decompress IFS stream files using standard .zip files.
The requests entered from commands ZIP and UNZIP are transformed to QSHELL commands, that are run in batch mode.
Results from ZIP and UNZIP commands can optionally be displayed.

10. CGIDEV2 updates

  1. Signature of service program CGIDEV2/CGISRVPGM2
  2. Some releases of CGIDEV2 may include new subprocedures for service program CGIDEV2/CGISRVPGM2.

    Since March 25, 2009 service program CGIDEV2/CGISRVPGM2 has a zero signature.

    If you already have installed CGIDEV2 and you are going to install a new release of it, you should first check the release date of the existing CGIDEV2. You do that by running command CGIDEV2/RELEASED.

    1. If the existing CGIDEV2 carries a release date equal to or higher than March 25, 2009, your CGI programs bounded to service program CGIDEV2 will have no problem with the new CGIDEV2 release, as there will be no signature check with the new service program CGIDEV2/CGISRVPGM2.
    2. If you have a CGIDEV2 version released prior to March 25, 2009 , after installing the new version of CGIDEV2 you must run command CGIDEV2/REBIND library_name for each library containing programs bound to service program CGIDEV2/CGISRVPGM2.
      Command CGIDEV2/REBIND rebinds all service programs and CBLLE/RPGLE programs in the user specified library.
    3. If you duplicated service program CGIDEV2/CGISRVPGM2 to several CGI program libraries (to make them independent from service program CGIDEV2/CGISRVPGM2, and be free to update library CGIDEV2 in any moment), and you want to replace some of those duplicated CGISRVPGM2 service programs with a more recent version available in library CGIDEV2, then you may use command CGIDEV2/DUPSRVPGM.
      This command:
      1. retrieves the libraries containing service program CGISRVPGM2
      2. lets you select the libraries to be processed
      3. for each selected library
        • replaces service program CGISRVPGM2 in that library with a copy of service program CGIDEV2/CGISRVPGM2
        • rebinds all service programs of that library
        • rebinds all CBLLE and RPGLE programs in that library.

  3. Activity group of service program CGIDEV2/CGISRVPGM2
  4. During CGIDEV2 installation, service program CGIDEV2/CGISRVPGM2 is created with activity group CGIDEV2.
    Before installing a new release of CGIDEV2, you should check if the activity group of your current service program CGIDEV2/CGISRVPGM2 is instead *CALLER. You do that by running command

    If the activity group of your current service program CGIDEV2/CGISRVPGM2 is *CALLER, after the installation of the new CGIDEV2 completes, you MUST run command
    If you do not do this, you may have problems with some existing CGI programs of yours.

    11. XSS Vulnerability

    One of the major security problems with WEB pages comes from Cross-Site scripts (known as XSS).
    Cross site scripting (also known as XSS) occurs when a web application gathers malicious data from a user. The data is usually gathered in the form of a hyperlink which contains malicious content within it. The user will most likely click on this link from another website, instant message, or simply just reading a web board or email message. Usually the attacker will encode the malicious portion of the link to the site in HEX (or other encoding methods) so the request is less suspicious looking to the user when clicked on. After the data is collected by the web application, it creates an output page for the user containing the malicious data that was originally sent to it, but in a manner to make it appear as valid content from the website. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.

    This vulnerability is not restricted to CGI pages, it applies to all dynamic WEB pages, wherever they come from.

    To protect your dinamic WEB pages (example: WEB pages dynamically sent to the browser from your CGI programs), you must provide a given HTTP header, which is understood by all major popular browsers (Firefox, Internet Explorer, Chrome, Opera, Safari). Such a HTTP header is named X-XSS-Protection and has two options:

    1. X-XSS-Protection: 1;
      A 1 value enables the XSS Filter
      If a cross-site scripting attack is detected, in order to stop the attack, the browser will sanitize the page.
    2. X-XSS-Protection: 1; mode=block
      Rather than sanitize the page, when an XSS attack is detected the browser will prevent rendering of the page.

    Content-type: text/html
    X-XSS-Protection: 1;
             (mandatory blank line to signal end of HTTP headers)
    ... ... ... ... ...