141 lines
9.6 KiB
HTML
141 lines
9.6 KiB
HTML
|
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
|
<!DOCTYPE html
|
||
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html lang="en-us" xml:lang="en-us">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
|
<meta name="security" content="public" />
|
||
|
|
<meta name="Robots" content="index,follow" />
|
||
|
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
||
|
|
<meta name="DC.Type" content="topic" />
|
||
|
|
<meta name="DC.Title" content="Overview of Persistent CGI" />
|
||
|
|
<meta name="abstract" content="Persistent CGI is an extension to the CGI interface that allows a CGI program to remain active across multiple browser requests and maintain a session with that browser client. This allows files to be left open, the state to be maintained, and long running database transactions to be committed or rolled-back based on end-user input." />
|
||
|
|
<meta name="description" content="Persistent CGI is an extension to the CGI interface that allows a CGI program to remain active across multiple browser requests and maintain a session with that browser client. This allows files to be left open, the state to be maintained, and long running database transactions to be committed or rolled-back based on end-user input." />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="rzaieparcgi.htm" />
|
||
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 2002,2006" />
|
||
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 2002,2006" />
|
||
|
|
<meta name="DC.Format" content="XHTML" />
|
||
|
|
<meta name="DC.Identifier" content="rzag3ch3ovrvwpercgi" />
|
||
|
|
<meta name="DC.Language" content="en-us" />
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
||
|
|
<title>Overview of Persistent CGI</title>
|
||
|
|
</head>
|
||
|
|
<body id="rzag3ch3ovrvwpercgi"><a name="rzag3ch3ovrvwpercgi"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">Overview of Persistent CGI</h1>
|
||
|
|
<div><p><dfn class="term">Persistent CGI</dfn> is an extension to the CGI interface
|
||
|
|
that allows a CGI program to remain active across multiple browser requests
|
||
|
|
and maintain a session with that browser client. This allows files to be left
|
||
|
|
open, the state to be maintained, and long running database transactions to
|
||
|
|
be committed or rolled-back based on end-user input. </p>
|
||
|
|
<p>The CGI program must be written using named activation groups which allows
|
||
|
|
the program to remain active after returning to the server. The CGI program
|
||
|
|
notifies the server it wants to remain persistent using the ″Accept-HTSession″
|
||
|
|
CGI header as the first header it returns. This header defines the session
|
||
|
|
ID associated with this instance of the CGI program and is not returned to
|
||
|
|
the browser. Subsequent URL requests to this program must contain the session
|
||
|
|
ID as the first parameter after the program name. The server uses this ID
|
||
|
|
to route the request to that specific instance of the CGI program. The CGI
|
||
|
|
program should regenerate this session ID for each request. It is strongly
|
||
|
|
recommended that you use Secure Sockets Layer (SSL) for persistent and secure
|
||
|
|
business transaction processing.</p>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="rzaieparcgi.htm" title="This topic provides information about Common Gateway Interfaces (CGI).">Common Gateway Interface</a></div>
|
||
|
|
</div>
|
||
|
|
</div><div class="nested1" xml:lang="en-us" id="namedactivationgroups"><a name="namedactivationgroups"><!-- --></a><h2 class="topictitle2">Named Activation Groups</h2>
|
||
|
|
<div><p>CGI programs can be built using named activation groups by specifying a
|
||
|
|
name on the ACTGRP parameter of the CRTPGM or CRTSRVPGM commands. In doing
|
||
|
|
this, the initial call to the program within the job will still have the startup
|
||
|
|
cost of activating the program. However, an activation group is left active
|
||
|
|
after the program has exited normally. All storage associated with that program
|
||
|
|
is still allocated and in ″last-used″ state. The program is not initialized
|
||
|
|
when it is called again. In addition, for the ILE C runtime, all settings
|
||
|
|
are in ″last-used″ state, such as signal(), strtok(). The RCLACTGRP command
|
||
|
|
is used to end a named activation group. Use the DSPJOB OPTION(*ACTGRP) command
|
||
|
|
to display all the activation groups for the job. All ILE languages running
|
||
|
|
on the server can use this mechanism to enable persistence for their CGI programs.</p>
|
||
|
|
<p>For additional information about activation groups see the <a href="../books/sc415606.pdf" target="_blank">ILE Concepts</a>, SC41-5606 book.</p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="nested1" xml:lang="en-us" id="accept-htsessioncgiheader"><a name="accept-htsessioncgiheader"><!-- --></a><h2 class="topictitle2">Accept-HTSession CGI Header</h2>
|
||
|
|
<div><p>This header specifies the session handle associated with this instance
|
||
|
|
of the Persistent CGI program. This session handle is used to route back subsequent
|
||
|
|
requests to that program and must be unique, or the server will not honor
|
||
|
|
the persistence request. A message is logged in the error log of the server.</p>
|
||
|
|
<pre>Accept-HTSession = "Accept-HTSession" ":" handle</pre>
|
||
|
|
<p>When the server receives this header, the CGI job servicing the request
|
||
|
|
will be reserved in a persistent state. Only requests coming in with that
|
||
|
|
session handle in the URL are routed back to that instance of the CGI program.
|
||
|
|
The URL must be in the following format:</p>
|
||
|
|
<pre>/path/cgi-name/handle/rest/of/path</pre>
|
||
|
|
<p>Where <var class="varname">handle</var> is an exact match of the handle provided
|
||
|
|
in the ″Accept-HTSession″ CGI header for the program <samp class="codeph">cgi-name</samp>.</p>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> The <samp class="codeph">cgi-name</samp> that is being resolved is the name as
|
||
|
|
it appears in the URL. It is not necessarily the actual name of the program
|
||
|
|
being started on the system. This is to remain consistent with the name resolution
|
||
|
|
performed by the server.</div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="nested1" xml:lang="en-us" id="httimeoutcgiheader"><a name="httimeoutcgiheader"><!-- --></a><h2 class="topictitle2">HTTimeout CGI Header</h2>
|
||
|
|
<div><p>The <dfn class="term">HTTimeout</dfn> header is for the CGI program to define the
|
||
|
|
amount of time, in minutes, that this CGI program wants to wait for a subsequent
|
||
|
|
request. If not specified, the value specified on the PersistentCGITimeout
|
||
|
|
directive is used. If specified, it takes precedence over the PersistentCGITimeout
|
||
|
|
directive, but the server will not wait longer than the time specified on
|
||
|
|
the MaxPersistentCGITimeout directive. This allows individual CGI programs
|
||
|
|
to give users more time to respond to lengthy forms or explanations. However,
|
||
|
|
it still gives the server ultimate control over the maximum time to wait.</p>
|
||
|
|
<pre>HTTimeout = "HTTimeout" ":" minutes</pre>
|
||
|
|
<p>The <var class="varname">time-out</var> value is a non-negative decimal integer,
|
||
|
|
representing the time in minutes. This header must be preceded by an ″Accept-HTSession″
|
||
|
|
header, if not, it is ignored. If you omit the header, the default <var class="varname">time-out</var> value
|
||
|
|
for the server is used. When a CGI program is ended because of a time-out,
|
||
|
|
a message is logged in the error log of the server.</p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="nested1" xml:lang="en-us" id="considerationsforusingpersistentcgiprograms"><a name="considerationsforusingpersistentcgiprograms"><!-- --></a><h2 class="topictitle2">Considerations for using Persistent CGI Programs</h2>
|
||
|
|
<div><p>You should be aware of the following considerations when using persistent
|
||
|
|
CGI programs:</p>
|
||
|
|
<ul><li>The web administrator can limit the number of persistent CGI programs
|
||
|
|
that the server supports by using the MaxPersistentCGI configuration directive.</li>
|
||
|
|
<li>There are some job or thread-level resources that the server code running
|
||
|
|
in the CGI job usually manipulates (directly or indirectly) on behalf of CGI
|
||
|
|
programs. The following attributes will (potentially) change across calls:<ul><li>Environment variables the server sets</li>
|
||
|
|
<li>Stdin/Stdout/Stderr file descriptors</li>
|
||
|
|
<li>User profile</li>
|
||
|
|
<li>Library list</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
<li>The server will not set the rest of the job attributes set by the server,
|
||
|
|
and therefore, will maintain state across calls if changed by the CGI program.
|
||
|
|
Note, however, that the CGI program must restore the initial state of these
|
||
|
|
values before ending its persistence in order to guarantee compatibility across
|
||
|
|
subsequent server requests:<ul><li>Job Language, Country, CCSID</li>
|
||
|
|
<li>Job Priority</li>
|
||
|
|
<li>Printer/Output Queue</li>
|
||
|
|
<li>Message Logging</li>
|
||
|
|
<li>Environment variables set by the CGI program</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
<li>For added security, web server administrators can protect their persistent
|
||
|
|
CGI programs using registered Internet users, thereby forcing authentication
|
||
|
|
by the user before processing each request.</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="nested1" xml:lang="en-us" id="persistentcgiprogramexample"><a name="persistentcgiprogramexample"><!-- --></a><h2 class="topictitle2">Persistent CGI Program Example</h2>
|
||
|
|
<div><p>The program example located under <strong>Developer Resources</strong>, <a href="http://www.ibm.com/eserver/iseries/http" target="_blank">http://www.ibm.com/eserver/iseries/http</a> ,
|
||
|
|
displays a counter that is increased each time the Persistent CGI program
|
||
|
|
is called.</p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|