This document describes the customizing and use of the HTTP Server.

This document covers the following topics:

• Initializing the HTTP Server

• Termination

• Configuration

• HTTP Server Parameters

• Content Processing

• Accessing HFS/zFS Files

• Using a Cache

• Pooled Server Processing

• Conversational Processing

---

Initializing the HTTP Server

The HTTP server is normally initialized by specifying a SERVER statement:

SERVER=(HTTP,HAENSERV,CONF=<config>)

where

HTTP	is the name of the SERVER. The name of the server may be any name valid for the SERVER statement.
HAENSERV	is the name of the HTTP server module. The HTTP server module must always be specified as HAENSERV.
<config>	is the location, in /path/member notation, of the HTTP server configuration to be used..

z/OS

Software AG strongly recommends to specify the following sysparm:

APPLYMOD=78

z/VSE

The following sysparm must be specified:

RESIDENTPAGE=(TLSPLISN,$SOCKLST)

and for SSL, additionally

RESIDENTPAGE=IPCRYPTO

The modules $SOCKLST and IPCRYPTO are located in library PRD1.BASE.

If inactive for any reason, the HTTP server may also be started using the operator command

SERV,INIT,HTTP,HAENSERV,CONF=<config>

where the meaning of the parameters is the same as previously outlined for the SERVER statement.

Notes:

1. It is possible to have more than one HTTP server active within the same Com-plete address space at the same time. Each server requires a different server name and a different configuration to ensure that it does not attempt to use the same port as one of the other servers.
2. The POSIX environment must be active before a HTTP server can be activated; otherwise, the HTTP server initialization fails. This can be achieved by placing any of the HTTP server SERVER statements after the POSIX SERVER statement in the Com-plete sysparms. When the servers are started using operator commands, the POSIX Server environment must be started first.

Termination

The HTTP server is terminated automatically when the Com-plete address space is terminated. However, it is also possible to cycle the server without bringing the address space down by issuing the operator commands

SERV,TERM,HTTP

where HTTP is the name given to the server at startup.

Configuration

The HTTP server is configured by a text file containing the HTTP server parameters as described below.

Sample HAANCONF Member

The HTPvrs.SRCE library contains a sample HAANCONF member. This may be copied and/or modified to produce a number of different configuration options, if required. A configuration option can then be selected by an operator when the HTTP server is started.

HTTP Server Parameters

The following parameters may be specified in the configuration file:

3270_FILLER_CHAR

Parameter	Use	Possible Values	Default
3270_FILLER_CHAR	Filler character to be removed from the end of all input fields upon output by the 3270 bridge.	1-byte string constant	none

Use this parameter to tell the 3270 bridge that your applications are using a filler character, so it can remove these characters when the 3270 output data stream is converted to XML.

Background: Some 3270 applications pad all input fields from end-of-text to end-of-field with a so-called filler character; usually characters like underscore ‘_’ or period ‘.’ are used for this. This dates back to a time when on 3270 terminals protected and unprotected fields could not be distinguished by background color, so that the purpose of the filler character was to visualize the size of the input field. Filler characters are widely used, e.g., in Natural applications.

With respect to unprotected fields, 3270 terminals and emulations by default run in replace mode (as opposed to insert mode), and the filler characters are just overwritten when the user starts typing. Modern software like web browsers use insert mode by default, and there is no way from HTML to force replace mode, so the filler characters become an annoyance with the 3270 bridge.

Example

3270_FILLER_CHAR='.'

CACHE

Parameter	Use	Possible Values	Default
CACHE	Allocate a server-side cache for files used in HTTP requests.	YES | NO | n[K|M]	NO

Value	Description
NO	Only the HTTP server’s native files and those from an optional HOMEDIR are to be cached.
YES	All PDS(E) or VSE sublib members are to be cached.
size	Limit on the maximum size of the cache buffer pool, in Kilobytes or Megabytes (implies YES).

