IBM AS-400e User Manual 2

4 (1)

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.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract

with IBM Corp.

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

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

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

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 11. Notices .........145

Programming Interface Information ......146

Trademarks..............146

Readers’ Comments — We’d Like to

Hear from You ...........149

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

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

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

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.

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.

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

HTML button to submit the request.

2. The web browser then sends the data to the web server in an encoded format.

For example, the data might consist of responses on an HTML form.

3. When the web server receives data, it converts the data to a format compliant

with the CGI specification for input and sends it to the CGI program.

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

compliant with the CGI specification for output.

6. The web server then interprets the response and forwards it to the web

browser.

Note: If a CGI application program must change the HTTP server job attributes

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>

<H3>Checkbox Field</H3>

<P>

<PRE>

Check to set variable VAR1 to 123<BR>

Check to set variable VAR2 to XyZ<BR>

</PRE>

<P>

<H3>Radio Button Field</H3>

<P>

<PRE>

Select to set variable VAR3 to 1<BR>

Select to set variable VAR3 to 2<BR>

Select to set variable VAR3 to 3<BR>

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

</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

<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

</PRE>

<P>

<H3>Hidden Field</H3>

<P>

<P>

<PRE>

<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:

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

Environment

variables

Query_String

encoding

argv

encoding

%%BINARY%% None No conversion FsCCSID No conversion No

conversion

%%EBCDIC%% NetCCSID to

FsCCSID

FsCCSID FsCCSID FsCCSID FsCCSID

%%EBCDIC%% - with

charset tag received

Calculate target

EBCDIC CCSID

based on received

ASCII charset tag

EBCDIC

equivalent of

received

charset

FsCCSID FsCCSID FsCCSID

%%EBCDIC_JCD%% Detect input based

on received data.

Convert data to

FsCCSID

FsCCSID FsCCSID Detect ASCII

input based on

received data.

Convert data to

FsCCSID

Detect ASCII

input based

on received

data. Convert

data to

FsCCSID

%%MIXED%%

(Compatability mode)

NetCCSID to

FsCCSID (receive

charset tag is

ignored)

FsCCSID with

ASCII escape

sequences

CCSID 37 CCSID 37 with

ASCII escape

sequences

CCSID37 with

ASCII escape

sequences

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

MS Windows J3.1/95/NT)

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

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

Calculated ASCII charset

ASCII CCSID/Charset No conversion Stdout CCSID/Charset as Charset

65535 No conversion None

None (%%BINARY%%,

%%BINARY/MIXED%%, or

%%BINARY/EBCDIC%%)

Default Conversion - FsCCSID to

NetCCSID

NetCCSID as charset

None (%%BINARY/BINARY%%) No Conversion None

None (%%EBCDIC%%,

%%EBCDIC/MIXED%%, or

%%EBCDIC/EBCDIC%%)

Default Conversion - FsCCSID to

NetCCSID

NetCCSID as charset

None (%%EBCDIC%%,

%%EBCDIC/MIXED%%, or

%%EBCDIC/EBCDIC%% with charset tag

received on HTTP request)

Use inverse of conversion

calculated for stdin

Charset as received on HTTP

request

None (%%EBCDIC_JCD%%,

%%EBCDIC_JCD/MIXED%%, or

%%EBCDIC_JCD/EBCDIC%%)

Default Conversion - FsCCSID to

NetCCSID

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%%)

Default Conversion - FsCCSID to

NetCCSID

None (compatibility mode)

Invalid CGI error 500 generated by server

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

<html><head><title>Invalid data</title>

</head><body>

<h1>Invalid data typed</h1>

The data entered must be valid numeric digits for id number

</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

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

14 Web Programming Guide V4R5

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:

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:

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:

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:

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

activation group.

2. CGI programs that are not persistent should not refer to job-level scoped

resources.

For additional information about activation groups see, ILE Concepts, SC41-5606

book.

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

+ 133 hidden pages

IBM AS-400e User Manual 2

Contents

Conventions in this book

AS/400 Operations Navigator

Installing Operations Navigator

Prerequisite and related information

How to send your comments

Chapter 1. Writing Common Gateway Interface Programs

Overview of the CGI

CGI and Dynamic Documents

Uses for CGI

The CGI process

Overview

Sending Information to the Server

Data Conversions on CGI Input and Output

CGI Input Conversion Modes

DBCS Considerations

CGI Output Conversion Modes

Returning Output from the Server

How CGI Programs Work

Parsing

Data manipulation

Response generation

Environment variables

Requests from Standard Search (ISINDEX) Documents

Passing SSL Environment Variables to a CGI Program

CGI Programs and AS/400 Activation Groups

AS/400 Activation Groups

CGI Considerations

Activation Group Problem Examples