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.
Procedure
- 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
Reserved and excluded characters 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.