For more detailed information, refer to Using a Cache.

CGIPARM

Parameter	Use	Possible Values	Default
CGIPARM	A parameter string to be passed to every CGI program that is started.	1-256 byte parameter string	none

The string is passed in standard z/OS format where register 1 points to a pointer that points to a half word length followed by the data.

CGIPARM is used to pass parameters or set runtime options for language environment-enabled programs.

CONTBUFL

Parameter	Use	Possible Values	Default
CONTBUFL	The size of a buffer allocated by the HTTP request processing program to hold information about the variables contained in a HTTP request, when the request is parsed by the HTTP server. 16 bytes per variable are required, so the default size of 1024 is sufficient for up to 64 variables. If the number of variables exceeds the value set in this parameter divided by 16, the request is rejected.	1-65545	1024

DEFACEE

Parameter	Use	Possible Values	Default
DEFACEE	Indicates whether the server will build a default ACEE for the user specified in HTTPUSER during initialization and startup.	NO | YES	NO

Value	Description
YES	A default ACEE is built and associated with any user that does not log on to the system.
NO	Any user that does not log on to the system has the authority associated with the address space.

DFLTCONT

Parameter	Use	Possible Values	Default
DFLTCONT	The default content type to be assigned to a URL if the content type cannot be determined through the dataset name or member type processing mechanism.	HTTP content type header	APPLICATION/ OCTET-STREAM

The web browser uses the content type header to determine what to do with data. For example, for content type TEXT/HTML , the browser interprets the data as an HTML page. For content type IMAGE/GIF , the browser attempts to interpret the data as a GIF file.

The default value causes the web browser to download as binary data any URLs for which the content cannot be explicitly determined; that is, such URLs are downloaded as is without any translation.

DFLTURL

Parameter	Use	Possible Values	Default
DFLTURL	The path[?query] part of an URL to be used when none is present in the HTTP request.	partial URL string, max. 100 characters	index.html

If the string contains any special characters other than "/" and "." it must be enclosed in apostrophes or double quotes.

DFLTURL="cgi/haen3270?command=some3270+parms"

EBCDIC_CODEPAGE

Parameter	Use	Possible Values	Default
EBCDIC_CODEPAGE	The codepage number used to encode text data on the machine where the HTTP server runs.	37 United States 420 Arabic 500 International 870 Latin 2 1025 Cyrillic 1047 Open Systems 1141 Germany, Austria 1142 Denmark, Norway 1145 Spain 1147 France 1148 Belgium, Switzerland	500

This parameter determines what input (ASCII -> EBCDIC) and output (EBCDIC -> ASCII) translation tables are used by the HTTP server.

Translation does not apply to the HTTP server’s native text files, as these are ASCII encoded.

Most EBCDIC codepages currently supported are translated to and from Latin 1 (ISO-8859-1), with the following exceptions:

• 420 (Arabic) - UTF-8

• 870 (Latin 2) - Windows-1250 or ISO-8859-2 depending on client

• 1025 (Cyrillc) - Windows-1251

The encoding is indicated to the HTTP client using the charset= property in the content-type HTTP header. If your machine uses an EBCDIC codepage that is not on the list, please, contact Software AG to have it added.

If in doubt what codepage is used on your machine, look at member CODEPAGE.txt at the link Native HTML pages from the INDEX page, and proceed as described there.

HOMEDIR

Parameter	Use	Possible Values	Default
HOMEDIR	Specifies the dataset name of the HTTP server’s home directory.	The name, in path notation, of a PDS or PDSE text library. VSE: /lib/sublib/	none

In contrast to former versions, specification of a home directory is optional. All the native files required by the HTTP server itself are contained in the HTTP server’s load library. The purpose of the home directory is only to hold files specific for your installation, like, e.g., your favicon.ico, welcome.html, or customized versions of some HTTP server files, for example if you prefer to remove certain functions from the menu in index.html. If specified, the home directory is logically concatenated before the HTTP server’s internal directory.

