Converter programs are primarily for use with application
programs that were not originally coded for use with the Web. They
can also be used to combine output from several application programs
into a single HTTP message.
Attention: This topic contains Product-sensitive Programming Interface
and Associated Guidance Information.
Converter
programs are not used when CICS® is an HTTP client, or for
Web service processing; they can only be invoked when CICS is
an HTTP server. The role of converter programs in the CICS Web
support process for CICS as an HTTP server is described
in HTTP request and response processing for CICS as an HTTP server. Planning your CICS Web support architecture for CICS as an HTTP server has information to help you plan
your architecture for CICS as an HTTP server.
A
URIMAP definition can invoke a converter program to carry out relevant
processing for HTTP requests. If an analyzer program is used in CICS Web
Support processing, the analyzer program can also invoke a converter
program. A converter program can be useful in the following circumstances:
- When application programs that were not originally coded for use
with the Web need to receive input in the form of a COMMAREA, or need
their output to be converted into an HTTP response. Web-aware application
programs, which are coded using the EXEC CICS WEB
and EXEC CICS DOCUMENT application programming
interfaces, should not require this conversion to take place. You
can use a converter program to perform this conversion or other processing
on the content of the request.
- When you want to make more than one application program work on
the same request data in sequence, and return a single HTTP response
to the Web client.
If a converter program is invoked directly from a URIMAP
definition, the PROGRAM attribute of the URIMAP definition (which
specifies the name of the application program to process the request)
can be passed to the converter program, and the converter program
can choose to override it.
A converter program is not able to
specify code page conversion settings for a request that it receives
from an analyzer program (through a pointer in the COMMAREA indicating
a 32K block of storage that contains the request). If a converter
program is invoked directly from a URIMAP definition, and the headers
for the Web client's request indicate that the message body is text, CICS converts
the message body supplied in the block of storage using the following
standard settings:
- For the character set, if the Web client's request has a Content-Type
header naming a character set supported by CICS,
that character set is used. If the Web client's request has no Content-Type
header or the named character set is unsupported, the ISO-8859-1 character
set is used.
- For the host code page, CICS uses the default code page
for the local CICS region, as specified in the LOCALCCSID
system initialization parameter.
If these standard settings are not suitable, or if code page
conversion is
not wanted, an analyzer program must be used
in the processing path to specify alternative settings.
For
the response sent to the Web client, CICS mirrors
the code page conversion that was carried out for the request. The
character set and host code page settings from the analyzer program,
or the default settings in the absence of an analyzer program, are
used. If the analyzer program suppressed code page conversion for
the request, no code page conversion is carried out for the response
body.
A converter program is not associated with a TCPIPSERVICE
definition in the same way as an analyzer program. You can use any
converter program that is local to the CICS system,
to process any HTTP request. For a given request, the same converter
program is called for both the decode and encode functions.
The
converter program has two functions:
- Decode
- The HTTP request is passed
to the decode function of the converter program in a 32K block of
storage, which is indicated by the user_data pointer
in the COMMAREA. It has already been divided into separate elements,
such as the method, request headers and body. (Note that if the request
is too long to fit into the block of storage, the remainder of the
data is not passed to the converter program.) The name of the application
program that should handle the request is also supplied, either taken
from the URIMAP definition for the request, or set by the analyzer
program. If an analyzer program is used, it can provide additional
information in a user token. Using this information, the decode function:
- Determines whether processing should continue for the request,
or whether CICS should return an error response to the
Web client.
- Specifies the name of the user-written application program that
is to process the request and provide the response. If the name has
already been input from a URIMAP definition or by an analyzer program,
the converter program can accept or change this.
- Constructs the COMMAREA that is passed to the user-written application
program. The COMMAREA includes data from the Web client's request
which has been converted into an acceptable input format for the application
program. The storage containing the HTTP request can be reused, or
a new COMMAREA can be specified.
If a converter program
does not use the decode function to create a COMMAREA for the
application program, the 32 767 byte buffer used to receive the HTTP
request is passed to the application program.
- Encode
- Using the COMMAREA returned
by the user-written application program, the encode function:
- If more than one application program is to supply data, sets the
loop response, to call the decode function again. The decode function
changes the name of the application program and supplies appropriate
input in a COMMAREA. The output is returned to the encode function
again.
- Constructs an HTTP response in a COMMAREA, which is to be sent
to the Web client.
Converter programs are used by CICS Web
support and by the CICS business logic interface.
The role of the converter program in the CICS business
logic interface is described in
Using the CICS business logic interface to call a program.
The caller of the CICS business logic interface determines
whether a converter is required, and which converter program should
be called. For a given request, the same converter program is called
for both the decode and encode functions.
For more information
about writing user-replaceable programs, see the CICS Customization
Guide.
All
the user-replaceable programs must be local to the system in which CICS Web
support is operating. If you do not use autoinstall for programs,
you must define and install program definitions for all user-replaceable
programs used by CICS Web support, including the analyzer and
converter programs. If you use autoinstall for programs, you must
ensure that user-replaceable programs are installed with the correct
attributes.
For detailed information about the converter, see Reference information for converter programs.