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.