z/OS:

The home directory must be a PDS or PDSE, recommended data set attributes are VB/4096/4092. FB might work, but cannot be guaranteed. The HTTP server’s internal directory can be accessed at the link Native HTML pages from the Com-plete main menu. If you want to obtain the source of a file for customization, use the provided Download links rather than the links with the file names for HTML files, as this is the only way to avoid resolution of Server Side Includes contained in some of the HTML files.

z/VSE:

Do not use the HOMEDIR parameter. The HTTP server’s internal directory is the HTPvrs sublibrary. If you want to obtain the source of a HTML file for customization, use the edit link and then cut-and-paste the contents from the text area. To replace a member, simply override it with your version in the HTP sublibrary itself or put your version into a sublibrary concatenated in front of it in the LIBDEF SEARCH,PHASE… concatenation.

Text files in the home directory can be either in ASCII encoding (no characters x80-xFF), or in ECBDIC, matching the codepage specified in parameter EBCDIC_CODEPAGE.

To reference a file in the home directory or in the HTTP server’s internal directory in a URL, specify the file name without any path, e.g., http://my.server/index.html.

HTTPUSER

Parameter	Use	Possible Values	Default
HTTPUSER	The user ID with which each HTTP request is identified if the HTTP request does not contain an authorization header.	1-8 character user ID	HTTPUSER

This is effectively the default user ID assigned initially to all requests.

HTTPLIST

Parameter	Use	Possible Values	Default
HTTPLIST	The user ID assigned to the HTTP task that listens for requests.	1-8 character user ID	HTTPLIST

HTTPHCD

Parameter	Use	Possible Values	Default
HTTPHCD	The hardcopy device name associated with any HTTP users.	1-8 character name	HTTPHCD

This output device name is used when the program attempts to write output to a SYSOUT/SYSLST type device. For example, when LE/370 is active and an abend occurs, LE/370 writes a dump to this hardcopy device name.

Output written to this device may be viewed and/or deleted using USPOOL or printed.

LOGON

Parameter	Use	Possible Values	Default
LOGON	Determines the level of security that the HTTP server will enforce.	ALLOWED | DISALLOWED | REQUIRED	ALLOWED

The parameter must be used in association with the Com-plete SECSYS configuration parameter.

Refer to section Security for more information about this parameter.

LOGON_DOMAIN

Parameter	Use	Default
LOGON_DOMAIN	Specifies the domain for which a user sign-in is valid. This can be used to organize single-point sign-in to multiple Com-plete HTTP servers running on the same machine or on different machines. To allow single-point sign-in to multiple Com-plete HTTP servers running on the same machine, specify LOGON_DOMAIN=HOST. To allow single-point sign-in to multiple Com-plete HTTP servers running on different machines in the same domain, specify the domain. The domain must be specified as per RFC 2965 - HTTP State Management Mechanism, i.e. in the form LOGON_DOMAIN=.mycompany.com.	None. By default, each Com-plete requires a separate sign-in. Note that multiple HTTP servers running in the same Com-plete always share a single security environment.

LOGON_MESSAGE

Parameter	Use	Possible Values	Default
LOGON_MESSAGE	Defines what method (HTML or basic) the HTTP server should use for requesting user authentication from the client. Any value other than "HTML" indicates basic authentication, and the value is treated as a message text given to the client for displaying it in the userID/password pop-up. In this case the server sends a HTTP response 401, a HTTP header WWW-Authenticate: Basic realm="message text", and the customizable page HHAN401.html . For "HTML", the server sends out the HTML form HHANLGON.html.	HTML | message text	HTML

Example:

LOGON_MESSAGE='Welcome to the Com-plete web server!'

Notes:

1. With basic authentication, browsers remember the userID and password until the browser is closed. Even if the user terminates a session by clicking a "Log out" button, he will be logged in again automatically when he sends another request to the same server without closing the browser.
2. Basic authentication offers no possibility to provide the user with informational messages that might accompany a successful log-in, like for example “your password will expire in N days”.

