Form data is information provided by the user through interaction
with an element in a HTML form, such as a text input box, button,
or check box. The information is transmitted as a series of name and
value pairs.
CICS®
can scan an HTTP request to pick out the
form fields, so an application can obtain the data using
CICS
commands,
without needing to receive and analyze the entire body of the request.
About this task
HTML forms
explains more about forms and form
fields.
An application can receive the value of a specified
form field or it can browse through the names and values of all the
form fields contained in a request. You can specify code page conversion
options if you want to convert the data into a different code page
for use by your application.
The web client sends form data
in a query string when the GET method is used and in the message body
when the POST method is used.
CICS
can extract the data from
either of these locations, so you do not specify which method was
used. As an alternative, if the form data is sent in the query string,
you can retrieve the entire query string using the WEB EXTRACT
command.
Examining the request line for an HTTP request
tells
you how to do that.
CICS
reads form data only when
CICS
is
the HTTP server and not when it is an HTTP client.
-
To obtain the value of a particular field of an HTML form,
use the
WEB READ FORMFIELD
command.
Your application program can provide a buffer, which will receive
the value, or, alternatively, you can provide a pointer, which
CICS
sets
to the address of the value.
CICS
returns a NOTFND condition
if the form data does not contain a field with the specified name.
The form data is unescaped by
CICS
before
it is returned, with the
%xx
sequences converted
back to the original characters. See
CICS web support and non-HTTP requests
for
an explanation of this.
-
To browse all the fields in the form data:
-
Use the
WEB STARTBROWSE FORMFIELD
command
to begin browsing the fields.
-
Use the
WEB READNEXT FORMFIELD
command
to retrieve the name and value of each field in turn.
Your
application program provides two buffers: one receives the name of
the field, and the other receives its contents.
CICS
returns
an ENDFILE condition when all fields have been read.
-
Use the
WEB ENDBROWSE FORMFIELD
command
to end the browse when your program has retrieved all the fields of
interest.
-
CICS carries out code
page conversion on the data you receive.
You can use the CHARACTERSET and HOSTCODEPAGE options on the WEB STARTBROWSE FORMFIELD and
WEB READ FORMFIELD commands to specify the code page used by the web client and by your application
program.
-
The character encoding used by a client application for both the GET and POST methods is
determined by information in the HTML form. However, this information is not typically present as
part of the submitted form request, so it is supplied by the application using the CHARACTERSET
option. This information must match the forms encoding determined by the corresponding HTML form.
See How the client
encoding is determined for more information.
-
The HOSTCODEPAGE option specifies the CICS (host) code page used by the application program. This code page is
typically an EBCDIC code page. If the code page is not specified, the data is returned in the EBCDIC
code page specified by the LOCALCCSID system initialization parameter, provided that the specified
code page is supported by the CICS web interface. Otherwise, CICS returns the data to the default EBCDIC code page 037.