Switch to Italian Language
Giovanni's logo
RPG-ILE CGI Tutorial
this means Version 2
power search
blue line
1. Getting acquainted
2. Basic demos
3. Setup commands
4. CGI services available through CGIDEV2 service program
5. CGI debugging tips
6. Error number meanings
7. Migration tips
8. Performance tips
9. About persistent CGI
10. ZIP and UNZIP commands

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 occurencies 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
  • Check IFS object
  • Uploading PC files
  • CGI debug file
  • Debugging functions
Coding facilities
  • Data conversion functions
  • Execute a command
  • Override a database file
Dynastatic pages
  • Write HTML to a stream file
Program state support Persistent CGI support
  • Get a random integer
  • Assign a Session ID ("handle")

    


5. CGI debugging tips

 Though debugging always comes last in a tutorial, it should rank first in a programmer's interest. This is why we dedicate a separate page to this topic.


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:
  1. Go to the following page of the iSeries Information Center: V4R5
  2. search for "errno xxxx", where xxxx is your error code.



7. Migration tips

 If you already developed some CGI's with Version 1, after having seen the advantages of Version 2, you would love to migrate them to Version 2.
We have a separate page to help you in this rather easy job, just link check it out.


8. 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 calls subprocedure gethtml, will not load the external html again (unless it was changed meanwhile), because it is still in core. This feature is responsible for the highest gain in the Version 2 performance improvements.
  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.



9. 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.


10. 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.