MAXCONNECTIONS

Parameter	Use	Possible Values	Default
MAXCONNECTIONS	The maximum number of parallel connections you want to allow this server to accept.	1-32767	No limit

MAXCONTENTLENGTH

Parameter	Use	Possible Values	Default
MAXCONTENTLENGTH	The maximum content length allowed for a HTTP request. Use this parameter for limiting the amount of data in a single transfer (upload). This limit does not apply to file uploads using the built-in upload program HAANUPLO, as these are written to the file directly.	0 - 1024M (number optionally followed by K or M)	1M (= 1MByte)

MAXPARALLEL

Parameter	Use	Possible Values	Default
MAXPARALLEL	Limit on the maximum number of simultaneous connections per client.	Integer	9

MSGCASE

Parameter	Use	Possible Values	Default
MSGCASE	The case in which messages are to be issued.	MIXED | UPPER	MIXED

NATLIB

Parameter	Use	Possible Values	Default
NATLIB	Name of the default library where Natural CGI requests to the HTTP server are directed.	1-8 character name	NATCGI

If no library is provided on the CGI request, the program specified on the Natural CGI request to this server must be cataloged in this library.

NATLOGON

Parameter	Use	Possible Values	Default
NATLOGON	For requests like /natcgi/lib/pgm the server starts Natural with the parameter STACK(LOGON lib;HNANSHEL). Specify NATLOGON=NO if you wish to avoid LOGON lib.	NO | YES	YES

NATPARM

Parameter	Use	Possible Values	Default
NATPARM	Parameter string to be provided as override parameters to Natural for all Natural CGI requests.	1-256 byte parameter string	none

For more information see Relationship to the HTTP Server Configuration in Installing Natural CGI.

The 'STACK ' override parameter is ignored if specified in this string.

It is also possible to supply Natural parameters dynamically in the CGI query string. If the keyword “natparm” is detected in the CGI query string, its value is appended to the value of the NATPARM parameter dynamically, and the resulting string is passed to Natural.

NATTHRD

Parameter	Use	Possible Values	Default
NATTHRD	The name of the Natural front-end driver module used to start Natural in Com-plete.	1-8 character name	NATCOM

See Installing Natural CGI.

PORT

Parameter	Use	Possible Values	Default
PORT	The sockets port on which the HTTP server server should listen for incoming HTTP requests.	1-32000	80

RECVBUFL

Parameter	Use	Possible Values	Default
RECVBUFL	The length of the buffer used for receiving input data from the network.	1-65545	4096

When conversations are being supported, this buffer must be set to the highest incoming data size expected for one incoming conversational HTTP request; otherwise, data may be lost.

When conversations are not being supported, this buffer is reused to read the entire incoming data stream.

Changing this size affects the amount of local storage the request processing program needs to run.

SEND

Parameter	Use	Possible Values	Default
SEND	Determines how HTTP sends data in response to a request.	IMMEDIATE | BUFFERED	IMMEDIATE

Value	Description
IMMEDIATE	Sends data as soon as it is available. This option may be useful where requests are failing: the web user receives whatever data has been created to the point of the failure. Should be used only temporarily in a test environment, as it is extremely slow.
BUFFERED	Buffers all data in the buffer created by the SENDBUFL parameter. If failures occur, the end user may see no response data at all as the data is being buffered; however, this is less resource and network intensive. Because the BUFFERED setting greatly increases the performance of the server, Software AG recommends that use it in a production environment.

SENDBUFL

Parameter	Use	Possible Values	Default
SENDBUFL	The length of the buffer used for sending output data to the network.	1-65545	4096

Changing this size affects the amount of local storage the request processing program needs in order to run.

SERVNAME

Parameter	Use	Possible Values	Default
SERVNAME	Name to identify the system.	1-8 character name	none

