IBM AS-400e User Manual 2
AS/400e
HTTP Server for AS/400 Web
Programming Guide
GC41-5435-04
AS/400e
HTTP Server for AS/400 Web
Programming Guide
GC41-5435-04
Note
Before using this information and the product it supports, be sure to read the general information under “Chapter 11.
Notices” on page 145.
Fifth Edition (May 2000)
This edition applies to the IBM HTTP Server for AS/400 licensed program (Program 5769-DG1), Version 4 Release 5
Modification 0 and to all subsequent releases and modifications until otherwise indicated in new editions. This
edition applies only to reduced instruction set computer (RISC) systems.
This edition replaces GC41-5435-03.
© Copyright International Business Machines Corporation 1997, 2000. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
About HTTP Server for AS/400 Web
Programming Guide (GC41-5435) ....v
Conventions in this book ..........v
AS/400 Operations Navigator ........v
Installing Operations Navigator .......vi
Prerequisite and related information ......vi
How to send your comments ........vi
Chapter 1. Writing Common Gateway
Interface Programs ..........1
OverviewoftheCGI ...........1
CGI and Dynamic Documents .......2
UsesforCGI.............3
The CGI process .............3
Overview..............3
SendingInformationtotheServer......5
Data Conversions on CGI Input and Output . . . 5
ReturningOutputfromtheServer......11
HowCGIProgramsWork ........12
Environment variables ...........13
Requests from Standard Search (ISINDEX)
Documents.............15
Passing SSL Environment Variables to a CGI
Program..............15
CGI Programs and AS/400 Activation Groups . . . 17
AS/400 Activation Groups ........17
CGIConsiderations...........18
Activation Group Problem Examples .....18
Chapter 2. Application Programming
Interfaces .............23
APIs for CGI applications .........24
Get Environment Variable (QtmhGetEnv) API . . 25
Put Environment Variable (QtmhPutEnv) API . . 26
Read from Stdin (QtmhRdStin) API .....27
Write to Stdout (QtmhWrStout) API .....29
Convert to DB (QtmhCvtDB) API ......30
Parse QUERY_STRING Environment Variable or
Post stdin data (QzhbCgiParse) API .....32
Produce Full HTTP Response (QzhbCgiUtils) API 36
ConfigurationAPIs............38
Convert URL to Path (QzhbCvtURLtoPath) API 38
Retrieve Directive (QzhbRetrieveDirective) API 40
Retreive a list of all Configuration Names
(QzhbGetConfigNames) API ........42
Create a Configuration (QzhbCreateConfig) API 43
Delete a Configuration (QzhbDeleteConfig) API 44
Read a Configuration File into Memory
(QzhbOpenConfig) API .........45
Free a Configuration File from Memory
(QzhbCloseConfig) API .........46
Search for a Main Directive (QzhbFindDirective)
API................47
Search for a Subdirective under Main Directive
(QzhbFindSubdirective) API ........49
Return Details of a Main Directive or
Subdirective (QzhbGetDirectiveDetail) API . . . 51
Add a Main Directive or Subdirective
(QzhbAddDirective) API .........52
Remove a Main Directive or Subdirective
(QzhbRemoveDirective) API ........54
Replace a Main Directive or Subdirective
(QzhbReplaceDirective) API ........55
ServerinstanceAPIs...........56
Retrieve a list of all Server Instances
(QzhbGetInstanceNames) API .......56
Look up Server Instance Data
(QzhbGetInstanceData) API ........58
Change Server Instance Data
(QzhbChangeInstanceData) API ......60
Create a Server Instance (QzhbCreateInstance)
API................62
Delete a Server Instance (QzhbDeleteInstance)
API................63
Group file APIs .............64
Create a new Group File (QzhbCreateGroupList)
API................64
Read a Group File into Memory
(QzhbOpenGroupList) API ........65
Free Group File from Memory
(QzhbCloseGroupList) API ........67
Retrieve the next Group in the Group List
(QzhbGetNextGroup) API ........68
Locate a named group in a Group List
(QzhbFindGroupInList) API ........69
Retrieve the Name of a Group
(QzhbGetGroupName) API ........70
Add a new Group to the end of a Group List
(QzhbAddGroupToList) API ........71
Remove a Group from a Group List
(QzhbRemoveGroupFromList) API .....72
Retrieve the next User in the Group
(QzhbGetNextUser) API .........73
Locate a User in a Group
(QzhbFindUserInGroup) API .......74
Retrieve the Name of a User
(QzhbGetUserString) API .........75
Add a new user to the end of a Group
(QzhbAddUserToGroup) API .......76
Remove a User or Element from a Group
(QzhbRemoveUserFromGroup) API .....77
Chapter 3. Using Net.Data to Write CGI
Programs for You ..........79
OverviewofNet.Data...........79
Chapter 4. Using Persistent CGI
Programs .............81
© Copyright IBM Corp. 1997, 2000 iii
Overview of Persistent CGI .........81
Named Activation Groups ........81
Accept-HTSession CGI Header .......81
HTTimeoutCGIHeader.........82
Considerations for using Persistent CGI
Programs..............82
Persistent CGI Program Example ......83
Chapter 5. Enabling your AS/400 to run
CGI programs............85
How to enable the server to run CGI programs . . 85
Using directives for security and access control . . 86
Thedefaultfailrule ..........87
Explicit CGI enablement .........87
ServerrunsonlyCGIprograms.......87
CGIprogramconsiderations.........87
Chapter 6. Sample programs (in Java,
C, and RPG) ............89
Example of Java language CGI program .....89
Example of C language CGI program......94
Example of RPG language CGI program.....99
Example of a C language server configuration API
program...............105
HTTPreturncodesandvalues.......113
Predefined functions and macros ......114
Returncodes ............119
Server API configuration directives ......120
ServerAPIusagenotes.........120
Server API directives and syntax ......120
Server API directive variables .......121
Compatibility with other APIs ........122
Porting CGI programs .........122
Authentication and Authorization .....122
Environment variables .........123
ServerAPIvariables..........124
Chapter 8. Writing Java Servlets . . . 129
Overview of servlets ...........129
Chapter 9. Using Server-Side Includes 131
Considerations for using server-side includes. . . 131
Preparing to use server-side includes .....131
Format for server-side includes .......132
Directives for server-side includes ......132
Chapter 10. Troubleshooting your CGI
programs .............139
Chapter 7. Writing Server API
programs .............109
OverviewoftheServerAPI ........109
General procedure for writing Server API
programs...............109
Guidelines .............109
Basic server request process .......110
Application functions ..........111
Chapter 11. Notices .........145
Programming Interface Information ......146
Trademarks..............146
Readers’ Comments — We’d Like to
Hear from You ...........149
iv
Web Programming Guide V4R5
About HTTP Server for AS/400 Web Programming Guide (GC41-5435)
The web is an interactive medium. For example, it allows users to use search
utilities to locate information on a topic, give feedback to a company about its
products, and more. The IBM HTTP Server software does not perform these tasks.
They are performed by external programs using information passed to them by the
server. The HTTP Server for AS/400 Web Programming Guide tells you how to write
external programs that interact with the IBM HTTP Server for AS/400 product.
The HTTP Server for AS/400 Webmaster’s Guide, GC41-5434, describes the
configuration directives used to set up and control the IBM HTTP Server for
AS/400 product.
The IBM AS/400 Information Center presents information about the Web server and
many other AS/400 products and topics in an electronic, searchable database
format. The Information Center offers assistance in setting up and configuring your
Web server and publishing a Web site, as well as the advanced functions such as
logging and proxy serving. It is available on the Internet at
http://publib.boulder.ibm.com/html/as400/infocenter.html or on CD-ROM:
AS/400 Information Center, SK3T-2027-03
The IBM HTTP Server is IBM’s web server, and it is a cross platform product. With
the IBM HTTP Server you can serve multimedia objects such as Hypertext Markup
Language (HTML) documents to World Wide Web browser clients with your
AS/400 system. The IBM HTTP Server for AS/400 is fully HTTP 1.1 compliant.
The IBM HTTP Server for AS/400 (that was introduced in V4R3) replaces the IBM
AS/400 Internet Connection Server (ICS) introduced in OS/400 V4R1.
Conventions in this book
Boldface Indicates the name of an item you need to select, the name of a field, or a
string you must enter.
Italics Indicates book titles or variable information that must be replaced by an
actual value.
Bold italics Indicates a new term.
Monospace Indicates an example, a portion of a file, or a previously entered value.
AS/400 Operations Navigator
AS/400 Operations Navigator is a powerful graphical interface for Windows
clients. With AS/400 Operations Navigator, you can manage and administer your
AS/400 systems from your Windows desktop.
You can use Operations Navigator to manage communications, printing, database,
security, and other system operations. Operations Navigator includes Management
Central for managing multiple AS/400 systems centrally.
This new interface has been designed to make you more productive and is the
only user interface to new, advanced features of OS/400. Therefore, IBM
© Copyright IBM Corp. 1997, 2000 v
recommends that you use AS/400 Operations Navigator, which has online help to
guide you. While this interface is being developed, you may still need to use an
emulator such as PC5250 to do some of your tasks.
Installing Operations Navigator
To use AS/400 Operations Navigator, you must have Client Access installed on
your Windows PC. For help in connecting your Windows PC to your AS/400
system, consult Client Access Express for Windows - Setup, SC41-5507-01.
AS/400 Operations Navigator is a separately installable component of Client
Access that contains many subcomponents. If you are installing for the first time
and you use the Typical installation option, the following options are installed by
default:
v Operations Navigator base support
v Basic operations (messages, printer output, and printers)
To select the subcomponents that you want to install, select the Custom installation
option. (After Operations Navigator has been installed, you can add
subcomponents by using Client Access Selective Setup.)
After you install Client Access, double-click the AS400 Operations Navigator icon
on your desktop to access Operations Navigator and create an AS/400 connection.
Prerequisite and related information
Use the AS/400 Information Center as a starting point for your AS/400
information needs. It is available in either of the following ways:
v The Internet at this uniform resource locator (URL) address:
http://publib.boulder.ibm.com/html/as400/infocenter.html
v On CD-ROM: AS/400 Information Center, SK3T-2027-03 .
The AS/400 Information Center contains important topics such as logical
partitioning, clustering, Java, TCP/IP, Web serving, and secured networks. It also
contains Internet links to Web sites such as the AS/400 Online Library and the
AS/400 Technical Studio. Included in the Information Center is a link that
describes at a high level the differences in information between the Information
Center and the Online Library.
How to send your comments
Your feedback is important in helping to provide the most accurate and
high-quality information. If you have any comments about this book or any other
AS/400 documentation, fill out the readers’ comment form at the back of this
book.
v If you prefer to send comments by mail, use the readers’ comment form with the
address that is printed on the back. If you are mailing a readers’ comment form
from a country other than the United States, you can give the form to the local
IBM branch office or IBM representative for postage-paid mailing.
v If you prefer to send comments by FAX, use either of the following numbers:
– United States and Canada: 1-800-937-3430
– Other countries: 1-507-253-5192
v If you prefer to send comments electronically, use this network ID:
– IBMMAIL, to IBMMAIL(USIB56RZ)
vi Web Programming Guide V4R5
– RCHCLERK@us.ibm.com
Be sure to include the following:
v The name of the book.
v The publication number of the book.
v The page number or topic to which your comment applies.
About HTTP Server for AS/400 Web Programming Guide (GC41-5435) vii
viii Web Programming Guide V4R5
Chapter 1. Writing Common Gateway Interface Programs
OverviewoftheCGI ...........1
CGI and Dynamic Documents .......2
UsesforCGI.............3
The CGI process .............3
Overview..............3
SendingInformationtotheServer......5
Data Conversions on CGI Input and Output . . . 5
CGI Input Conversion Modes.......6
DBCS Considerations .........7
CGI Output Conversion Modes ......9
ReturningOutputfromtheServer......11
HowCGIProgramsWork ........12
This chapter discusses the Common Gateway Interface (CGI): What it is, why you
might want to use it, and how it works.
Overview of the CGI
CGI is a standard, supported by almost all web servers, that defines how
information is exchanged between a web server and an external program (CGI
program).
The CGI specification dictates how CGI programs get their input and how they
produce any output. CGI programs process data that is received from browser
clients. For example, the client fills out a form and sends the information back to
the server. Then the server runs the CGI program.
Parsing ..............12
Datamanipulation..........12
Response generation .........12
Environment variables ...........13
Requests from Standard Search (ISINDEX)
Documents.............15
Passing SSL Environment Variables to a CGI
Program..............15
CGI Programs and AS/400 Activation Groups . . . 17
AS/400 Activation Groups ........17
CGIConsiderations...........18
Activation Group Problem Examples .....18
Programs that are called by the server must conform to the server CGI interface in
order to run properly. We will describe this in further detail later in this chapter.
The administrator controls which CGI programs the system can run by using the
server directives. The server recognizes a URL that contains a request for a CGI
program, commonly called a CGI script. Depending on the server directives, the
server calls that program on behalf of the client browser.
For more information on CGI, see this URL:
http://www.w3.org/Daemon/User/CGI/Overview.html.
®
AS/400
supports CGI programs that are written in C++, Rexx, Java®, ILE-C,
ILE-RPG, and ILE-COBOL. It also supports multi-thread CGI programs in all of
these languages capable of multiple threads. For sample code that can help you
with CGI programs, see the AS/400 Web Builder’s Workshop. You can find it at the
following URL:
http://www.as400.ibm.com/tstudio/workshop/webbuild.htm.
You need to compile programs that are written in programming languages.
Compiled programs typically run faster than uncompiled programs. On the other
hand, those programs that are written in scripting languages tend to be easier to
write, maintain, and debug.
© Copyright IBM Corp. 1997, 2000 1
The functions and tasks that CGI programs can perform range from the simple to
the very advanced. In general, we call those that perform the simple tasks CGI
scripts because you do not compile them. We often call those that perform
complex tasks gateway programs. In this manual, we refer to both types as CGI
programs.
Given the wide choice of languages and the variety of functions, the possible uses
for CGI programs seem almost endless. How you use them is up to you. Once you
understand the CGI specification, you will know how servers pass input to CGI
programs and how servers expect output.
There are many uses for CGI programs. Basically, you should design them to
handle dynamic information. Dynamic in this context refers to temporary
information that is created for a one-time use and not stored anywhere on the web.
This information may be a document, an e-mail message, or the results of a
conversion program.
For detailed information about AS/400 CGI APIs, see “Chapter 2. Application
Programming Interfaces” on page 23.
CGI and Dynamic Documents
There are many types of files that exist on the web. Primarily they fall into one of
the following categories:
v Images
v Multimedia
v Programs
v HTML documents
Servers break HTML documents into two distinct types:
v Static
v Dynamic
Static documents exist in non-changing source form on the web server. You should
create Dynamic documents as temporary documents to satisfy a specific, individual
request.
Consider the process of ″serving″, these two types of documents. Responding to
requests for static documents is fairly simple. For example, Jill User accesses the
Acme web server to get information on the Pro-Expert gas grill. She clicks on
Products, then on Grills, and finally on Pro-Expert. Each time Jill clicks on a link,
the web browser uses the URL that is attached to the link to request a specific
document from the web server. The server responds by sending a copy of the
document to Jill’s browser.
What if Jill decides that, she wants to search through the information on the Acme
web server for all documents that contain information on Acme grills? Such
information could consist of news articles, press releases, price listings, and service
agreements. This is a more difficult request to process. This is not a request for an
existing document. Instead, it is a request for a dynamically generated list of
documents that meet certain criteria. This is where CGI comes in.
You can use a CGI program to parse the request and search through the
documents on your web server. You can also use it to create a list with hypertext
links to each of the documents that contain the specified word or string.
2 Web Programming Guide V4R5
Uses for CGI
HTML allows you to access resources on the Internet by using other protocols that
are specified in the URL. Examples of such protocols are mailto, ftp, and news. If
you code a link with mailto that is followed by an e-mail address, the link will
result in a generic mail form.
What if you wanted your customers to provide specific information, such as how
often they use the web? Or how they heard about your company? Rather than
using the generic mailto form, you can create a form that asks these questions and
more. You can then use a CGI program to interpret the information, include it in
an e-mail message, and send it to the appropriate person.
You do not need to limit CGI programs to processing search requests and e-mail.
You can use them for a wide variety of purposes. Basically, anytime you want to
take input from the reader and generate a response, you can use a CGI program.
The input may even be apparent to the reader. For example, many people want to
know how many other people have visited their home page. You can create a CGI
program that keeps track of the number of requests for your home page. This
program can display the new total each time someone links to your home page.
The CGI process
Usually CGI programs are referred to from within HTML documents. In general,
the HTML document format defines the environment variables that specify the
passing of information. When you design the layout of your HTML document, you
must keep in mind how a CGI program might affect the look of your document.
Developing the CGI program along with the HTML document will help you avoid
many design mistakes.
Overview
The CGI process involves three players: The web browser, the web server, and the
CGI program. To exemplify how CGI programs for online forms work, let us
assume that the web browser has already requested and obtained an HTML form.
1. The user clicks buttons or enters information in fields, and then clicks on an
2. The web browser then sends the data to the web server in an encoded format.
3. When the web server receives data, it converts the data to a format compliant
4. The CGI program then decodes and processes the data.
5. The system sends this response back to the web server in a form that is
6. The web server then interprets the response and forwards it to the web
Note: If a CGI application program must change the HTTP server job attributes
HTML button to submit the request.
For example, the data might consist of responses on an HTML form.
with the CGI specification for input and sends it to the CGI program.
compliant with the CGI specification for output.
browser.
while processing, the CGI program must restore the attributes to their initial
values before the CGI program ends. Failure to restore job attributes that are
changed in the CGI program will result in unpredictable responses to future
server requests. For example, a CGI program that requires a library in the
library list needs to add the library to the library list. The CGI program
must remove the library list before the CGI program ends.
Chapter 1. Writing Common Gateway Interface Programs 3
The following HTML form illustrates the various types of fields:
Note: The CGIXMP.EXE program referred to in this sample is just an example; it is
not shipped with the server product.
<HTML>
<HEAD>
<TITLE>CGIXMP Test Case</TITLE>
</HEAD>
<BODY>
<H1>CGI Sample Test Case</H1>
Fill in the following fields and press APPLY.
The values you enter will
be read by the CGIXMP.EXE program and displayed in a simple HTML
form which is generated dynamically by the program.
<P> <HR>
<form method=POST action="/cgi-bin/cgixmp">
<P>
<H3>Checkbox Field</H3>
<P>
<PRE>
<input type="checkbox" name="var1" value="123">
Check to set variable VAR1 to 123<BR>
<input type="checkbox" name="var2" value="XyZ" checked>
Check to set variable VAR2 to XyZ<BR>
</PRE>
<P>
<H3>Radio Button Field</H3>
<P>
<PRE>
<input type="radio" name="var3" value="1">
Select to set variable VAR3 to 1<BR>
<input type="radio" name="var3" value="2">
Select to set variable VAR3 to 2<BR>
<input type="radio" name="var3" value="3" checked>
Select to set variable VAR3 to 3<BR>
<input type="radio" name="var3" value="4">
Select to set variable VAR3 to 4<BR>
</PRE>
<P>
<H3>Single selection List Field</H3>
<P>
<PRE>
Select a value for variable VAR4 <select size=1 name="var4">
<option>0<option>1<option>2<option>3
<option>4<option>5</select>
</PRE>
<P>
<H3>Text Entry Field</H3>
<P>
<PRE>
Enter value for variable VAR5 <input type="text" name="var5"
size=20 maxlength=256 value="TEST value">
</PRE>
<P>
<H3>Multiple selection List Field</H3>
<P>
<PRE>
Select a value for variable VAR6
<select multiple size=2 name="var6">
<option>Ford<option>Chevrolet<option>Chrysler<option>
Ferrari<option>Porsche
</select>
</PRE>
<P>
<H3>Password Field</H3>
<P>
4 Web Programming Guide V4R5
<PRE>
Enter Password
<input type="password" name="pword" size=10 maxlength=10>
</PRE>
<P>
<H3>Hidden Field</H3>
<P>
<input type="hidden" name="hidden" value="Text not shown on form...">
<P>
<PRE>
<input type="submit" name="pushbutton" value="Apply">
<input type="reset" name="pushbutton" value="Reset">
<HR>
</PRE>
</FORM>
</BODY>
</HTML>
Sending Information to the Server
When you fill out a form, the web browser sends the request to the server in a
format that is described as URL-encoded. The web browser also performs this
function whenever you enter a phrase in a search field and click on the submission
button. In URL-encoded information:
v The URL starts with the URL of the processing program.
v A question mark (?) precedes attached data, such as name=value information
from a form, which the system appends to the URL.
v A plus sign (+) represents spaces.
v A percent sign (%) that is followed by the American National Standard Code for
Information Interchange (ASCII) hexadecimal equivalent of the symbol
represents special characters, such as a period (.) or slash (/).
v An ampersand (&) separates fields and sends multiple values for a field such as
check boxes.
Note: The method attribute specifies how the server sends the form information to
the program. You use the GET and POST methods in the HTML file to
process forms. The GET method sends the information through environment
variables. You will see the information in the URL after the ″?″ character.
The POST method passes the data through standard input.
The main advantage of using the GET method is that you can access the
CGI program with a query without using a form. In other words, you can
create canned queries that pass parameters to the program. For example, if
you want to send the previous query to the program directly, you can do
the following:
<A HREF="/cgi-bin/program.pgm?Name=John&LName=Richard&user=Smith%Company=IBM">
YourCGI Program</a>
The main advantage to the POST method is that the query length can be
unlimited so you do not have to worry about the client or server truncating
data. The query string of the GET method cannot exceed 4 KB.
Data Conversions on CGI Input and Output
The server can perform ASCII to EBCDIC conversions before sending data to CGI
programs. This is because the Internet is an ASCII world and the AS/400 is
primarily an extended binary-coded decimal interchange code (EBCDIC) world.
The server can also perform EBCDIC to ASCII conversions before sending data
Chapter 1. Writing Common Gateway Interface Programs 5
back to the browser. You must provide data to a CGI program through
environment variables and standard-input (stdin). HTTP and HTML specifications
allow you to tag text data with a character set (charset parameter on the
Content-Type header). However, this practice is not widely in use today (although
technically required for HTTP1.0/1.1 compliance). According to this specification,
text data that is not tagged can be assumed to be in the default character set
ISO-8859-1 (US-ASCII). AS/400 correlates this character set with ASCII CCSID 819.
There are basically three different ways the server can process the input to and
output from your CGI program. You can configure the server to control which
mode is used by specifying an overall server directive (CGIConvMode) or an
optional parameter on the Exec or Post-Script script directives:
CGIConvMode Mode
Exec request-template program-path [server-IP-address or hostname] [Mode]
Post-Script program_path_and_name [server-IP-address or hostname] [Mode]
Where Mode is one of the following:
%%MIXED%% or %%MIXED/MIXED%% This is the default.
%%EBCDIC%% or %%EBCDIC/MIXED%%
%%EBCDIC/EBCDIC%%
%%BINARY%% or %%BINARY/MIXED%%
%%BINARY/EBCDIC%%
%%BINARY/BINARY%%
%%EBCDIC_JCD%% or %%EBCDIC_JCD/MIXED%%
%%EBCDIC_JCD/EBCDIC%%
The CGIMode can be thought of as 2 logical pieces. The input mode and output
mode. They are separated by the ″/″. If only the input mode is provided, the
output mode is defaulted to MIXED for compatibility.
In addition, the system provides the following CGI environment variables to the
CGI program:
v CGI_MODE - which input conversion mode the server is using (%%MIXED%%,
%%EBCDIC%%, %%BINARY%%, or %%EBCDIC_JCD%%).
v CGI_ASCII_CCSID - from which ASCII CCSID was used to convert the data
v CGI_EBCDIC_CCSID - which EBCDIC CCSID the data was converted into
v CGI_OUTPUT_MODE - which output conversion mode the server is using
(%%MIXED%%, %%EBCDIC%%, or %%BINARY%%)
The following section explains CGI input conversion modes in more detail.
CGI Input Conversion Modes
MIXED
This mode is the default mode of operation for the server. The system
converts values for CGI environment variables to EBCDIC CCSID 37,
including QUERY_STRING. The system converts stdin data to the CCSID
of the job. However, the system still represents the encoded characters
“%xx” by the ASCII 819 octet. This requires the CGI program to convert
these further into EBCDIC to process the data. For more information, see
symptom, Special characters are not being converted or handled as expected in
“Chapter 10. Troubleshooting your CGI programs” on page 139.
EBCDIC
6 Web Programming Guide V4R5
In this mode, the server will convert everything into the EBCDIC CCSID of
the job. The server checks the Entity bodies for a charset tag. If found, the
server will convert the corresponding ASCII CCSID to the EBCDIC CCSID
of the job. If the server does not find a charset tag, it uses the value of the
DefaultNetCCSID configuration directive as the conversion CCSID. In
addition, the system converts escaped octets from ASCII to EBCDIC,
eliminating the need to perform this conversion in the CGI program.
BINARY
In this mode, the server processes environment variables (except
QUERY_STRING) the same way as EBCDIC mode. The server performs no
conversions on either QUERY_STRING or stdin data.
EBCDIC_JCD
Japanese browsers can potentially send data in one of three code pages, JIS
(ISO-2022-JP), S-JIS (PC-Windows), or EUC (UNIX). In this mode, the
server uses a well-known JCD utility to determine which codepage to use
(if not explicitly specified by a charset tag) to convert stdin data.
Table 1 summarizes the type of conversion that is performed by the server for each
CGI mode.
Table 1. Conversion action for text in CGI Stdin.
CGI_MODE Conversion Stdin
encoding
%%BINARY%% None No conversion FsCCSID No conversion No
%%EBCDIC%% NetCCSID to
FsCCSID
%%EBCDIC%% - with
charset tag received
%%EBCDIC_JCD%% Detect input based
%%MIXED%%
(Compatability mode)
Calculate target
EBCDIC CCSID
based on received
ASCII charset tag
on received data.
Convert data to
FsCCSID
NetCCSID to
FsCCSID (receive
charset tag is
ignored)
FsCCSID FsCCSID FsCCSID FsCCSID
EBCDIC
equivalent of
received
charset
FsCCSID FsCCSID Detect ASCII
FsCCSID with
ASCII escape
sequences
Environment
variables
FsCCSID FsCCSID FsCCSID
CCSID 37 CCSID 37 with
Query_String
encoding
input based on
received data.
Convert data to
FsCCSID
ASCII escape
sequences
conversion
Detect ASCII
input based
on received
data. Convert
data to
FsCCSID
CCSID37 with
ASCII escape
sequences
argv
encoding
DBCS Considerations
URL-encoded forms containing DBCS data could contain ASCII octets that
represent parts of DBCS characters. The server can only convert non-encoded
character data. This means that it must un-encode the double-byte character set
(DBCS) stdin and QUERY_STRING data before performing the conversion. In
addition, it has to reassemble and re-encode the resulting EBCDIC representation
before passing it to the CGI program. Because of this extra processing, CGI
programs that you write to handle DBCS data may choose to receive the data as
BINARY and perform all conversions to streamline the entire process.
Chapter 1. Writing Common Gateway Interface Programs 7
Using the EBCDIC_JCD mode: The EBCDIC_JCD mode determines what
character set is being used by the browser for a given request. This mode is also
used to automatically adjust the ASCII/EBCDIC code conversions used by the web
server as the request is processed.
After auto detection, the %%EBCDIC_JCD%% mode converts the stdin and
QUERY_STRING data from the detected network CCSID into the correct EBCDIC
CCSID for Japanese. The default conversions configured for the server instance are
overridden. The DefaultFsCCSID directive or the -fsccsid startup parameter
specifies the default conversions. The startup FsCCSID must be a Japanese CCSID
(5026 or 5035).
The possible detected network code page is Shift JIS, eucJP, and ISO-2022-JP. The
following are the associated CCSIDs for each code page:
Shift JIS (See note 1)
=========
CCSID 932: IBM PC (old JIS sequence, OS/2 J3.X/4.0, IBM Windows J3.1)
CCSID 942: IBM PC (old JIS sequence, OS/2 J3.X/4.0)
CCSID 943: MS Shift JIS (new JIS sequence, OS/2 J4.0
eucJP
=====
CCSID 5050: Extended UNIX Code (Japanese)
ISO-2022-JP (See note 2)
===========
CCSID 5052: Subset of RFC 1468 ISO-2022-JP (JIS X 0201 Roman and
MS Windows J3.1/95/NT)
JIS X 0208-1983) plus JIS X 0201 Katakana.
CCSID 5054: Subset of RFC 1468 ISO-20220JP (ASCII and JIS X 0208-1983)
plus JIS X 0201 Katakana.
The detected network CCSID is available to the CGI program. The CCSID is stored
in the CGI_ASCII_CCSID environment variable. When JCD can not detect, the
default code conversion is done as configured (between NetCCSID and FsCCSID).
(See note 3.)
Since the code page of Stdin and QUERY_STRING are encoded according to the
web client’s outbound code page, we recommend using the following
configuration value combinations when you use the %%EBCDIC_JCD%% mode.
Startup FsCCSID Startup NetCCSID Description
--------------- ---------------- ---------------------5026/5035 (See note 4) <-> 943 Default: MS Shift JIS
5026/5035 (See note 4) <-> 942 Default: IBM PC
5026/5035 (See note 4) <-> 5052/5054 Default: ISO-2022-JP
Using CCSID 5050(eucJP) for the startup NetCCSID, is not recommended. When
5050 is specified for the startup NetCCSID, the default code conversion is done
between FsCCSID and 5050. This means that if JCD cannot detect a code page, JCD
returns 5050 as the default network CCSID. Most browser’s use a default outbound
code page of Shift JIS or ISO-2022-JP, not eucJP.
If the web client sends a charset tag, JCD gives priority to the charset tag. Stdout
function is the same. If the charset/ccsid tag is specified in the Content-Type field,
stdout gives priority to charset/ccsid tag. Stdout also ignores the JCD detected
network CCSID. (See note 5.)
8 Web Programming Guide V4R5
Notes:
1. If startup NetCCSID is 932 or 942, detected network, Shift JIS’s CCSID is the
same as startup NetCCSID. Otherwise, Shift JIS’s CCSID is 943.
Startup NetCCSID Shift JIS (JCD detected CCSID)
---------------- -----------------------------932 932
942 942
943 943
5052 943
5054 943
5050 943
2. Netscape Navigator 3.x sends the alphanumeric characters by using JIS X 0201
Roman escape sequence (CCSID 5052) for ISO-2022-JP. Netscape Communicator
4.x sends the alphanumeric characters by using ASCII escape sequence (CCSID
5054) for ISO-2022-JP.
3. JCD function has the capability to detect EUC and SBCS Katakana, but it is
difficult to detect them. IBM
®
recommends that you do not use SBCS Katakana
and EUC in CGI.
4. CCSID 5026 assigns lowercase alphabet characters on special code point. This
often causes a problem with lowercase alphabet characters. To avoid this
problem, do one of the following:
v Do not use lowercase alphabet literals in CGI programs if the FsCCSID is
5026.
v Use CCSID 5035 for FsCCSID.
v Use the Charset/CCSID tag as illustrated in the following excerpt of a CGI
program:
main(){
printf("Content-Type: text/html; Charset=ISO-2022-JP\n\n");
...
}
v Do the code conversions in the CGI program. The following sample C
program converts the literals into CCSID 930 (the equivalent to CCSID 5026)
main(){
printf("Content-Type: text/html\n\n);
#pragama convert(930)
printf("<html>");
printf("This is katakana code page\n");
#pragama convert(0)
...
}
5. When the web client sends a charset tag, the network CCSID becomes the
ASCII CCSID associated with Multipurpose Internet Mail Extensions (MIME)
charset header. The charset tag ignores the JCD detected CCSID. When the
Charset/ccsid tag is in the Content-Type header generated by the CGI program,
the JCD-detected CCSID is ignored by this charset/ccsid. Stdout will not
perform a conversion if the charset is the same as the MIME’s charset. Stdout
will not perform a conversion if the CCSID is ASCII. Stdout will perform code
conversion if the CCSID is EBCDIC. Because the environment variables and
stdin are already stored in FsCCSID, ensure that you are consistent between the
FsCCSID and the Content-Type header’s CCSID.
CGI Output Conversion Modes
The CgiConv mode includes an output mode. This section explains CGI output
conversion modes in more detail.
Chapter 1. Writing Common Gateway Interface Programs 9
%%MIXED%%
In this mode HTTP header output is in CCSID 37. However, the escape
sequence must be the EBCDIC representative of the ASCII code point for
the 2 characters following the ″%″ in the escape sequence. An example of a
HTTP header that may contain escape sequences is the Location header.
%%EBCDIC%%
In this mode HTTP header output is in CCSID 37. However, the escape
sequence must be the EBCDIC representative of the EBCDIC code point for
the 2 characters following the ″%″ in the escape sequence. An example of a
HTTP header that may contain escape sequences is the Location header.
%%BINARY%%
In this mode HTTP header output is in CCSID 819 with the escape
sequences also being the ASCII representative of the ASCII code point. An
example of a HTTP header that may contain escape sequences is the
Location header.
For HTTP body standard-output (stdout) data that is sent from the CGI program,
the server recognizes and uses the charset or CCSID parameter on the text/*
Content-Types. If you specify ASCII, the server performs no conversions on the
data. Otherwise, the system uses the Content-Type value instead of the
DefaultFsCCSID on conversions back to the browser. The system sets an
appropriate charset tag for all text/* Content-Types that it sends back to the
browser. The exception to this is %%MIXED%%, %%MIXED/MIXED%%,
%%BINARY/BINARY%% modes and when the charset or CCSID parameter is set
to 65535.
Table 2 summarizes the type of conversion that is performed and the charset tag
that is returned to the browser by the server.
Table 2. Conversion action and charset tag generation for text in CGI Stdout.
CGI Stdout CCSID/Charset in HTTP header Conversion action Server reply charset tag
EBCDIC CCSID/Charset Calculate EBCDIC to ASCII
conversion based on supplied
EBCDIC CCSID/Charset
ASCII CCSID/Charset No conversion Stdout CCSID/Charset as Charset
65535 No conversion None
None (%%BINARY%%,
%%BINARY/MIXED%%, or
%%BINARY/EBCDIC%%)
None (%%BINARY/BINARY%%) No Conversion None
None (%%EBCDIC%%,
%%EBCDIC/MIXED%%, or
%%EBCDIC/EBCDIC%%)
None (%%EBCDIC%%,
%%EBCDIC/MIXED%%, or
%%EBCDIC/EBCDIC%% with charset tag
received on HTTP request)
None (%%EBCDIC_JCD%%,
%%EBCDIC_JCD/MIXED%%, or
%%EBCDIC_JCD/EBCDIC%%)
Default Conversion - FsCCSID to
NetCCSID
Default Conversion - FsCCSID to
NetCCSID
Use inverse of conversion
calculated for stdin
Default Conversion - FsCCSID to
NetCCSID
Calculated ASCII charset
NetCCSID as charset
NetCCSID as charset
Charset as received on HTTP
request
NetCCSID as charset
10 Web Programming Guide V4R5
Table 2. Conversion action and charset tag generation for text in CGI Stdout. (continued)
CGI Stdout CCSID/Charset in HTTP header Conversion action Server reply charset tag
None (%%MIXED%% or
%%MIXED/MIXED%%)
Invalid CGI error 500 generated by server
Default Conversion - FsCCSID to
NetCCSID
None (compatibility mode)
The server also sets an environment variable CGI_OUTPUT_MODE to reflect the
setting for the CGI output mode. It contains the CGI output conversion mode the
server is using for this request. Valid values are %%EBCDIC%%, %%MIXED%%, or
%%BINARY%%. The program can use this information to determine what
conversion, if any, the server performs on CGI output.
Returning Output from the Server
When the CGI program is finished, it passes the resulting response to the server by
using standard output (stdout). The server interprets the response and sends it to
the browser.
A CGI program writes a CGI header that is followed by an entity body to standard
output. The CGI header is the information that describes the data in the entity
body. The entity body is the data that the server sends to the client. A single
newline character always ends the CGI header. The newline character for ILE/C is
\n. For ILE/RPG or ILE/COBOL, it is hexadecimal ’15’. The following are some
examples of Content-Type headers:
Content-Type: text/html\n\n
Content-Type: text/html; charset=iso-8859-2\n\n
If the response is a static document, the CGI program returns either the URL of the
document using the CGI Location header or returns a Status header. The CGI
program does not have an entity body when using the Location header. If the host
name is the local host, the HTTP server will retrieve the specified document that
the CGI program sent. It will then send a copy to the web browser. If the host
name is not the local host, the HTTP processes it as a redirect to the web browser.
For example:
Location: http://www.acme.com/products.html\n\n
The Status header should have a Content_Type: and a Status in the CGI header.
When Status is in the CGI header, an entity body should be sent with the data to
be returned by the server. The entity body data contains information that the CGI
program provides to a client for error processing. The Status line is the Status with
an HTTP 3 digit status code and a string of alphanumeric characters (A-Z, a-z, 0-9
and space). The HTTP status code must be a valid 3 digit number from the
HTTP/1.1 specification.
Note: The newline character \n ends the CGI header.
CONTENT-TYPE: text/html\n
Status: 600 Invalid data\n
\n
<html><head><title>Invalid data</title>
</head><body>
<h1>Invalid data typed</h1>
<br><pre>
The data entered must be valid numeric digits for id number
<br></pre>
</body></html>
Chapter 1. Writing Common Gateway Interface Programs 11
How CGI Programs Work
Most CGI programs include the following three stages:
v Parsing CGI programs
v Data manipulation within a CGI program
v Response generation by a CGI program
Parsing
Parsing is the first stage of a CGI program. In this stage, the program takes the
data from QUERY_STRING environment variable, command line arguments using
argv() or standard input. When the method is GET, the system reads the data from
the QUERY_STRING environment variable or command line arguments by using
argv(). There is no way to determine the length of data in QUERY_STRING. The
system encodes the QUERY_STRING data in the request header.
An example of data read in the QUERY_STRING variable (%%MIXED%% mode):
NAME=Eugene+T%2E+Fox&ADDR=etfox%40ibm.net&INTEREST=RCO
Parsing breaks the fields at the ampersands and decodes the ASCII hexadecimal
characters. The results look like this:
NAME=Eugene T. Fox
ADDR=etfox@ibm.net
INTEREST=RCO
You can use the QtmhCvtDb API to parse the information into a structure. The
CGI program can refer to the structure fields. If using %%MIXED%% input mode,
the “%xx” encoding values are in ASCII and must be converted into the “%xx”
EBCDIC encoding values before calling QtmhCvtDb. If using %%EBCDIC%%
mode, the server will do this conversion for you. The system converts ASCII
“%xx” first to the ASCII character and then to the EBCDIC character. Ultimately,
the system sets the EBCDIC character to the “%xx” in the EBCDIC CCSID. For
code samples, use the following URL to the AS/400 web site:
http://www.as400.ibm.com/tstudio/index.htm.
When the method is post, the system reads the data from standard input. Before
the CGI attempts to read standard input, it must check environment variables
REQUEST_METHOD and CONTENT_LENGTH. Read standard input only when
the REQUEST_METHOD is POST. The read must specify no more than
CONTENT_LENGTH bytes. Attempts to specify more than CONTENT_LENGTH
bytes on reading standard input are not defined.
Data manipulation
Data manipulation is the second stage of a CGI program. In this stage, the
program takes the parsed data and performs the appropriate action. For example, a
CGI program designed to process an application form might perform one of the
following functions:
1. Take the input from the parsing stage
2. Convert abbreviations into more meaningful information
3. Plug the information into an e-mail template
4. Use SNDDST to send the e-mail.
Response generation
Response generation is the final stage of a CGI program. In this stage, the program
formulates its response to the web server, which forwards it to the browser. The
response contains MIME headers that vary depending on the type of response.
12 Web Programming Guide V4R5
With a search, the response might be the URLs of all the documents that met the
search value. With a request that results in e-mail, the response might be a
message that confirms that the system actually sent the e-mail.
Environment variables
Before you begin writing your CGI program, you need to understand the format in
which the server will pass the data. The server receives the URL-encoded
information and, depending on the type of request, passes the information to the
CGI program. The server does this by using environment variables, command line
arguments, or standard input.
A CGI application program should be able to handle a NULL value when getting
an environment variable. For example, when the CGI program is trying to do a
getenv(″CONTENT_LENGTH″) and the method is GET, the value would be
returned NULL. This is because CONTENT_LENGTH is only defined in method
POST (to describe the length of standard input).
The system supports the following environment variables:
AUTH_TYPE
If the server supports client authentication and the script is a protected
script, this environment variable contains the method that is used to
authenticate the client. For example:
Basic
CGI_ASCII_CCSID
Contains the ASCII CCSID the server used when converting CGI input
data. If the server did not perform any conversion, (for example, in
%%BINARY%% mode), the server sets this value to the DefaultNetCCSID
configuration directive value.
CGI_MODE
Contains the CGI conversion mode the server is using for this request.
Valid values are %%EBCDIC%%, %%MIXED%%, %%BINARY%%, or
%%EBCDIC_JCD%%. The program can use this information to determine
what conversion, if any, was performed by the server on CGI input data
and what format that data is currently in.
CGI_EBCDIC_CCSID
Contains the EBCDIC CCSID under which the current server job is running
(DefaultFsCCSID configuration directive). It also represents the current job
CCSID that is used during server conversion (if any) of CGI input data.
CONTENT_LENGTH
When the method of POST is used to send information, this variable
contains the number of characters. Servers typically do not send an
end-of-file flag when they forward the information by using stdin. If
needed, you can use the CONTENT_LENGTH value to determine the end
of the input string. For example:
7034
CONTENT_TYPE
When information is sent with the method of POST, this variable contains
the type of data included. You can create your own content type in the
server configuration file and map it to a viewer. For example:
Application/x-www-form-urlencoded
Chapter 1. Writing Common Gateway Interface Programs 13
GATEWAY_INTERFACE
Contains the version of CGI that the server is using. For example:
CGI/1.1
HTTP_ACCEPT
Contains the list of MIME types the browser accepts. For example:
text/html
HTTP_USER_AGENT
Contains the name of your browser (web client). It includes the name and
version of the browser, requests that are made through a proxy, and other
information. For example:
Netscape Navigator dll /v3.0
IBM_CCSID_VALUE
The CCSID under which the current server job is running.
PATH_INFO
Contains the additional path information as sent by the web browser. For
example:
/ballyhoo
PATH_TRANSLATED
Contains the decoded or translated version of the path information that is
contained in PATH_INFO, which takes the path and does any
virtual-to-physical mapping to it. For example:
/wwwhome/ballyhoo
QUERY_STRING
When information is sent using a method of GET, this variable contains the
information in a query that follows the ?. The string is coded in the
standard URL format of changing spaces to “+” and encoding special
characters with “%xx” hexadecimal encoding. The CGI program must
decode this information. For example:
NAME=Eugene+T%2E+Fox&ADDR=etfox%7Cibm.net&INTEREST=xyz
REMOTE_ADDR
Contains the IP address of the remote host (web browser) that is making
the request, if available. For example:
9.23.06.8
REMOTE_HOST
Contains the host name of the web browser that is making the request, if
available. For example:
raleigh.ibm.com
REMOTE_IDENT
Contains the user ID of the remote user. For example:
Jillx
REMOTE_USER
If you have a protected script and the server supports client authentication,
this environment variable contains the user name that is passed for
authentication. For example:
Jill
REQUEST_METHOD
14 Web Programming Guide V4R5
Contains the method (as specified with the METHOD attribute in an
HTML form) that is used to send the request. For example:
GET or POST
SCRIPT_NAME
A virtual path to the program being run. Use this for self-referring URLs.
SERVER_NAME
Contains the server host name or IP address of the server. For example:
www.ibm.com
SERVER_PORT
Contains the port number to which the client request was sent. For
example:
80
SERVER_PROTOCOL
Contains the name and version of the information protocol that is used to
make the request. For example:
HTTP/1.0
SERVER_SOFTWARE
Contains the name and version of the information server software that is
answering the request. For example:
IBM-Secure-ICS/AS/400 Secure HTTP Server
Requests from Standard Search (ISINDEX) Documents
ISINDEX is an HTML tag that identifies the document as a standard search
document and causes the browser to automatically generate an entry field. When
information is sent from an ISINDEX document, the server takes the appended
data (the information following the ?), breaks it at the pluses (+), and sends the
data to the CGI program as command line arguments (argv). For example:
<ISINDEX>
Note: It is possible to write CGI scripts that display all environment variables. At
times these variables may include sensitive data such as user IDs and
passwords for various products. Consequently, you must be careful about
displaying environment variables in your CGI scripts, and you must be
careful about who has access to them.
Passing SSL Environment Variables to a CGI Program
You can use the following SSL-related environment variables in CGI programs.
HTTPS
Returns ON if the system has completed an SSL handshake. It returns OFF
if the exchange of signals to set up communications between two modems
has failed. For example:
OFF
HTTPS_CLIENT_CERT
The entire certificate passed to the server from the client browser when
SSL Client authentication is enabled. The format of the certificate is a
BASE64 encoded string that represents the DER format of the X.509
certificate.
HTTPS_CLIENT_CERT_COUNTRY
The Country Code from the client certificate’s distinguished name. For
example:
US
Chapter 1. Writing Common Gateway Interface Programs 15
HTTPS_CLIENT_CERT_COMMON_NAME
The Common Name from the client certificate’s distinguished name. For
example:
John Smith
HTTPS_CLIENT_CERT_ISSUER_COMMON_NAME
The Common Name of the Certificate Authority that issued the client’s
certificate. For example:
Digital ID
HTTPS_CLIENT_CERT_ISSUER_COUNTRY
The Country code of the Certificate Authority that issued the client’s
certificate. For example:
US
HTTPS_CLIENT_CERT_ISSUER_LOCALITY
The Locality of the Certificate Authority that issued the client’s certificate.
For example:
50265
HTTPS_CLIENT_CERT_ISSUER_STATE_OR_PROVINCE
The State or Province of the Certificate Authority that issued the client’s
certificate. For example:
Iowa
HTTPS_CLIENT_CERT_ISSUER_ORG_UNIT
The Organizational Unit of the Certificate Authority that issued the client’s
certificate. For example:
Department of Client Certificates
HTTPS_CLIENT_CERT_ISSUER_ORGANIZATION
The Organization name of the Certificate Authority that issued the client’s
certificate. For example:
Roadrunner CA
HTTPS_CLIENT_CERT_LEN
The Length of the certificate passed in HTTPS_CLIENT_CERT.
HTTPS_CLIENT_CERT_LOCALITY
The Locality (zip code in the US) from the client certificate’s distinguished
name. For example:
55901
HTTPS_CLIENT_CERT_SERIAL_NUM
The serial number assigned by the issuing Certificate Authority. For
example:
92787829
HTTPS_CLIENT_CERT_ORG_UNIT
The Organizational Unit name from the client certificate’s distinguished
name. For example:
Department of Coyote products
HTTPS_CLIENT_CERT_ORGANIZATION
The Organization name from the client certificate’s distinguished name. For
example:
Acme Corporation
16 Web Programming Guide V4R5
HTTPS_CLIENT_CERT_STATE_OR_PROVINCE
The State or Province from the client certificate’s distinguished name. For
example:
Minnesota
HTTPS_KEYSIZE
Returns the number of bits in the session key that is established by SSL
after a completed exchange of signals to set up communications between
two modems. This value is blank if HTTPS=OFF. For example:
512
Examples of key sizes are Export {40} or {128}.
HTTPS_PORT
If a valid security product is installed and the SSLMode directive is
SSLMode=ON, this environment variable contains the SSL port number the
server is listening on. For example:
443
CGI Programs and AS/400 Activation Groups
The following section is intended to give a brief overview of AS/400 Activation
Groups.
Note: It is very important to become familiar with the details of activation groups
prior to developing or porting a CGI application that will use this support.
AS/400 Activation Groups
Program activation is the process that is used to prepare a program to run. The
system must activate AS/400 ILE programs before they can be run. Program
activation includes the allocation and initialization of static storage for the program
in addition to completing the binding of programs to service programs.
Program activation is not an AS/400 unique concept. All modern computer
operating systems must perform program initialization and load. What is unique to
AS/400 is the concept of Activation Groups. All ILE programs and service
programs are activated within an activation group. This substructure contains the
resources necessary to run the program. The resources that are contained and are
managed with an activation group include:
v Static and automatic program variables
v Dynamic storage
v Temporary data management resources (For example, open files and SQL
cursors)
v Certain types of exception handlers and ending procedures
Run-time creation of ILE activation groups is controlled by specifying an activation
group attribute when your program or service program is created. The attribute is
specified by using the ACTGRP parameter on the CRTPGM or CRTSRVPGM
command. The valid options for this attribute include user-named, *NEW, and
*CALLER. The following is a brief description of these options:
user-named - A named activation group allows you to manage a collection of
ILE programs and ILE service programs as one application. The activation
group is created when it is first needed. All programs and service programs
that specify the same activation group name use it then.
Chapter 1. Writing Common Gateway Interface Programs 17
*NEW- The name for this activation group is selected by ILE and will always
be unique. System-named activation groups are always deleted when the high
level language returns.
*CALLER - Specifying *CALLER causes the ILE program or service program to
be activated within the activation group of the calling program. A new
activation group is never created with this attribute.
*NEW is the standard behavior that can be expected on other systems such as
®
UNIX
Notes:
1. When you create a persistent CGI program, you must specify a named
2. CGI programs that are not persistent should not refer to job-level scoped
For additional information about activation groups see, ILE Concepts, SC41-5606
book.
.
activation group.
resources.
CGI Considerations
There are advantages to running CGI programs in either a user-named or
*CALLER activation group. The performance overhead associated with activating a
CGI every time that is requested can be drastically reduced. It is important to
understand that because the system does not delete user-named activation groups,
normal high level language end verbs cannot provide complete end processing. For
example, the system will not close open files, and the system will not return the
static and heap storage that are allocated by a program. The program must manage
these resources explicitly. This will be especially important when moving CGI
programs that rely on end processing to function properly.
Note: When you activate multi-threaded CGI on your web server, you get multiple
thread support for your CGI application Your CGI application must end all
of its threads before returning to the server. When using multi-thread
capable CGI, you need to put the CGI program in a new or named
activation group.
The following section shows examples which will work fine running in a *NEW
activation group, however will cause problems if run in a user-named or *CALLER
activation group.
Activation Group Problem Examples
Note
The following examples are not general CGI programming examples. For
general CGI programming examples, see “Chapter 6. Sample programs (in
Java, C, and RPG)” on page 89.
In the following example a CGI program when run in a *NEW activation group,
would write Hello World to the browser. What is important to understand is that
this application is taking advantage of job end processing to delete the stdio
buffers that are used to buffer the stdout data.
You could build the following CGI program to run in either a user-named or
*CALLER activation group. In such an instance, the server will not process the
18 Web Programming Guide V4R5
information that was written to stdout. This will cause the web browser to display
a ″Document Contains No Data″ error message. Another application could run
again in the same activation group that properly erased stdout. In this instance, the
data that has been buffered from previous calls would be sent.
#include <stdio.h>
void main(void) {
/***************************************************/
/* Write header information. */
/***************************************************/
printf("Content-type: text/html\n\n");
/***************************************************/
/* Write header information. */
/***************************************************/
printf("Hello World\n");
}
End processing may not erase stdio buffers so the application must erase the
stdout with a fflush(stdout) call. The following example will work regardless of the
activation group specification:
#include <stdio.h>
void main(void) {
/***************************************************/
/* Write header information. */
/***************************************************/
printf("Content-type: text/html\n\n");
/***************************************************/
/* Write header information. */
/***************************************************/
printf("Hello World\n");
/*-------------------------------------------------*/
/* FIX: Flush stdout. */
/*-------------------------------------------------*/
fflush(stdout);
}
When run in a *NEW activation group, this example CGI would read
CONTENT_LENGTH bytes of data from stdin and write this back out to stdout.
The system has allocated the buffer that is used to hold the data with a malloc.
Like the example that is previously shown, this application is relying on several
aspects of job end processing to function properly.
If this CGI program were built to run in either a user-named or *CALLER
activation group, the following problems would occur:
v As with the simple example that is previously shown, the application is not
erasing stdout. This would cause the web browser to display a ″Document
Contains No Data″ error message. You could run another application again in
the same activation group that properly erased stdout. This would send the data
that has been buffered from previous calls.
v Stdin is buffered similar to stdout. If the contents of stdin are not erased, the
stdin data on the second and all following calls of the CGI program will be
unpredictable and the contents may at times contain information from
subsequent requests.
Chapter 1. Writing Common Gateway Interface Programs 19
v The heap storage allocated using malloc is not being freed. Over time, a memory
leak error like this could use significant amounts of memory. This is a common
application error that only surfaces when the application is not running in a
*NEW activation group.
/*************************************************************************/
/* */
/* CGI Example program. */
/* */
/*************************************************************************/
#include
void main(void)
{
char* stdinBuffer;
char* contentLength;
int numBytes;
int bytesRead;
FILE* pStdin;
/**********************************************************************/
/* Write the header. */
/**********************************************************************/
printf("Content-type: text/html\n\n");
/**********************************************************************/
/* Get the length of data on stdin. */
/**********************************************************************/
contentLength = getenv("CONTENT_LENGTH");
if (contentLength != NULL) {
/*******************************************************************/
/* Allocate storage and clear the storage to hold the data. */
/*******************************************************************/
numBytes = atoi(contentLength);
stdinBuffer = (char*)malloc(numBytes+1);
if ( stdinBuffer )
memset(stdinBuffer, 0x00, numBytes+1);
/*******************************************************************/
/* Read the data from stdin and write back to stdout. */
/*******************************************************************/
bytesRead = fread(stdinBuffer, 1, numBytes, pStdin);
stdinBufferþbytesRead+1þ = '\0';
printf("%s", stdinBuffer);
} else
printf("Error getting content length\n");
return;
}
The following example shows the changes that would be required to this
application to allow it to run in a user-named or *CALLER activation group:
/*************************************************************************/
/* */
/* CGI Example program with changes to support user-named */
/* and *CALLER ACTGRP. */
/* */
/*************************************************************************/
#include
void main(void)
20 Web Programming Guide V4R5
Loading...