Two state management sample programs, DFH$WBST and DFH$WBSR, are
supplied with CICS® Web
support. They allow a transaction to save data for later retrieval by the
same transaction, or by another transaction. The saved data is accessed by
a token that is created by the state management program for the first transaction.
The first transaction must pass the token to the transaction that is to retrieve
the data. DFH$WBST uses a GETMAIN command to allocate storage for the saved
data. DFH$WBSR saves the data in temporary storage queues, one for each token,
so that, with suitable temporary storage table definitions, the data can be
accessed from several CICS systems. The rest of this section applies equally
to either program.
The state management programs provide the following
operations:
- Create a new token.
- Store information and associate it with a previously-created token.
- Retrieve information previously associated with a token.
- Destroy information associated with a token, and invalidate the token.
DFH$WBST also removes information and tokens that have expired. You can
run this program periodically to purge state data which has expired:
- To purge all state data which has not been updated for one hour, run the
program as transaction CWBT.
- To purge all state data, run the program as transaction CWBP.
The layout of the 268-byte COMMAREA is shown in the following
table. You must clear the COMMAREA to binary zeros before setting the inputs
for the function you require.
Table 1. Parameters for the state management
programOffset |
Length |
Type |
Value |
Notes |
0 |
4 |
C |
|
Eyecatcher |
4 |
1 |
C |
'C'
'R'
'S'
'D'
|
Create
Retrieve
Store
Destroy
This is the function code. It is a required input to every
call. |
5 |
1 |
X |
|
Return code. This is an output from every
call. |
6 |
2 |
X |
|
Reserved. |
8 |
4 |
F |
|
Token. This is an output from a Create call,
and an input to every other call. |
12 |
256 |
C |
|
User data. This is an input to the Create
and Store calls, and an output from a Retrieve call. It is not used in other
calls. |
The return codes are as follows:
- 0
- The requested function was performed.
- If the function was Create, a new token is available at offset 8.
- If the function was Retrieve, the entity body associated with the input
token at offset 8 is now in the entity body area at offset 12.
- If the function was Store, the input entity body at offset 12 is now associated
with the input token and offset 8. Any entity body previously associated with
the token is overwritten.
- If the function was Destroy, the data associated with the input token
at offset 8 has been discarded, and the token is no longer valid.
- 2
- The function code at offset 4 was not valid. Correct the program that
sets up the COMMAREA.
- 3
- The function was Create, but a GETMAIN command gave an error response.
- 4
- The function was Retrieve, Store, or Destroy, but the input token at offset
8 was not found. Either the input token is not a token returned by Create,
or it has expired.
- 5
- A WRITEQ TS command gave an error response when writing internal data
to a temporary storage queue.
- 7
- An ASKTIME command gave an error response.
- 8
- A READQ TS command gave an error response when reading internal data from
a temporary storage queue.
- 9
- An ASKTIME command gave an error response during time-out processing.
- 11
- The function was Create, but a WRITEQ TS command gave an error response.
This return code is produced only by DFH$WBSR.
- 12
- The function was Retrieve, but a READQ TS command gave an error response.
This return code is produced only by DFH$WBSR.
- 13
- The function was Store, but a WRITEQ TS command gave an error response.
This return code is produced only by DFH$WBSR.
- 14
- The function was Destroy, but a DELETEQ TS command gave an error response.
This return code is produced only by DFH$WBSR.