This name is included in all messages (except some start-up and termination messages) issued to the operator during the execution of the HTTP server.

The name must be unique within a machine.

SERVPOOL

Parameter	Use	Possible Values	Default
SERVPOOL	Indicates how many previously started HTTP server instances should be kept in a pool for reuse. If you specify 0, then server instances are not pooled, and a new server instance is started for each HTTP request and terminated after the request is completed.	0-32767 YES | NO	10

Value	Description
YES	YES is supported for compatibility with previous versions and treated as 10.
NO	NO is supported for compatibility with previous versions and treated as 0.

SSL

Parameter	Use	Possible Values	Default
SSL	Specifies whether this is a HTTP or HTTPS server. If you need servers for both protocols, you can set up two or more seperate servers in the same address space using different port numbers. Using SSL requires specification of a key database or SAF key ring using the Com-plete SSL-KEYRING-* sysparms, and the IBM GSK load library SYS1.SIEALNKE must be present in either the system LINKLIST or Com-plete's COMPLIB chain.	YES | NO |CERT	NO

Value	Description
CERT	Implies YES. Specify CERT if you need the HTTPS server to require a client certificate from each client.

TRACE

Parameter	Use	Possible Values	Default
TRACE	Turns on tracing to the DD statement identified by the TRACEDD keyword.	REQUEST | HEADER | DATA	none

HEADER and DATA can be combined by specifying TRACE=(HEADER,DATA). REQUEST cannot be combined with any other options, but what is traced by REQUEST is also included in HEADER.

Value	Description
REQUEST	Writes one line per HTTP request, indicating: timestamp in store-clock format, client IP address, sequence number of the request within a persistent connection, request URI (truncated when too long).
HEADER	Dumps all HTTP headers and their associated data to the DD once they have all been read and processed.
DATA	Traces all HTTP input data as it is read and all data being sent in response to the request prior to it being sent. The data is printed in both character and hex formats. The hex represents what is actually sent in ASCII. The character output is translated to EBCDIC so that it can be read.

TRACEDD

Parameter	Use	Possible Values	Default
TRACEDD	Name of the DD to which all HTTP trace data is written.	1-8 character name	HTPTRCE

If the DD/DLBL name is not specified in the Com-plete start-up procedure, it is automatically allocated as a SYSOUT/SYSLST dataset.

z/VSE:

If you want to write the data to a sequential dataset, you must allocate it (e.g. using OBMAINT) before you start the HTTP server.

TRANSLATE_CONTENT

Parameter	Use
TRANSLATE_CONTENT	Specifies a list of content types to be treated as EBCDIC at output from the HTTP server, translating them to ASCII. Wildcards are not currently supported.

Example:

TRANSLATE_CONTENT=(application/msword,
                                       application/vnd.ms-excel,
                                       application/pdf)

UPLOAD

Parameter	Use	Possible Values	Default
UPLOAD	In order to avoid vulnerability when the administrator of a server is not aware of the presence of the upload functionality, this functionality is disabled by default. To activate it, set config parameter UPLOAD=YES. The scope of this parameter is the HTTP methods PUT and DELETE, and the CGI program haanuplo. Using the POST method with form elements "input type=file" to invoke other CGI programs is not affected by this parameter.	YES | NO	NO

URLPBUFL

Parameter	Use	Possible Values	Default
URLPBUFL	Length of the buffer used for holding parameters passed on any given URL request (that is, any data following ? in the URL).	1-65545	1024

Depending on the nature of the requests in use, the length could be increased or decreased; however, if there is insufficient space in this buffer, the request is rejected.

Changing this size affects the amount of local storage the request processing program needs in order to run.

Content Processing

One of the most important pieces of information that the HTTP server provides to the web browser in response to a HTTP request is the 'content type'. This is the HTTP header that the browser uses to interpret the data sent in response to the request. The HTTP server has a number of ways to determine what the content type is.

Member Type Processing

