The state maintenance routines enable you to create an Internet
application which can store user and application state information on the
web server:
For more details on using the state maintenance routines, see the
section Maintaining
Application State in the chapter Server-side Programming.
One of the following status codes might be returned by the state
maintenance routines:
| 0 |
Call is successful |
| 1 |
Call failed |
| 2 |
Duplicate client-id has been found (allocate) |
| 3 |
Possible causes:
Client-id not found (save and restore).
Trying to save/restore/delete a record with no matching key.
Another internal error happened (due to incorrect CALL order).
Record allocation problem. |
MF_CLIENT_STATE_ALLOCATE
Allocates a client identifier.
call "MF_CLIENT_STATE_ALLOCATE" using client-id
client-length
server-status
Parameters:
| client-id |
pic x(30). |
| client-length |
pic x(4) comp-x. |
| server-status |
pic x comp-x. |
On Entry:
| client-id |
The client identifier. See Comments below. |
| client-length |
The length of the empty record for the state
information. |
On Exit:
Comments:
This routine:
- Allocates a new empty record for the state information, with the
length given in client-length.
- Returns a new client-id, and allocates an empty record, if
the value passed in client-id is set to spaces. Otherwise, if
client-id is set to a valid client identifier, this routine
allocates an empty record with that client identifier.
Example:
working-storage section.
...
01 client-id pic x(30).
01 client-length pic xxxx comp-x.
01 state-status pic x comp-x.
...
procedure division.
...
call "MF_CLIENT_STATE_ALLOCATE"
using client-id client-length state-status
...
MF_CLIENT_STATE_DELETE
Deletes an
existing client identifier and its associated client information.
Call "MF_CLIENT_STATE_DELETE " using client-id
server-status
Parameters:
| client-id |
pic x(30). |
| server-status |
pic x comp-x. |
On Entry:
| client-id |
The client identifier. |
On Exit:
MF_CLIENT_STATE_EXPIRY
Returns a date string for use in the cookie expiry field.
Call "MF_CLIENT_STATE_FILE" using date-criteria
expiry-string
Parameters:
| date-criteria |
pic x(4) comp-x. |
| expiry-string |
pic x(50). |
On Entry:
| date-criteria |
The number of days after which client records are to
expire. |
On Exit:
| expiry-string |
The expiry date to be used in the cookie expiry field. |
Comments:
expiry-string returns a value with the format day, dd-month-yyyy
hh:mm:ss GMT
MF_CLIENT_STATE_FILE
Specifies the file to be used on the server to store state information.
Call "MF_CLIENT_STATE_FILE" using filename
server-status
Parameters:
| filename |
pic x(255). |
| server-status |
pic x comp-x. |
On Entry:
On Exit:
Example:
working-storage section.
...
01 state-status pic x comp-x.
01 state-filename pic x(255)
value "MF-STATE-SAVE.DAT".
...
procedure division.
...
call "MF_CLIENT_STATE_FILE" using state-filename
server-status
...
MF_CLIENT_STATE_PURGE
Deletes all client information older than the number of days specified.
Call "MF_CLIENT_STATE_PURGE" using date-criteria
server-status
Parameters:
| date-criteria |
pic x(4) comp-x. |
| server-status |
pic x comp-x. |
On Entry:
| date-criteria |
The number of days after which which client information should be
purged. |
On Exit:
MF_CLIENT_STATE_RESTORE
Restores a previously saved or allocated record which matches the client
identifier.
Call "MF_CLIENT_STATE_RESTORE " using client-id
client-state
client-length
server-status
Parameters:
| client-id |
pic x(30). |
| client-state |
pic x(4) comp-x. |
| client-length |
See Comments. |
| server-status |
pic x comp-x. |
On Entry:
| client-id |
The client identifier. |
| client-state |
The state information to be saved. See Comments. |
| client-length |
The length of the empty record for the state
information. |
On Exit:
Comments:
On entry, client-length is the length of the buffer. On exit,
client-length returns the length of the data recovered. The data
is truncated to fit the client-length specified on entry.
You can define any format for client-state records. Define the
length of the client-state record in the client-length
field.
Example:
working-storage section.
...
01 client-id pic x(30).
01 client-length pic xxxx comp-x.
01 state-status pic x comp-x.
01 client-state.
03 user-preferences pic x(10).
03 user-selection-list pic x(80).
...
procedure division.
...
call "MF_CLIENT_STATE_RESTORE"
using client-id client-state
client-length state-status
...
MF_CLIENT_STATE_SAVE
Updates the information in the state file.
Call "MF_CLIENT_STATE_SAVE" using client-id
client-state
client-length
server-status
Parameters:
| client-id |
pic x(30). |
| client-state |
pic x(4) comp-x. |
| client-length |
See Comments. |
| server-status |
pic x comp-x. |
On Entry:
| client-id |
The client identifier. |
| client-state |
The state information to be saved. See Comments. |
| client-length |
The length of the empty record for the state
information. |
On Exit:
Comments:
This routine saves a previously allocated client-id and client
state, or rewrites a previously saved client-id and client
state. Client-length can be updated.
You can define any format for client-state records. Define the
length of the client-state record in the client-length
field.
Example:
working-storage section.
...
01 client-id pic x(30).
01 client-length pic x(4) comp-x.
01 state-status pic x comp-x.
01 client-state.
03 user-preferences pic x(10).
03 user-selection-list pic x(80).
...
procedure division.
...
call "MF_CLIENT_STATE_SAVE"
using client-id client-state
client-length state-status
...
Copyright © 2002 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.