When a member type is specified on a URL request, even though the mainframe operating system has no concept of types as such, the HTTP server uses this type to look up a user configuration table HAANTYPT to determine whether it can identify the content type of the URL.

The source for the table HAANTYPT is delivered in HTPvrs.SRCE and copied during installation to the HTPvrs.USER.SRCE datasets for modification by the user. The table is built using the HMANTYPT macro which has two parameters:

TYPE	1-8 character member type.
CONTENT	The content type to be returned to the browser when a member of this type is requested on a URL. The HTTP server does not validate content types: any type may be specified and new types are constantly being created. The sample HAANTYPT member contains examples of commonly used content types.

Once modified, the HAANTYPT table must be reassembled into a load library in the Com-plete COMPLIB concatenation.

Software AG recommends that you use the HTPvrs.USER.LOAD dataset for this. Member HJBNTYPT in the HTPvrs.SRCE dataset contains sample JCL to assemble and link the HAANTYPT table.

If a match cannot be found for the type specified on the URL, or no type is specified on the URL, the HTTP server attempts to determine the content type from the last level of the URL provided.

Dataset Name Processing

The HTTP server breaks down the URL provided by the user into

• a dataset name component; and

• optionally a member and member type component

  /this/is/a/pds/member.type is THIS.IS.A.PDS(MEMBER)
  

  or

  /this/is/a/seq/file/ is THIS.IS.A.SEQFILE
  

On z/OS systems, the HTTP server assumes that the last level of the resulting dataset name indicates the sort of data contained in a given dataset. In the above examples, 'PDS ' and 'FILE ' are the last levels.

Once the last level is determined, the HTTP server checks a second user-configurable table HAANDSNT to determine if the last level can be used to map the URL to a content type. The HAANDSNT member is provided on the HTPvrs.SRCE dataset and copied by the installation to the HTPvrs.USER.SRCE for modification. HAANDSNT is built using the HMANDSNT macro which has the following parameters:

LASTDSNL	The last level of the dataset name resulting from the interpretation of the URL.
CONTENT	The content type to be returned to the browser when a member from this dataset (or the dataset itself, if sequential) is requested on a URL. The HTTP server does not validate these content types: any type may be specified and new types are being created daily. The sample HAANDSNT member contains examples of commonly used content types.

Once modified, the HAANDSNT table must be reassembled into a load library in the Com-plete COMPLIB concatenation.

Software AG recommends that you use the HTPvrs.USER.LOAD dataset for this. Member HJBNDSNT in the HTPvrs.USER.SRCE dataset contains sample JCL to assemble and link the HAANDSNT table.

If a match cannot be found in the HAANDSNT table, the HTTP server uses the default as specified by the DFLTCONT configuration parameter.

CGI Request Output Processing

Any CGI program, whether it is written in Natural , C , COBOL, or PL/1 , may write a CONTENT-TYPE header to the output stream to indicate the content it is going to send. If the HTTP server detects that no CONTENT-TYPE header is sent by the CGI program, it sends a CONTENT-TYPE header using the default content type for the system as specified by the DFLTCONT configuration parameter.

Accessing HFS/zFS Files

In order to access HFS/zFS files via the Com-plete HTTP server, the respective directories must be mounted logically in the Com-plete/APS sysparms. The following definitions must be made:

CDI_DRIVER=('uss,PAAMFUSS')

The name of the protocol, which is 'uss' here, can be chosen freely, and must then be used for logically mounting one or more file systems.

You can mount an entire real file system (root), e.g.:

MOUNT_FS=('uss://','/hfs/')

Here this allows you to access for example /etc/profile like http://server/hfs/etc/profile, or mount any existing (sub-) directories of any level, for example

MOUNT_FS=('uss://etc/','/etc/')

This allows you to access for example /etc/profiles such as http://server/etc/profile.

The names of the mount points, which are '/hfs/' and '/etc/' here, can be any valid path names. The presence of these MOUNT_FS parameters merely defines a mapping of path names; no access to the specified directories takes place until a mount point name is used in a real HTTP request.

Only those parts of a file system that are explicitly mounted in Com-plete can be accessed. Note that symbolic links in a mounted branch pointing to a non-mounted branch make the target branch accessible.

Normal UNIX file permissions apply (based on the userID).

Using a Cache

The server-side cache has been added to avoid the overhead of reading files used in web pages (z/OS PDS(E) members, z/VSE library contents) multiple times. The storage is allocated as a buffer pool in a dataspace with a minimum size of 1MB and will expand as needed unless you specify a limit in the CACHE parameter.

With CACHE=NO set or on default, only the files in the home directory and in the HTTP server’s internal directory are cached. Generally, sequential files are not cached, and PDS(E) members are only cached when referenced with a file name extension. This is in order to avoid caching of members when they are accessed from a directory listing, because otherwise users would be looking at stale versions when the contents of a member changes.

The following operator commands and utilities are available to administer the cache:

SERV servername,CNEW	Deletes the current cache and allocates a new empty one.
	Return Codes:
	04 Cache in use (files are currently copied to and from it). 16 Cache never allocated
SERV servername,CREFRESH	Removes unusable (incomplete) entries.

The contents of the cache can be displayed and cached files can be refreshed by using the link Server cache from the INDEX page.

Here you can also mark files as 'unusable', so that changed versions are read from disk. But keep always in mind that your browser has its own cache and might still use the original files. Each browser has options available to delete these temporary files too.

Pooled Server Processing

The HTTP server implements pooled server processing dynamically.

When a request is received, the HTTP server checks the pooled server queue to determine if any pool servers are available. For the first request, no pool server is found so the system starts a server to process the request. When the request is processed, the server puts itself on the pooled server processing queue. When the next request arrives, the pooled server is found on the queue and is used to process the request.

Advantages of Pooled Servers

• Using a pooled server rather than starting a new server saves the cost of starting and initializing a new thread of control and terminating the request processing logic. Significant resources are thus saved.

• The system creates pooled servers until a steady state is reached where a pooled server is always available to process an incoming request.

• If a pool server ABENDs for some reason, only the user being processed is affected. If insufficient pooled servers are available, the HTTP server attaches more users.

• Pooled servers are dormant while on the pooled server queue. They use no CPU. In Com-plete, pooled servers are eligible for rollout so they do not occupy a thread.

Considerations when Using Pooled Servers

A pooled server can process any type of request. For example, the first request it services may be a static HTML deliver request, the second may be a COBOL program CGI request, the third may be a Natural program CGI request.

• The amount of storage available in the pooled server's thread must be carefully considered to ensure that sufficient unfragmented storage is available to run whatever request may arrive. To that end, it may be advisable to have a separate HTTP server processing Natural requests only.

• Because a pooled server instance never really terminates, CGI programs must clean up after processing to avoid a negative impact on following requests.

Natural Considerations

When a Natural CGI request is issued and a new thread must be started, the Natural interface is started and, using an internal inverted call mechanism, Natural CGI programs are driven.

Using the inverted mechanism to call Natural means that the Natural environment is only started once per pooled server so that the next time a Natural CGI request is handled by the same pooled server, no Natural initialization/termination is required.

In this way, a significant savings is realized in both CPU and wall clock time required to process Natural CGI requests.

Conversational Processing

Instead of maintaining a generic queue of active user threads, a more specific queue is maintained for conversational processing.

A conversation is maintained by sending a session-specific cookie to the browser with the output from the CGI program. The cookie is returned with the next request that enables the HTTP server to match the incoming request with the active request on the conversational request queue.

The incoming data is piped to the program in conversation and the conversational program is dispatched again to process the request from the user with whom it is in conversation.

If a conversational program terminates due to a timeout or an ABEND, the next time the user attempts to converse with the other user in the conversation, a message is issued to indicate that the conversation no longer exists.