Parameter lists

File control provides the following functions in OCO modules:

FCCA CHECK function

CHECK is issued to get the results of a previous, asynchronous, operation.

Input parameters

CHECK_TOKEN
is a token that was returned on the previous request for which the results are being checked.

Output parameters

ACCMETH_RETURN_CODE
is a two-byte code returned by SMSVSAM.
CONFLICTING_QUIESCE
indicates the type of quiesce which conflicts with this request, and can have any of these values:
QUIESCE|UNQUIESCE|NONBWO_END|BWO_END|NONBWO_START|
BWO_START
RESPONSE
is DFHFCCA’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
VSAM_REQUEST_ERROR
RLS_FAILURE
DISASTER ABEND

FCCA COLD_START_RLS function

This request is issued as part of CICS® cold start processing. CICS issues an IDARECOV TYPE=COLDSTART call to SMSVSAM to release all RLS locks owned by this CICS, and to clear the lost locks status and 'non RLS update permitted' state of all data sets with respect to this CICS.

Input parameters

SUBSYSNM
is a pointer to an IFGSYSNM structure.

Output parameters

ACCMETH_RETURN_CODE
is a two-byte code returned by SMSVSAM.
RESPONSE
is DFHFCCA’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
VSAM_REQUEST_ERROR
RLS_FAILURE
DISASTER ABEND

FCCA DRAIN_CONTROL_ACB function

The Control ACB must be drained when file control detects that an instance of the SMSVSAM server has become failed. DFHFCCA will set an indicator in FC static storage so that no other RLS activity may proceed, and then drain all existing RLS access. This involves incrementing the server sequence number in FC static storage, closing all RLS ACBs and unregistering the Control ACB.

Input parameters

None

Output parameters

RESPONSE
is DFHFCCA’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
DISASTER_PERCOLATION
ABEND

FCCA INQUIRE_RECOVERY function

This request is issued as part of CICS start up processing. CICS makes an IDAINQRC request to VSAM to obtain the information necessary to determine what RLS recovery actions are required by CICS.

Input parameters

AREA_PTR
is the address of an area in which the IFGINQRC information is to be returned.
AREA_LENGTH
is the length of the supplied area.

Output parameters

ACCMETH_RETURN_CODE
is a two-byte code returned by SMSVSAM.
REQUIRED_LENGTH
is the length of the IFGINQRC area to be returned, if it exceeds the length of the supplied area.
RESPONSE
is DFHFCCA’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
AREA_TOO_SMALL
VSAM_REQUEST_ERROR
RLS_FAILURE
DISASTER ABEND

FCCA LOST_LOCKS_COMPLETE function

CICS issues an IDARECOV TYPE=LL request to SMSVSAM when it has completed recovery processing for a data set that is in lost locks status. SMSVSAM resets the state of the data set in the sharing control data set to indicate that the data set is no longer lost locks with respect to this CICS.

Input parameters

DATASET
is the 44-character name of the base data set for which CICS has completed lost locks recovery.
[RESTART]
is an optional parameter which indicates whether the call was issued by file control restart. It can have either of these values:
YES|NO

Output parameters

ACCMETH_RETURN_CODE
is a two-byte code returned by SMSVSAM.
RESPONSE
is DFHFCCA’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
VSAM_REQUEST_ERROR
RLS_FAILURE
DISASTER ABEND

FCCA QUIESCE_COMPLETE function

When CICS has completed the processing required by it for a quiesce request from SMSVSAM, it issues an IDAQUIES call to SMSVSAM with a quiesce type of QUICMP.

Input parameters

DATASET
is the 44-character name of the base data set for which quiesce processing is complete.
VSAM_QUIESCE_TOKEN
is a token used to relate quiesce completion to the quiesce request which has been completed, and which is supplied by SMSVSAM when the quiesce request is received by CICS.

Output parameters

ACCMETH_RETURN_CODE
is a two-byte code returned by SMSVSAM.
RESPONSE
is DFHFCCA’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
VSAM_REQUEST_ERROR
RLS_FAILURE
DISASTER ABEND

FCCA QUIESCE_REQUEST function

DFHFCCA issues quiesce requests to SMSVSAM on behalf of the quiesce component of CICS. It issues IDAQUIES calls of the following types:

Input parameters

DATASET
is the 44-character name of the base data set to be quiesced.
QUIESCE_TYPE
is the type of quiesce, and can have any of these values:
QUIESCE|UNQUIESCE|NONBWO_END|BWO_END
QUIESCE_TYPE
is the type of quiesce, and can have any of these values:
QUIESCE|UNQUIESCE|NONBWO_END|BWO_END
[IMMEDIATE]
applies only when the quiesce type is quiesce, and indicates whether or not the quiesce will force files to close immediately, or will allow in-flight units of work to reach syncpoint. It can have either of these values:
YES|NO

Output parameters

ACCMETH_RETURN_CODE
is a two-byte code returned by SMSVSAM.
CHECK_TOKEN
is a token which will be used on the CHECK request.
CONFLICTING_QUIESCE
indicates the type of quiesce which conflicts with this request, and can have any of these values:
QUIESCE|UNQUIESCE|NONBWO_END|BWO_END|NONBWO_START|
BWO_START
RESPONSE
is DFHFCCA’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
VSAM_REQUEST_ERROR
RLS_FAILURE
DISASTER ABEND

FCCA REGISTER_CONTROL_ACB function

The Control ACB is ’opened’ using an IDAREGP request to SMSVSAM. The Control ACB must be registered before CICS can open any ’ordinary’ ACB for RLS access.

Input parameters

None

Output parameters

VSAM_RETURN_CODE
is a fullword return code from VSAM.
VSAM_REASON_CODE
is a fullword return code from VSAM.
VSAM_ERROR_DATA
is an 8-byte field containing error data returned by VSAM.
RESPONSE
is DFHFCCA’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
RLS_FAILURE
VSAM_REQUEST_ERROR
DISASTER
DISASTER_PERCOLATION
ABEND

FCCA RELEASE_LOCKS function

CICS issues an IDALKREL request to SMSVSAM as part of commit processing at the end of every unit of work. It requests VSAM to release all locks owned by the unit of work.

Input parameters

LUWID
is a pointer to an IFGLUWID structure containing the id for the unit of work.
[RESTART]
is an optional parameter which indicates whether the call was issued by file control restart. It can have either of these values:
YES|NO

Output parameters

ACCMETH_RETURN_CODE
is a two-byte code returned by SMSVSAM.
RESPONSE
is DFHFCCA’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
VSAM_REQUEST_ERROR
RLS_FAILURE
DISASTER ABEND

FCCA RESET_NONRLS_BATCH function

CICS issues an IDARECOV TYPE=NONRLS request to VSAM when it has completed processing the NSR batch override response from an RLS file open. SMSVSAM resets the state of the data set in the sharing control data set to indicate that the batch override (or ’non RLS update permitted’) state no longer needs to be reported to this CICS when it opens the data set.

Input parameters

DATASET
is the 44-character name of the base data set for which the state is to be cleared.

Output parameters

ACCMETH_RETURN_CODE
is a two-byte code returned by SMSVSAM.
RESPONSE
is DFHFCCA’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
VSAM_REQUEST_ERROR
RLS_FAILURE
DISASTER ABEND

FCCA RETAIN_DATASET_LOCKS function

CICS issues an IDARETLK TYPE=SS call to SMSVSAM when a unit of work has suffered a backout failure on a data set. This requests SMSVSAM to mark all locks against the data set owned by the unit of work for conversion into retained locks on a subsequent IDALKREL call.

Input parameters

LUWID
is a pointer to an IFGLUWID structure containing the id for the unit of work.
DATASET
is the 44-character name of the base data set which has suffered a backout failure.

Output parameters

ACCMETH_RETURN_CODE
is a two-byte code returned by SMSVSAM.
RESPONSE
is DFHFCCA’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
VSAM_REQUEST_ERROR
RLS_FAILURE
DISASTER ABEND

FCCA RETAIN_UOW_LOCKS function

CICS issues an IDARETLK TYPE=IND call to SMSVSAM when a unit of work has encountered an in-doubt failure. This requests VSAM to mark all locks owned by the unit of work for conversion into retained locks on a subsequent IDALKREL call.

Input parameters

LUWID
is a pointer to an IFGLUWID structure containing the id for the unit of work.

Output parameters

ACCMETH_RETURN_CODE
is a two-byte code returned by SMSVSAM.
RESPONSE
is DFHFCCA’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
VSAM_REQUEST_ERROR
RLS_FAILURE
DISASTER ABEND

FCCA UNREGISTER_CONTROL_ACB function

The RLS Control ACB is ’closed’ using an IDAUNRP request to SMSVSAM. The Control ACB cannot be unregistered while there are any ’ordinary’ ACBs open for RLS access.

Input parameters

None

Output parameters

VSAM_RETURN_CODE
is a fullword return code from VSAM.
VSAM_REASON_CODE
is a fullword reason code from VSAM.
RESPONSE
is DFHFCCA’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
RLS_FAILURE
VSAM_REQUEST_ERROR
DISASTER
DISASTER_PERCOLATION
ABEND

FCCI INQUIRE function

FCCI is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for the table inquire function. It is not used by CICS.

FCCR POINT function

FCCR is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for data access requests.

The POINT function locates a record in a coupling facility data table.

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
TABLE_TOKEN
is the token returned on OPEN which must be passed on all subsequent requests against that open table.
KEY
is the 16-byte key of the record to be accessed. For approximate key operations, this specifies the start key and is updated on successful completion to contain the key of the record actually accessed.
KEY_COMPARISON
is the comparison condition, and can take the values
LT|LTEQ|EQ|GTEQ|GT
KEY_MATCH_LENGTH
is the key match length for generic key operations.
UOW_ID
is the unit of work identification, which is required when updating using the locking model (non-recoverable or recoverable).
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

KEY
returns the 16-byte key of the located record.
RESPONSE
is DFHFCCR’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECORD_NOT_FOUND
TABLE_LOADING
TABLE_TOKEN_INVALID
TABLE_DESTROYED
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCR HIGHEST function

FCCR is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for data access requests.

The HIGHEST function returns the highest key in a coupling facility data table, if any.

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
TABLE_TOKEN
is the token returned on OPEN which must be passed on all subsequent requests against that open table.
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

KEY
returns the 16-byte key of the highest record.
RESPONSE
is DFHFCCR’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECORD_NOT_FOUND
TABLE_LOADING
TABLE_TOKEN_INVALID
TABLE_DESTROYED
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCR READ function

FCCR is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for data access requests.

The READ function reads a record from a coupling facility data table, optionally for update.

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
TABLE_TOKEN
is the token returned on OPEN which must be passed on all subsequent requests against that open table.
KEY_COMPARISON
is the comparison condition, and can take the values
LT|LTEQ|EQ|GTEQ|GT
KEY_MATCH_LENGTH
is the key match length for generic key operations.
KEY
is the 16-byte key of the record to be accessed. For approximate key operations, this specifies the start key and is updated on successful completion to contain the key of the record actually accessed.
BUFFER
is the input buffer for read requests.
UOW_ID
is the unit of work identification, which is required when updating using the locking model (non-recoverable or recoverable).
SUSPEND
specifies whether to wait if the requested record is locked by an active lock, and can take the values
YES|NO
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

UPDATE_TOKEN
returns a token on a read for update.
KEY
returns the 16-byte key of the highest record.
LOCK_OWNER_SYSTEM
identifies the MVS™ system from which the record lock was acquired for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
LOCK_OWNER_APPLID
identifies the applid of the region which owns the record lock for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
LOCK_OWNER_UOW_ID
identifies the unit of work which owns the record lock for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
RESPONSE
is DFHFCCR’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECORD_NOT_FOUND
RECORD_BUSY
RECORD_LOCKED
TABLE_LOADING
INVALID_REQUEST
INCOMPLETE_UPDATE
TABLE_TOKEN_INVALID
TABLE_DESTROYED
UOW_FAILED
UOW_NOT_IN_FLIGHT
UOW_TOO_LARGE
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCR READ_DELETE function

FCCR is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for data access requests.

The READ_DELETE function reads and deletes a record from a coupling facility data table. It is not used by CICS.

FCCR UNLOCK function

FCCR is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for data access requests.

The UNLOCK function unlocks a record previously read for update in a coupling facility data table.

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
TABLE_TOKEN
is the token returned on OPEN which must be passed on all subsequent requests against that open table.
KEY
is the 16-byte key of the record to be unlocked.
BUFFER
is the input buffer for read requests.
UPDATE_TOKEN
is the token returned on the preceding read for update.
UOW_ID
is the unit of work identification, which is required for the locking model (non-recoverable or recoverable).
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

RESPONSE
is DFHFCCR’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECORD_NOT_FOUND
RECORD_CHANGED
TABLE_LOADING
INVALID_REQUEST
UPDATE_TOKEN_INVALID
TABLE_TOKEN_INVALID
TABLE_DESTROYED
UOW_FAILED
UOW_NOT_IN_FLIGHT
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCR LOAD function

FCCR is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for data access requests.

The LOAD function adds a record to a coupling facility data table during loading.

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
TABLE_TOKEN
is the token returned on OPEN which must be passed on all subsequent requests against that open table.
KEY
is the 16-byte key of the record to be loaded.
DATA
is the address and length of the record data to be loaded.
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

RESPONSE
is DFHFCCR’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
DUPLICATE_RECORD
MAXIMUM_RECORDS_REACHED
NO_SPACE_IN_POOL
INVALID_REQUEST
INVALID_LENGTH
TABLE_TOKEN_INVALID
TABLE_DESTROYED
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCR WRITE function

FCCR is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for data access requests.

The WRITE function writes a new record to a coupling facility data table.

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
TABLE_TOKEN
is the token returned on OPEN which must be passed on all subsequent requests against that open table.
KEY
is the 16-byte key of the record to be added.
DATA
is the address and length of the record data to be added.
UOW_ID
is the unit of work identification, which is required when updating using the locking model (non-recoverable or recoverable).
SUSPEND
specifies whether to wait if the requested record is locked by an active lock, and can take the values
YES|NO
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

LOCK_OWNER_SYSTEM
identifies the MVS system from which the record lock was acquired for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
LOCK_OWNER_APPLID
identifies the applid of the region which owns the record lock for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
LOCK_OWNER_UOW_ID
identifies the unit of work which owns the record lock for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
RESPONSE
is DFHFCCR’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
DUPLICATE_RECORD
RECORD_BUSY
RECORD_LOCKED
MAXIMUM_RECORDS_REACHED
NO_SPACE_IN_POOL
TABLE_LOADING
INVALID_REQUEST
INVALID_LENGTH
UPDATE_TOKEN_INVALID
INCOMPLETE_UPDATE
TABLE_TOKEN_INVALID
TABLE_DESTROYED
UOW_FAILED
UOW_NOT_IN_FLIGHT
UOW_TOO_LARGE
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCR REWRITE function

FCCR is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for data access requests.

The REWRITE function rewrites an an existing record in a coupling facility data table, following a read for update.

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
TABLE_TOKEN
is the token returned on OPEN which must be passed on all subsequent requests against that open table.
KEY
is the 16-byte key of the record to be rewritten.
DATA
is the address and length of the record data to be rewritten.
UPDATE_TOKEN
is the token returned on the preceding read for update.
UOW_ID
is the unit of work identification, which is required when updating using the locking model (non-recoverable or recoverable).
SUSPEND
specifies whether to wait if the requested record is locked by an active lock, and can take the values
YES|NO
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

LOCK_OWNER_SYSTEM
identifies the MVS system from which the record lock was acquired for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
LOCK_OWNER_APPLID
identifies the applid of the region which owns the record lock for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
LOCK_OWNER_UOW_ID
identifies the unit of work which owns the record lock for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
RESPONSE
is DFHFCCR’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECORD_NOT_FOUND
RECORD_CHANGED
RECORD_BUSY
RECORD_LOCKED
MAXIMUM_RECORDS_REACHED
NO_SPACE_IN_POOL
TABLE_LOADING
INVALID_REQUEST
INVALID_LENGTH
UPDATE_TOKEN_INVALID
INCOMPLETE_UPDATE
TABLE_TOKEN_INVALID
TABLE_DESTROYED
UOW_FAILED
UOW_NOT_IN_FLIGHT
UOW_TOO_LARGE
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCR DELETE function

FCCR is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for data access requests.

The DELETE function deletes a record from a coupling facility data table, following a read for update.

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
TABLE_TOKEN
is the token returned on OPEN which must be passed on all subsequent requests against that open table.
KEY_COMPARISON
is the comparison condition, and can take the values
LT|LTEQ|EQ|GTEQ|GT
KEY_MATCH_LENGTH
is the key match length for generic key operations.
KEY
is the 16-byte key of the record to be deleted.
UPDATE_TOKEN
is the token returned on the preceding read for update.
UOW_ID
is the unit of work identification, which is required when updating using the locking model (non-recoverable or recoverable).
SUSPEND
specifies whether to wait if the requested record is locked by an active lock, and can take the values
YES|NO
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

KEY
is the 16-byte key of the record actually deleted.
LOCK_OWNER_SYSTEM
identifies the MVS system from which the record lock was acquired for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
LOCK_OWNER_APPLID
identifies the applid of the region which owns the record lock for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
LOCK_OWNER_UOW_ID
identifies the unit of work which owns the record lock for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
RESPONSE
is DFHFCCR’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECORD_NOT_FOUND
RECORD_CHANGED
RECORD_BUSY
RECORD_LOCKED
TABLE_LOADING
INVALID_REQUEST
UPDATE_TOKEN_INVALID
INCOMPLETE_UPDATE
TABLE_TOKEN_INVALID
TABLE_DESTROYED
UOW_FAILED
UOW_NOT_IN_FLIGHT
UOW_TOO_LARGE
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCR DELETE_MULTIPLE function

FCCR is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for data access requests.

The DELETE_MULTIPLE function deletes records from a coupling facility data table, subject to key match conditions, until no more records match or an exception occurs.

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
TABLE_TOKEN
is the token returned on OPEN which must be passed on all subsequent requests against that open table.
KEY_COMPARISON
is the comparison condition, and can take the values
LT|LTEQ|EQ|GTEQ|GT
KEY_MATCH_LENGTH
is the key match length for generic key operations.
KEY
is the 16-byte key of the record(s) to be deleted.
UOW_ID
is the unit of work identification, which is required when updating using the locking model (non-recoverable or recoverable).
SUSPEND
specifies whether to wait if the requested record is locked by an active lock, and can take the values
YES|NO
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

DELETED_RECORD_COUNT
is the number of records successfully deleted by the delete_multiple request.
KEY
is the 16-byte key of the last record deleted.
LOCK_OWNER_SYSTEM
identifies the MVS system from which the record lock was acquired for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
LOCK_OWNER_APPLID
identifies the applid of the region which owns the record lock for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
LOCK_OWNER_UOW_ID
identifies the unit of work which owns the record lock for a record_busy or record_locked condition. Also set when the wait exit is taken for a lock wait.
RESPONSE
is DFHFCCR’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECORD_NOT_FOUND
RECORD_CHANGED
RECORD_BUSY
RECORD_LOCKED
TABLE_LOADING
INVALID_REQUEST
UPDATE_TOKEN_INVALID
INCOMPLETE_UPDATE
TABLE_TOKEN_INVALID
TABLE_DESTROYED
UOW_FAILED
UOW_NOT_IN_FLIGHT
UOW_TOO_LARGE
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCT OPEN function

FCCT is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for table status functions (Open, Close etc.).

The OPEN function defines a coupling facility data table table and establishes a connection between it and a CICS file. A security check is performed for access to the table name. If the table does not exist, it is implicitly created. If the table requires loading, it can only be opened if the access mode specifies exclusive access (or prefer_shared, allowing exclusive access if necessary).

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
RECORD_LENGTH
specifies the maximum record length, in the range 1 to 32767.
KEY_LENGTH
specifies the key length, in the range 1 to 16.
MAXIMUM_RECORDS
specifies the maximum number of records which can be stored in the table.
UPDATE_MODEL
specifies the method to be used for updating. It can take any of the values:
CONTENTION|LOCKING|RECOVERABLE
Contention means version compare and swap. Locking means normal update locking. Recoverable includes backout support in addition to the basic locking model.
INITIAL_LOAD
specifies whether initial load is required. It can take the values:
YES|NO
OPEN_MODE
specifies a read_only or read_write open. It can take the values
READ_ONLY|READ_WRITE
ACCESS_MODE
specifies whether the table is being opened for exclusive or shared use. It can take the values:
EXCLUSIVE|SHARED|PREFER_SHARED
Only one user at a time can have an exclusive open active. If the table requires loading and is not yet being loaded, it can only be opened in exclusive mode. If PREFER_SHARED is specified, the table will be opened in exclusive mode if loading is required, otherwise it will be open in shared mode.
SHARED_ACCESS
specifies for an exclusive mode open whether other users will be allowed shared access to the file at the same time. It can take the values:
NONE|READ_ONLY|READ_WRITE
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

TABLE_TOKEN
is a unique token representing the connection to this table. It must be passed on all subsequent requests against that open table, including close and set.
RECORD_LENGTH
returns the maximum record length of the table.
KEY_LENGTH
returns the key length of the table.
MAXIMUM_RECORDS
returns the maximum number of records limit for the table.
UPDATE_MODEL
returns the update model for the data table. It can take any of the values:
CONTENTION|LOCKING|RECOVERABLE
Contention means version compare and swap. Locking means normal update locking. Recoverable includes backout support in addition to the basic locking model.
INITIAL_LOAD
returns whether or not the data table requires initial loading. It can take the values:
YES|NO
ACCESS_MODE
returns whether the table was opened for exclusive or shared use. It can take the values:
EXCLUSIVE|SHARED
LOADED
returns an indication of whether the table has been loaded. If the table was created as empty this is set to yes as if loading were already done. It can take the values:
YES|NO
CURRENT_USERS
returns the number of explicit opens which are currently active against the table (not including internal recoverable opens issued by the server).
CURRENT_RECORDS
returns the number of records in the data table.
CURRENT_HIGH_KEY
returns the key of the last record in the table at the time of the request, or low values if the table does not contain any records.
RESPONSE
is DFHFCCT’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
ACCESS_NOT_ALLOWED
TABLE_NOT AVAILABLE
NOT_YET_LOADED
SHARED_ACCESS_CONFLICT
EXCLUSIVE_ACCESS_CONFLICT
INCOMPATIBLE_ATTRIBUTES
INCOMPLETE_ATTRIBUTES
INCORRECT_STATE
RECOVERY_NOT_ENABLED
OPTION_NOT_SUPPORTED
NO_SPACE_IN_POOL
MAXIMUM TABLES_REACHED
TOO_MANY_USERS
TABLE_DESTROYED
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCT CLOSE function

FCCT is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for table status functions (Open, Close etc.).

The CLOSE function terminates the connection to the specified table.

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
TABLE_TOKEN
is the token which was returned by the open.
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

RESPONSE
is DFHFCCT’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
TABLE_TOKEN_INVALID
TABLE_DESTROYED
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCT DELETE function

FCCT is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for table status functions (Open, Close etc.).

The DELETE function deletes a coupling facility data table, provided that it is not currently open. A security check for table access is performed.

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

RESPONSE
is DFHFCCT’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
ACCESS_NOT_ALLOWED
TABLE_NOT_FOUND
EXCLUSIVE_ACCESS_CONFLICT
TABLE_DESTROYED
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCT SET function

FCCT is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for table status functions (Open, Close etc.).

The SET function is used to change the attributes of a table. The maximum number of records can be changed, the open mode can be changed to indicate no longer loading, and the access mode can be changed from exclusive to shared.

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
MAXIMUM_RECORDS
specifies the maximum number of records which can be stored in the table.
AVAILABLE
indicates whether new open requests are to be allowed for this table. It can take the values:
YES|NO
LOADED
indicates whether the table is to be marked as loaded. It can take the values:
YES|NO
ACCESS_MODE
specifies the access mode which is to be set for the table. It can take the values:
EXCLUSIVE|SHARED
The access mode is normally set to shared when a data table load has completed.
SHARED_ACCESS
specifies the shared access which is to be allowed by other users when the access mode is shared.
NONE|READ_ONLY|READ_WRITE
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

RESPONSE
is DFHFCCT’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
ACCESS_NOT_ALLOWED
TABLE_NOT_FOUND
SHARED_ACCESS_CONFLICT
EXCLUSIVE_ACCESS_CONFLICT
ALREADY_SET
INCORRECT_STATE
OPTION_NOT_SUPPORTED
TABLE_TOKEN_INVALID
TABLE_DESTROYED
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCT EXTRACT_STATISTICS function

FCCT is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for table status functions (Open, Close etc.).

The EXTRACT_STATISTICS function returns information about a table which is currently open, with optional reset.

Input parameters

TABLE_NAME
is the 16-character name of the CFDT (8 characters padded with trailing spaces).
TABLE_TOKEN
is the token which was returned by the open.
RESET_STATISTICS
is an optional parameter which specifies whether or not statistics are to be reset. It can take the values
YES|NO
TRANSACTION_NUMBER
identifies the requesting task within the debug trace, if used.

Output parameters

CURRENT_USERS
is the number of explicit opens which are currently active against the table (not including internal recoverable opens issued by the server).
CURRENT_RECORDS
is the number of records currently in the data table.
HIGHEST_RECORDS
is the highest number of records in the table as seen by the current server at any time since the last statistics reset.
CONTENTION_COUNT
is the number of times a rewrite or delete failed because of a mismatched version (for the contention model) or the number of times that a lock was found to be unavailable (for the locking or recoverable models) since the last statistics reset.
RESPONSE
is DFHFCCT’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
TABLE_TOKEN_INVALID

FCCU PREPARE function

FCCU is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for unit of work related functions.

The PREPARE function prepares to commit a unit of work.

Input parameters

UOW_ID
is the CICS unit of work identification, which is prefixed by the CFDT server with the subsystem name to form the fully qualified unit of work identifier.
TRANSACTION_NUMBER
is used for debug trace purposes.

Output parameters

RESPONSE
is DFHFCCU’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECOVERY_NOT_ENABLED
UOW_NOT_FOUND
UOW_MADE_NO_CHANGES
UOW_FAILED
NO_SPACE_IN_POOL
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCU RETAIN function

FCCU is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for unit of work related functions.

The RETAIN function marks a unit of work as retained.

Input parameters

UOW_ID
is the CICS unit of work identification, which is prefixed by the CFDT server with the subsystem name to form the fully qualified unit of work identifier.
TRANSACTION_NUMBER
is used for debug trace purposes.

Output parameters

RESPONSE
is DFHFCCU’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECOVERY_NOT_ENABLED
UOW_NOT_FOUND
UOW_MADE_NO_CHANGES
UOW_FAILED
NO_SPACE_IN_POOL
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCU COMMIT function

FCCU is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for unit of work related functions.

The COMMIT function commits a unit of work.

Input parameters

UOW_ID
is the CICS unit of work identification, which is prefixed by the CFDT server with the subsystem name to form the fully qualified unit of work identifier.
TRANSACTION_NUMBER
is used for debug trace purposes.

Output parameters

RESPONSE
is DFHFCCU’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECOVERY_NOT_ENABLED
UOW_NOT_FOUND
UOW_MADE_NO_CHANGES
UOW_FAILED
NO_SPACE_IN_POOL
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCU BACKOUT function

FCCU is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for unit of work related functions.

The BACKOUT function backs out a unit of work.

Input parameters

UOW_ID
is the CICS unit of work identification, which is prefixed by the CFDT server with the subsystem name to form the fully qualified unit of work identifier.
TRANSACTION_NUMBER
is used for debug trace purposes.

Output parameters

RESPONSE
is DFHFCCU’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECOVERY_NOT_ENABLED
UOW_NOT_FOUND
UOW_MADE_NO_CHANGES
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCCU INQUIRE function

FCCU is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for unit of work related functions.

The INQUIRE function inquires about the status of a unit of work.

Input parameters

UOW_ID
is the CICS unit of work identification, which is prefixed by the CFDT server with the subsystem name to form the fully qualified unit of work identifier.
UOW_RESTARTED
is an optional parameter which indicates whether the inquire should select only units of work which have been through restart processing, and can take the values:
NO|YES
TRANSACTION_NUMBER
is used for debug trace purposes.
BROWSE
specifies whether the inquire is for a single unit of work or for the first or next UOW in a browse. If omitted, a single UOW inquire is performed. If specified, it can take the values
FIRST|NEXT
FIRST indicates a search for a UOWID greater than or equal to the specified UOWID, and NEXT indicates a search for a UOWID greater than the specified UOWID.

Output parameters

UOW_STATE
indicates the state of an active unit of work, and can have any of the values:
IN_FLIGHT|IN_DOUBT|IN_COMMIT|IN_BACKOUT
In_flight means that the unit of work has made some changes but has not yet reached the stage of prepare to commit. In_doubt means that it has been prepared but not committed or backed out. In_commit means that commit processing has been started. In_backout means that backout processing has been started. (When commit or backout processing completes, the unit of work is deleted).
UOW_ID
is the CICS unit of work id of the UOW for which inquire data is being returned.
UOW_RESTARTED
indicates whether the unit of work has been through restart processing, and can take the values:
NO|YES
UOW_RETAINED
indicates whether the locks for the unit of work have been marked as retained, either explicitly within the current connection or implicitly by a restart. It can take the values:
NO|YES
RESPONSE
is DFHFCCU’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECOVERY_NOT_ENABLED
UOW_NOT_FOUND

FCCU RESTART function

FCCU is the parameter list used by File Control to communicate with the Coupling Facility Data Table cross-memory server, DFHCFMN, for unit of work related functions.

The RESTART function establishes recovery status on connecting to a CFDT server.

Input parameters

UOW_SUBSYSTEM_NAME
is not specified by CICS (the CICS applid is used by default).
TRANSACTION_NUMBER
is used for debug trace purposes.

Output parameters

RESPONSE
is DFHFCCU’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
SUBSYSTEM_ALREADY_ACTIVE
RESTART_ALREADY_ACTIVE
TABLE_OPEN_FAILED
NO_SPACE_IN_POOL
POOL_STATE_ERROR
CF_ACCESS_ERROR

FCDS EXTRACT_CFDT_STATS function

This function causes statistics relating to coupling facility data table usage to be extracted from the coupling facility data tables server.

Input parameters

FCTE_POINTER
is the address of the FCTE entry of the file for which CFDT statistics are to be extracted.
RESET_STATISTICS
indicates whether the statistics fields are to be reset to zero or not. It takes the values
YES|NO
TRANSACTION_NUMBER
is an optional parameter which allows the transaction number to be passed to the CFDT server for inclusion in trace messages.

Output parameters

CURRENT_USERS
is an optional fullword parameter which returns the current number of users of the coupling facility data table (that is, the number of opens issued against it).
MAXIMUM_RECORDS
is an optional fullword parameter which returns the current value of the MAXNUMRECS limit for the data table.
CURRENT_RECORDS
is an optional fullword parameter which returns the current number of records in the coupling facility data table.
HIGHEST_RECORDS
is an optional fullword parameter which returns the highest number of records which have ever been in this coupling facility data table since it was last created.
CONTENTION_COUNT
is an optional fullword parameter which returns the number of contentions which have been detected, for a coupling facility data table which uses the contention update model.
RESPONSE
is DFHFCDS’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION, INVALID or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
CFDT_CONNECT_ERROR
CFDT_DISCONNECT_ERROR
CFDT_REOPEN_ERROR
CFDT_SERVER_NOT_AVAILABLE
CFDT_SERVER_NOT_FOUND
CFDT_STATS_ERROR
CFDT_SYSIDERR
CFDT_TABLE_GONE
INVALID
INVALID_FORMAT
INVALID_FUNCTION
DISASTER
POOL_ELEMENT_NOT_FOUND
ABEND
DISASTER_PERCOLATION

FCDS DISCONNECT_CFDT_POOLS function

This function causes CICS to disconnect from any coupling facility data table pools to which it is connected.

Input parameters

None

Output parameters

RESPONSE
is DFHFCDS’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION, INVALID or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION CFDT_DISCONNECT_ERROR
INVALID
INVALID_FORMAT
INVALID_FUNCTION
DISASTER
ABEND
DISASTER_PERCOLATION

FCDU PREPARE function

This function causes the coupling facility data table server to be called to prepare a unit of work which has made recoverable updates to one or more coupling facility data tables.

Input parameters

POOL_ELEM_ADDR
is the address of the pool element which identifies the coupling facility data table pool for which the prepare is to be issued. One or more of the coupling facility data tables updated by the unit of work reside in this pool. The prepare call will be issued to the CFDT server for this pool.
POOL_NAME
is the name of the coupling facility data table pool. The pool name is included for diagnostic purposes.
UOW_ID
is the identifier for the unit of work which is to be prepared.

Output parameters

RESPONSE
is DFHFCDU’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION, INVALID or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECOVERY_NOT_ENABLED
UOW_NOT_FOUND
UOW_MADE_NO_CHANGES
UOW_FAILED
NO_SPACE_IN_POOL
POOL_STATE_ERROR
CF_ACCESS_ERROR
CFDT_SYSIDERR
CFDT_SERVER_NOT_AVAILABLE
CFDT_SERVER_NOT_FOUND
CFDT_CONNECT_ERROR
CFDT_DISCONNECT_ERROR
RESYNC_RETRY_FAILED
INVALID
INVALID_FORMAT
INVALID_FUNCTION
DISASTER
ABEND
DISASTER_PERCOLATION

FCDU RETAIN function

This function causes the coupling facility data table server to be called to convert locks held by the unit of work against recoverable coupling facility data tables into retained locks.

Input parameters

POOL_ELEM_ADDR
is the address of the pool element which identifies the coupling facility data table pool for which the retain is to be issued. One or more of the coupling facility data tables updated by the unit of work reside in this pool. The retain call will be issued to the CFDT server for this pool.
POOL_NAME
is the name of the coupling facility data table pool. The pool name is included for diagnostic purposes.
UOW_ID
is the identifier for the unit of work for which locks are to be retained.

Output parameters

RESPONSE
is DFHFCDU’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION, INVALID or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECOVERY_NOT_ENABLED
UOW_NOT_FOUND
UOW_MADE_NO_CHANGES
UOW_FAILED
NO_SPACE_IN_POOL
POOL_STATE_ERROR
CF_ACCESS_ERROR
CFDT_SYSIDERR
CFDT_SERVER_NOT_AVAILABLE
CFDT_SERVER_NOT_FOUND
CFDT_CONNECT_ERROR
CFDT_DISCONNECT_ERROR
RESYNC_RETRY_FAILED
INVALID
INVALID_FORMAT
INVALID_FUNCTION
DISASTER
ABEND
DISASTER_PERCOLATION

FCDU COMMIT function

This function causes the coupling facility data table server to be called to commit a unit of work which has made recoverable updates to one or more coupling facility data tables.

Input parameters

POOL_ELEM_ADDR
is the address of the pool element which identifies the coupling facility data table pool for which the commit is to be issued. One or more of the coupling facility data tables updated by the unit of work reside in this pool. The commit call will be issued to the CFDT server for this pool.
POOL_NAME
is the name of the coupling facility data table pool. The pool name is included for diagnostic purposes.
UOW_ID
is the identifier for the unit of work which is to be committed.

Output parameters

RESPONSE
is DFHFCDU’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION, INVALID or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECOVERY_NOT_ENABLED
UOW_NOT_FOUND
UOW_MADE_NO_CHANGES
UOW_FAILED
NO_SPACE_IN_POOL
POOL_STATE_ERROR
CF_ACCESS_ERROR
CFDT_SYSIDERR
CFDT_SERVER_NOT_AVAILABLE
CFDT_SERVER_NOT_FOUND
CFDT_CONNECT_ERROR
CFDT_DISCONNECT_ERROR
RESYNC_RETRY_FAILED
INVALID
INVALID_FORMAT
INVALID_FUNCTION
DISASTER
ABEND
DISASTER_PERCOLATION

FCDU BACKOUT function

This function causes the coupling facility data table server to be called to backout a unit of work which has made recoverable updates to one or more coupling facility data tables.

Input parameters

POOL_ELEM_ADDR
is the address of the pool element which identifies the coupling facility data table pool for which the backout is to be issued. One or more of the coupling facility data tables updated by the unit of work reside in this pool. The backout call will be issued to the CFDT server for this pool.
POOL_NAME
is the name of the coupling facility data table pool. The pool name is included for diagnostic purposes.
UOW_ID
is the identifier for the unit of work which is to be backed out.

Output parameters

RESPONSE
is DFHFCDU’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION, INVALID or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECOVERY_NOT_ENABLED
UOW_NOT_FOUND
UOW_MADE_NO_CHANGES
POOL_STATE_ERROR
CF_ACCESS_ERROR
CFDT_SYSIDERR
CFDT_SERVER_NOT_AVAILABLE
CFDT_SERVER_NOT_FOUND
CFDT_CONNECT_ERROR
CFDT_DISCONNECT_ERROR
RESYNC_RETRY_FAILED
INVALID
INVALID_FORMAT
INVALID_FUNCTION
DISASTER
ABEND
DISASTER_PERCOLATION

FCDU INQUIRE function

This function causes an INQUIRE to be issued to the coupling facility data table in order to obtain information about the status of an active unit of work. If the BROWSE parameter is specified, then the function will return the status of the next unit of work in the browse.

Input parameters

POOL_ELEM_ADDR
is the address of the pool element which identifies the coupling facility data table pool for which the INQUIRE is to be issued. The inquire call will be issued to the CFDT server for this pool.
POOL_NAME
is the name of the coupling facility data table pool. The pool name is included for diagnostic purposes.
UOW_ID
identifies the unit of work for which status information is to be returned, or gives the previous unit of work in the browse.
UOW_RESTARTED
is an optional input parameter which indicates whether or not the inquire should select only units of work which have been through restart processing. It can take the values
YES|NO
BROWSE
is an optional parameter which specified whether the inquire is for a single unit of work or for the first or next UOW in a browse, and which can take the values
FIRST|NEXT
If the BROWSE parameter is omitted, the request is a single UOW inquire. The FIRST option indicates a search for a UOW id greater than or equal to the specified UOW_ID, and next indicates a search for a UOW id greater than the specified UOW_ID.

Output parameters

RETURNED_UOW_ID
Is the unit of work for which the browse is returning status information.
UOW_STATE
indicates the state of the unit of work, and can have the values:
IN_FLIGHT|IN_DOUBT|IN_COMMIT|IN_BACKOUT
UOW_RESTART_STATE
indicates whether the unit of work has been through restart processing.
UOW_RETAINED
indicates whether the locks for the unit of work have been retained.
RESPONSE
is DFHFCDU’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION, INVALID or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
RECOVERY_NOT_ENABLED
UOW_NOT_FOUND
CF_ACCESS_ERROR
CFDT_SYSIDERR
CFDT_SERVER_NOT_AVAILABLE
CFDT_SERVER_NOT_FOUND
CFDT_CONNECT_ERROR
CFDT_DISCONNECT_ERROR
RESYNC_RETRY_FAILED
INVALID
INVALID_FORMAT
INVALID_FUNCTION
DISASTER
ABEND
DISASTER_PERCOLATION

FCDU RESTART function

This function establishes recovery status for a coupling facility data table pool when a CICS region has successfully connected to it.

Input parameters

POOL_ELEM_ADDR
is the address of the pool element which identifies the coupling facility data table pool for recovery status is to be established. The RESTART call will be issued to the CFDT server for this pool.
POOL_NAME
is the name of the coupling facility data table pool. The pool name is included for diagnostic purposes.

Output parameters

RETURNED_UOW_ID
Is the unit of work for which the browse is returning status information.
UOW_STATE
indicates the state of the unit of work, and can have the values:
IN_FLIGHT|IN_DOUBT|IN_COMMIT|IN_BACKOUT
UOW_RESTART_STATE
indicates whether the unit of work has been through restart processing.
UOW_RETAINED
indicates whether the locks for the unit of work have been retained.
RESPONSE
is DFHFCDU’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION, INVALID or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
SERVER_CONNECTION_FAILED
SUBSYSTEM_ALREADY_ACTIVE
RESTART_ALREADY_ACTIVE
TABLE_OPEN_FAILED
NO_SPACE_IN_POOL
CF_ACCESS_ERROR
CFDT_SYSIDERR
CFDT_SERVER_NOT_AVAILABLE
CFDT_SERVER_NOT_FOUND
CFDT_CONNECT_ERROR
CFDT_DISCONNECT_ERROR
INVALID
INVALID_FORMAT
INVALID_FUNCTION
DISASTER
ABEND
DISASTER_PERCOLATION

FCDY RESYNC_CFDT_POOL function

This function causes a coupling facility data table pool to be resynchronized.

Input parameters

POOL_NAME
is the name of the coupling facility data table pool which is to be resynchronized.

Output parameters

RESPONSE
is DFHFCDY’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION, INVALID or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
INITIATE_RECOVERY_FAILED
TERMINATE_RECOVERY_FAILED
CFDT_SERVER_CALL_FAILED
INVALID
INVALID_FORMAT
INVALID_FUNCTION
DISASTER
ABEND
DISASTER_PERCOLATION

FCDY RESYNC_CFDT_LINK function

This function causes a link between a unit of work and a coupling facility data table pool to be resynchronized.

Input parameters

POOL_NAME
is the name of the coupling facility data table pool for which the link is to be resynchronized.
UOW_ID
is the unit of work ID which identifies the link to be resynchronized.

Output parameters

RESPONSE
is DFHFCDY’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION, INVALID or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
INITIATE_RECOVERY_FAILED
TERMINATE_RECOVERY_FAILED
CFDT_SERVER_CALL_FAILED
INVALID
INVALID_FORMAT
INVALID_FUNCTION
DISASTER
ABEND
DISASTER_PERCOLATION

FCDY RETURN_CFDT_ENTRY_POINTS function

This function causes module DFHFCDY to return the entry point addresses of the other modules with which it is link-edited.

Input parameters

None

Output parameters

CFDT_EP_DFHFCDW
is the entry point address of module DFHFCDW.
CFDT_EP_DFHFCDU
is the entry point address of module DFHFCDU.
RESPONSE
is DFHFCDY’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is INVALID or DISASTER. Possible values are:
RESPONSE Possible REASON values
INVALID
INVALID_FORMAT
INVALID_FUNCTION
DISASTER
ABEND
DISASTER_PERCOLATION

FCFL END_UOWDSN_BROWSE function

After a browse of all the data set failures within a unit of work, the END_UOWDSN_BROWSE function releases the storage that was used for a snapshot of the failures.

Input parameters

BROWSE_TOKEN
is the token which was used for the browse.

Output parameters

RESPONSE
is DFHFCFL’s response to the call. It can have any of these values:
OK|INVALID|DISASTER|PURGED
[REASON]
is returned when RESPONSE is INVALID or DISASTER. Possible values are:
RESPONSE Possible REASON values
INVALID INVALID_BROWSE_TOKEN
DISASTER
DISASTER_PERCOLATION
ABEND

FCFL FIND_RETAINED function

This function looks for any FLAB associated with the specified data set which is flagged as retained, indicating that there are retained locks associated with the data set.

Input parameters

DSNAME
is the 44-character name of the data set for which associated retained locks are to be found.

Output parameters

RETLOCKS
indicates whether or not there are retained locks associated with the data set, and can have either of these values:
RETAINED|NORETAINED
RESPONSE
is DFHFCFL’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
DISASTER_PERCOLATION
ABEND

FCFL FORCE_INDOUBTS function

This function is used by the CEMT or EXEC CICS SET DSNAME() UOWACTION(COMMIT|BACKOUT|FORCE) command. Shunted in-doubt units of work are forced to complete in the specified direction. FORCE means that the direction is obtained from the ACTION specified on the transaction definition.

Input parameters

DSNAME
is the 44-character name of the data set for which shunted in-doubt units of work are to be forced to complete.
DIRECTION
is the direction in which the units of work are to complete: forwards (commit), backwards (backout), or heuristic (from the action specified on the transaction definition). It can have any of these values:
FORWARD|BACKWARD|HEURISTIC

Output parameters

RESPONSE
is DFHFCFL’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
DISASTER_PERCOLATION
ABEND

FCFL GET_NEXT_UOWDSN function

This function returns the failure information for the next data set that has a failure within the unit of work being browsed.

Input parameters

BROWSE_TOKEN
is the token for the browse, which was returned by a START_UOWDSN_BROWSE call.

Output parameters

DSNAME
is the 44-character name of the data set for which failure information is returned.
[RLSACCESS]
indicates whether the data set was last open in RLS or non-RLS access mode, and can have either of these values:
RLS|NOTRLS
[CAUSE]
indicates the cause of the failure, and can have any of these values:
CACHE|RLSSERVER|CONNECTION|DATASET|UNDEFINED
[RETAIN_REASON]
indicates the reason for the failure, and can have any of these values:
RLSGONE|COMMITFAIL|IOERROR|DATASETFULL|INDEXRECFULL|
OPENERROR|DELEXITERROR|DEADLOCK|BACKUPNONBWO|
LOCKSTRUCFULL|FAILEDBKOUT|NOTAPPLIC|RR_COMMITFAIL|
RR_INDOUBT
RESPONSE
is DFHFCFL’s response to the call. It can have any of these values:
OK|INVALID|EXCEPTION|DISASTER
[REASON]
is returned when RESPONSE is EXCEPTION, INVALID, or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION END_OF_LIST
INVALID INVALID_BROWSE_TOKEN
DISASTER
DISASTER_PERCOLATION
ABEND

FCFL RESET_BFAILS function

This function is used by the CEMT and EXEC CICS SET DSNAME() ACTION(RESETLOCKS) command. It purges shunted unit of work log records which hold backout-failure or commit-failure locks on the specified data set, and releases the locks.

Input parameters

DSNAME
is the 44-character name of the data set for which backout and commit failures are to be reset.

Output parameters

RESPONSE
is DFHFCFL’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
DISASTER_PERCOLATION
ABEND
REMOVE_FAILURE

FCFL RETRY function

This function is used by the CEMT and EXEC CICS SET DSNAME() UOWACTION(RETRY) command. It drives retry of any failed backouts and commits for the specified data set, by informing DFHFCRR that the failed resource (that is, the data set) is now available.

Input parameters

DSNAME
is the 44-character name of the data set for which backout and/or commits are to be retried.

Output parameters

RESPONSE
is DFHFCFL’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
DISASTER_PERCOLATION
ABEND
RESOURCE_NOT_FOUND

FCFL START_UOWDSN_BROWSE function

This function starts a browse of the data set failures within a unit of work. A snapshot of the failed data sets for the unit of work and the reasons for the failures are collected in an in-storage table to be browsed by the GET_NEXT_UOWDSN function.

Input parameters

UOW
is the 8-byte local unit of work identifier.

Output parameters

BROWSE_TOKEN
is a token which is used during the browse.
RESPONSE
is DFHFCFL’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
UOW_NOT_FOUND
NO_FLABS_FOUND
DISASTER
DISASTER_PERCOLATION
ABEND

FCFL TEST_USER function

This function is used to test if the task has updated a record, and therefore established itself as a file user, either for any data set or for a specified data set. It can be used either as a domain subroutine call or as an inline macro.

Input parameters

[ENVIRONMENT]
is an optional parameter which is a fullword environment identifier. If specified, then the function will test whether the task is a user of any files within that environment.
[DSNAME]
is an optional parameter which specifies that a particular data set is to be tested.

Output parameters

FLAB_PTR
is the address of a FLAB which was found by the test. If a non-zero value is returned, then this means that the user is a task.
RESPONSE
is DFHFCFL’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
DISASTER_PERCOLATION
ABEND

FCLJ FILE_OPEN function

This function is called when a file is opened, and causes a 'tie up record' record to be written to the log of logs if either the file (or associated data set) is forward recoverable or if autojournalling is specified for the file, to the forward recovery log if the file (or associated data set) is forward recoverable, and to the autojournal if autojournalling is specified for the file.

Input parameters

FCTE_ADDRESS
is the address of the file control table entry for the file being opened.

Output parameters

RESPONSE
is DFHFCLJ’s response to the call. It can have any of these values:
OK|INVALID|PURGED|DISASTER
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LG_RETURNED_ERROR

FCLJ FILE_CLOSE Function

This function is called when a file is closed, and causes a file close log record to be written to the log of logs if either the file (or associated data set) is forward recoverable or if autojournalling is specified for the file, to the forward recovery log if the file (or associated data set) is forward recoverable, and to the autojournal if autojournalling is specified for the file.

Input parameters

FCTE_ADDRESS
is the address of the file control table entry for the file being closed.

Output parameters

RESPONSE
is DFHFCLJ’s response to the call. It can have any of these values:
OK|INVALID|PURGED|DISASTER
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LG_RETURNED_ERROR

FCLJ READ_ONLY Function

This function causes a read_only log record to be written to an autojournal, if read-only autojournalling is specified on the file definition. The log record is built using the input parameters.

Input parameters

BASE_ESDS_RBA
is the RBA of the record being read, if the file is an ESDS.
FCTE_ADDRESS
is the address of the file control table entry for the file being read.
KEY_ADDRESS
is the address of the key of the record being read.
KEY_LENGTH
is the key length of the record being read.
RECORD_ADDRESS
is the address of the record being read.
RECORD_LENGTH
is the length of the record being read.
SHUNTED
indicates whether or not the unit of work has ever been shunted (due to some failure during syncpoint). It can have either of these values:
YES|NO

Output parameters

RESPONSE
is DFHFCLJ’s response to the call. It can have any of these values:
OK|INVALID|PURGED|DISASTER
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LG_RETURNED_ERROR
RM_RETURNED_ERROR

FCLJ READ_UPDATE Function

This function causes a read_update log record to be written to the system log, if the file is recoverable, and if the destination parameter specifies either LOG or BOTH. It causes a read_update log record to be written to the autojournal if journaling of read updates is specified on the file definition, and if the destination parameter specifies either JOURNAL or BOTH. The log record is built using the input parameters.

Input parameters

BASE_ESDS_RBA
is the RBA of the record being read for update, if the file is an ESDS.
FCTE_ADDRESS
is the address of the file control table entry for the file being read for update.
KEY_ADDRESS
is the address of the key of the record being read for update.
KEY_LENGTH
is the key length of the record being read for update.
RECORD_ADDRESS
is the address of the record being read for update.
RECORD_LENGTH
is the length of the record being read for update.
DESTINATION
specifies whether the log record is to be written to the autojournal, the system log, or both. It is used to suppress writing records that would otherwise be requested by the file definition. It can have any of these values:
JOURNAL|LOG|BOTH
SYNCHRONIZE_LOG
indicates whether or not the system log is to be synchronized (forced) when the log record is written. It can have either of these values:
YES|NO
SHUNTED
indicates whether or not the unit of work has ever been shunted (due to some failure during syncpoint). It can have either of these values:
YES|NO

Output parameters

[LOG_TOKEN]
is an optional parameter which is returned if SYNCHRONIZE(NO) was specified, and which contains a token to be used when subsequently synchronizing (forcing) the system log.
RESPONSE
is DFHFCLJ’s response to the call. It can have any of these values:
OK|INVALID|PURGED|DISASTER
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LG_RETURNED_ERROR
RM_RETURNED_ERROR

FCLJ WRITE_UPDATE Function

This function causes a write_update log record to be written to the forward recovery log, if the file (or associated data set) is forward recoverable, and to the autojournal, if journaling of write updates is specified on the file definition. A write_update log record represents the completion of a file REWRITE request. The log record is built using the input parameters.

Input parameters

BACKOUT
indicates if the call is made as part of transaction backout processing. It can have either of these values:
YES|NO
BASE_ESDS_RBA
is the RBA of the record being rewritten, if the file is an ESDS.
FCTE_ADDRESS
is the address of the file control table entry for the file being rewritten to.
KEY_ADDRESS
is the address of the key of the record being rewritten.
KEY_LENGTH
is the key length of the record being rewritten to.
RECORD_ADDRESS
is the address of the record being rewritten.
RECORD_LENGTH
is the length of the record being rewritten.
SHUNTED
indicates whether or not the unit of work has ever been shunted (due to some failure during syncpoint). It can have either of these values:
YES|NO

Output parameters

RESPONSE
is DFHFCLJ’s response to the call. It can have any of these values:
OK|INVALID|PURGED|DISASTER
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LG_RETURNED_ERROR
RM_RETURNED_ERROR

FCLJ WRITE_ADD Function

This function causes a write_add log record to be written to the system log if the file is recoverable, and if the destination parameter specifies BOTH. It causes a write_add log record to be written to the autojournal if journaling of write adds was specified on the file definition. The log record is built using the input parameters.

Input parameters

BACKOUT
indicates if the call is made as part of transaction backout processing. It can have either of these values:
YES|NO
BASE_ESDS_RBA
is the RBA of the record being added, if the file is an ESDS.
FCTE_ADDRESS
is the address of the file control table entry for the file being written to.
KEY_ADDRESS
is the address of the key of the record being added.
KEY_LENGTH
is the key length of the record being written to.
MASSINSERT
indicates whether or not the record is being added as part of a mass insert. It can have either of these values:
YES|NO
DESTINATION
specifies whether the log record is to be written to the autojournal only, or to both the autojournal and the system log. It is used to suppress writing records that would otherwise be requested by the file definition. It can have either of these values:
JOURNAL|BOTH
RECORD_ADDRESS
is the address of the record being added.
RECORD_LENGTH
is the length of the record being added.
SHUNTED
indicates whether or not the unit of work has ever been shunted (due to some failure during syncpoint). It can have either of these values:
YES|NO

Output parameters

RESPONSE
is DFHFCLJ’s response to the call. It can have any of these values:
OK|INVALID|PURGED|DISASTER
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LG_RETURNED_ERROR
RM_RETURNED_ERROR

FCLJ WRITE_ADD_COMPLETE Function

This function causes a write_add_complete log record to be written to the forward recovery log if the file (or associated data set) is forward recoverable, and to the autojournal if write_add_complete journaling is specified on the file definition. It causes a truncated write_add_complete log record to be written to the system log if the file is a recoverable ESDS accessed in non-RLS mode. If MASSINSERT(YES) and MASSINSERT_STAGE(LAST) are specified, then only the system log record is written, and not the forward recovery log or autojournal record. The log record is built using the input parameters.

Input parameters

BACKOUT
indicates if the call is made as part of transaction backout processing. It can have either of these values:
YES|NO
BASE_ESDS_RBA
is the RBA of the record that has been added, if the file is an ESDS.
FCTE_ADDRESS
is the address of the file control table entry for the file that has been written to.
KEY_ADDRESS
is the address of the key of the record which has been added.
KEY_LENGTH
is the key length for the file which has been written to.
MASSINSERT
indicates whether or not the record was added as part of a mass insert. It can have either of these values:
YES|NO
[MASSINSERT_STAGE]
is an optional parameter which indicates whether the record is either the first or last record added during a massinsert sequence. It can have either of these values:
FIRST|LAST
RECORD_ADDRESS
is the address of the record which has been added.
RECORD_LENGTH
is the length of the record which has been added.
SHUNTED
indicates whether or not the unit of work has ever been shunted (due to some failure during syncpoint). It can have either of these values:
YES|NO

Output parameters

RESPONSE
is DFHFCLJ’s response to the call. It can have any of these values:
OK|INVALID|PURGED|DISASTER
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LG_RETURNED_ERROR
RM_RETURNED_ERROR

FCLJ WRITE_DELETE Function

This function causes a write_delete log record to be written to the forward recovery log if the file (or associated data set) is forward recoverable, and to the autojournal if journaling of write_deletes is specified on the file definition. The log record is built using the input parameters.

Input parameters

BACKOUT
indicates if the call is made as part of transaction backout processing. It can have either of these values:
YES|NO
BASE_ESDS_RBA
is the RBA of the record being deleted, if the file is an ESDS.
FCTE_ADDRESS
is the address of the file control table entry for the file.
KEY_ADDRESS
is the address of the key of the record being deleted.
KEY_LENGTH
is the key length for the file.
BASE_KEY_ADDRESS
is the address of the base key of the record being deleted, which is used if the data set is being accessed via a path.
SHUNTED
indicates whether or not the unit of work has ever been shunted (due to some failure during syncpoint). It can have either of these values:
YES|NO

Output parameters

RESPONSE
is DFHFCLJ’s response to the call. It can have any of these values:
OK|INVALID|PURGED|DISASTER
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LG_RETURNED_ERROR
RM_RETURNED_ERROR

FCLJ SYNCHRONIZE_READ_UPDATE Function

This function causes any log records previously written to the system log for this file to be synchronized (forced). The log token returned on a previous call to write a log record for this file is supplied as input.

Input parameters

FCTE_ADDRESS
is the address of the file control table entry for the file being read for update.
LOG_TOKEN
is the token returned on a previous call. The system log record written by the previous call, plus any log records written prior to that, are hardened.

Output parameters

RESPONSE
is DFHFCLJ’s response to the call. It can have any of these values:
OK|INVALID|PURGED|DISASTER
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
RM_RETURNED_ERROR

FCLJ TAKE_KEYPOINT Function

Provided that BWO copy is supported by this CICS (indicated by a flag in file control static storage), then this function performs a scan of the file control table and, unless it has been called within the last half hour, writes a tie up record for each file open for update in non-RLS mode that is BWO-eligible and forward recoverable to the forward recovery log.

A tie up record specifies which CICS system within the sysplex opened the file, and the data set which the file was opened against. Tie up records are used by forward recovery utilities, for example CICSVR.

Input parameters

None

Output parameters

KEYPOINT_TAKEN
indicates whether or not the set of tie up records was successfully written. It can have either of these values:
YES|NO
RESPONSE
is DFHFCLJ’s response to the call. It can have any of these values:
OK|INVALID|PURGED|DISASTER
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LG_RETURNED_ERROR
TM_GETNEXT_FCTE_FAILED

FCLJ DATASET_COPY Function

This function is called when DFSMSdss initiates a copy of an RLS data set via the VSAM RLS quiesce mechanism. The function causes a ’tie up record’ to be written to the log of logs if either the data set is forward recoverable, or some flavor of autojournalling has been specified in the file definition. In addition, if applicable, a record is written to the forward recovery log.

A tie up record specifies which CICS system within the sysplex opened the file, and the data set which the file was opened against. Tie up records are used by forward recovery utilities, for example CICSVR.

Input parameters

FCTE_ADDRESS
is the address of the file control table entry for the file associated with a data set being copied.

Output parameters

RESPONSE
is DFHFCLJ’s response to the call. It can have any of these values:
OK|INVALID|PURGED|DISASTER
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
LG_RETURNED_ERROR

FCQI INITIATE_QUIESCE Function

This function takes a quiesce request of type QUIESCE, IMMQUIESCE, UNQUIESCE, QUIESCE_CANCEL, NONBWO_CANCEL or BWO_CANCEL and creates a FC Quiesce Send Element (FCQSE) to describe the request. The FCQSE is added to a chain anchored in FC static, and an ECB associated with the chain (also in FC static) is posted. DFHFCQI then either suspends until the quiesce request completes or returns immediately to its caller, depending on whether busy WAIT or NOWAIT was specified on the call.

When DFHFCQI posts the ECB, the CFQS transaction (DFHFCQS) wakes up and processes the FCQSE on the chain, calling DFHFCCA QUIESCE to issue the appropriate flavor of IDAQUIES macro to SMSVSAM. When the IDAQUIES has completed, DFHFCQS will resume DFHFCQI if it was suspended, communicating the results of the IDAQUIES via the FCQSE. The FCQSE can then be unchained and freed.

Input parameters

QUIESCE_TYPE
indicates the type of quiesce being initiated and can have any of these values:
QUIESCE|IMMQUIESCE|UNQUIESCE|NONBWO_CANCEL|
BWO_CANCEL|QUIESCE_CANCEL
DSNAME
is the 44-character name of the base data set to be quiesced.
BUSY
indicates whether DFHFCQI is to wait for the quiesce to complete, or is to return immediately to the caller, and can take either of these values:
WAIT|NOWAIT
SOURCE
indicates whether the source of the quiesce request was CICS or a user, and can take either of these values:
CICS|USER

Output parameters

RESPONSE
is DFHFCQI’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is INVALID, EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
INVALID INVALID_QUIESCE_TYPE
EXCEPTION
NOT_SUPPORTED
UNKNOWN_VSAM_DATASET
QUIESCE_NOT_POSSIBLE
UNQUIESCE_NOT_POSSIBLE
CANCELLED
TIMED_OUT
IOERR
SERVER_FAILURE
DATASET_MIGRATED
DISASTER
ABEND
CATALOG_ERROR
DISASTER_PERCOLATION

FCQI INQUIRE_QUIESCE Function

This function returns the quiesce state of a data set as QUIESCED, UNQUIESCED, or QUIESCING. DFHFCAT is called to inquire on the state of the ’quiesced’ bit in the VSAM ICF catalog, which will return QUIESCED or UNQUIESCED. If UNQUIESCED is returned, the FCQSE chain is then scanned to find an FCQSE specifying the data set in question. If such an FCQSE is found for a quiesce or immquiesce request then a state of QUIESCING is returned. There is no UNQUIESCING state as the unquiesce operation is far quicker than quiesce.

Input parameters

DSNAME
is the 44-character name of the base data set for which quiesce state information is to be returned.

Output parameters

QUIESCESTATE
indicates the quiesce state of the data set, and can have any of these values:
QUIESCED|UNQUIESCED|QUIESCING
RESPONSE
is DFHFCQI’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
NOT_SUPPORTED
UNKNOWN_VSAM_DATASET
IOERR
DISASTER
ABEND
CATALOG_ERROR
DISASTER_PERCOLATION

FCQI COMPLETE_QUIESCE Function

This function is invoked whenever CICS has finished the processing for those quiesce requests for which SMSVSAM must be notified with an IDAQUIES QUICMP. Such quiesce requests are VSAM QUICLOSE (quiesce), QIOCOPY (non-BWO backup) and QUIBWO (BWO backup). This is achieved by calling DFHFCCA QUIESCE_COMPLETE to issue the IDAQUIES QUICMP macro to SMSVSAM.

Input parameters

DSNAME
is the 44-character name of the base data set for which quiesce processing has been completed by this CICS.
QUIESCE_TOKEN
is the token which was supplied by SMSVSAM when it drove the quiesce exit for the original quiesce request, and which must be returned on the IDAQUIES QUICMP.

Output parameters

RESPONSE
is DFHFCQI’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
EXCEPTION
IOERR
SERVER_FAILURE
DISASTER
ABEND
DISASTER_PERCOLATION

FCQR RECEIVE_QUIESCES Function

This function consists of a forever loop around a dispatcher wait on an ECB. It receives work from the CICS RLS quiesce exit DFHFCQX whenever SMSVSAM requires CICS to perform processing for a quiesce request. DFHFCQX queues the request to DFHFCQR by adding an FC Quiesce Receive Element (FCQRE) to a chain anchored in file control static storage, and posting the ECB associated with the chain, also in FC static.

The posting of the ECB wakes the CFQR transaction, which executes the code in DFHFCQR. The FCQREs on the chain are processed, and DFHFCQU is called with function PROCESS_QUIESCE to perform the actual work. The ECB might also be posted to inform DFHFCQR that CICS is terminating. When DFHFCQU has finished processing, DFHFCQR unchains and frees the FCQRE.

Input parameters

None.

Output parameters

RESPONSE
is DFHFCQR’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
PROCESS_QUIESCE_ERROR
DISASTER_PERCOLATION

FCQS SEND_QUIESCES Function

This function consists of a forever loop around a dispatcher wait on a list of ECBs. Work is received from tasks that wish to send a quiesce request to SMSVSAM. Such tasks call DFHFCQI with function INITIATE_QUIESCE, which queues the request to DFHFCQS by adding an FC Quiesce Send Element (FCQSE) to the chain anchored in file control static storage, and posting an ECB associated with the chain, also in FC static.

When the ECB is posted, it wakes the CFQS transaction, which executes the code in DFHFCQS. The FCQSEs on the chain are processed, and DFHFCCA is called with function QUIESCE_REQUEST to issue the appropriate flavor of IDAQUIES macro to SMSVSAM. This is an asynchronous operation, and SMSVSAM returns the address of an ECB that will be posted when the IDAQUIES completes. This is saved in the FCQSE.

DFHFCQS then goes back into its dispatcher wait. It is actually waiting on a list of ECBs, the ECB for the chain plus an ECB for each IDAQUIES request. It wakes and processes the chain whenever one of these ECBs is posted. The wait also specifies a timeout interval, so that IDAQUIES requests that hang can be detected. When DFHFCQS wakes up, this can mean that: there is new work on the chain, or a quiesce request has completed, or a quiesce request timed out, or CICS is terminating. When a quiesce request has completed or timed out, DFHFCQS will resume the initiating task if it is waiting, after issuing appropriate messages and invoking global user exit XFCQUIS if active.

Input parameters

None.

Output parameters

RESPONSE
is DFHFCQS’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is DISASTER. Possible values are:
RESPONSE Possible REASON values
DISASTER
ABEND
TIMEOUT_CANCEL_ERROR
DISASTER_PERCOLATION

FCQU PROCESS_QUIESCE Function

DFHFCQU PROCESS_QUIESCE is called whenever a quiesce request is received from VSAM RLS. The quiesce exit DFHFCQX queues requests to the CFQR system transaction (DFHFCQR), which calls DFHFCQU to process each one in turn. The PROCESS_QUIESCE function is also called to implement a non-RLS variant of QUIESCE called NON_RLS_CLOSE. This is for non-RLS files, is only used internally by CICS, and does not run under the CFQR system transaction. Each quiesce request type is processed in a different way by DFHFCQU.

QUIESCE
corresponds to an SMSVSAM QUICLOSE. All files open against the data set are closed, the file state of each file is set to unenabled but with a flag that says re-enable on QUIOPEN, and a QUICMP is issued for the QUICLOSE back to VSAM RLS to indicate our QUICLOSE processing is complete. The immediate option on the DFHFCQU call governs how file closes are to be performed. If NO or omitted then closes will occur when all UOWs using the data set have completed normally. If YES then all such UOWs will be force purged to speed things up.
UNQUIESCE
corresponds to an SMSVSAM QUIOPEN. All files associated with the data set are checked to see if the file state requires resetting back to enabled, because it had been set unenabled by a QUICLOSE.
NONBWO_START
corresponds to an SMSVSAM QUICOPY. CICS prepares for a non-BWO backup of the data set by preventing new units of work from updating the data set, allowing existing UOWs to finish updating the data set, and then issuing a QUICMP for the QUICOPY back to SMSVSAM to indicate that QUICOPY processing is complete. The files involved are not closed.
NONBWO_END
corresponds to an SMSVSAM QUICEND. All files associated with the data set are checked to see if the file state requires resetting to enabled because it had been set unenabled by an OPEN failure, and a set of ’tie up records’ are written for the data set.
BWO
corresponds to an SMSVSAM QUIBWO. CICS prepares for a BWO backup of the data set by writing a set of ’tie up records’ allowing existing units of work to finish updating the data set, and then issuing a QUICMP for the QUIBWO back to SMSVSAM to indicate that QUIBWO processing is complete. The files involved are not closed, nor are updates prevented.
BWO_END
corresponds to an SMSVSAM QUIBEND. The only processing involved is to stop an existing BWO quiesce if one is in progress.
LOST_LOCKS_RECOVERED
corresponds to an SMSVSAM QUILLRC. It notifies CICS that lost locks recovery has been completed for the data set throughout the sysplex. DFHFCRR is called with function LOST_LOCKS_RECOVERED to process the availability of the data set.
FORWARD_RECOVERY_COMPLETE
corresponds to an SMSVSAM QUIFRC. It notifies CICS that forward recovery has been completed for the data set. DFHFCRR is called with function RESOURCE_AVAILABLE to process the availability of the data set.
CACHE_AVAILABLE
corresponds to an SMSVSAM QUICA. It notifies CICS that a previously failed cache structure is now available. DFHFCRR is called with function RESOURCE_AVAILABLE to process the availability of the cache.
NON_RLS_CLOSE
processes a non-RLS variant of type CLOSE called NON_RLS_CLOSE. All ACBs open against the specified non-RLS data set are closed.

Some of the requests cause global user exit XFCVSDS to be invoked if active and a DSNB exists for the data set, and XFCVSDS can suppress certain of the requests if desired. Suppression causes the quiesce request to be cancelled throughout the sysplex (by issuing the inverse quiesce request).

The types of quiesce that DFHFCQU can receive fall into two ’completion’ categories.

  1. Those for which VSAM does not require completion notification. For these no IDAQUIES QUICMP is issued. The successful return of the quiesce exit DFHFCQX to VSAM is sufficient. The requests in this category are:
    UNQUIESCE, NONBWO_END, BWO_END, CACHE_AVAILABLE,
    LOCKS_RECOVERY_COMPLETE, FORWARD_RECOVERY_COMPLETE.
  2. Those for which VSAM requires completion notification because CICS must complete some critical processing. For these an IDAQUIES QUICMP must be issued when CICS processing is complete. The requests in this category are:
    QUIESCE, NONBWO_START, BWO_START.

Input parameters

QUIESCE_TYPE
indicates the type of quiesce being requested. It can have any of these values:
QUIESCE|UNQUIESCE|NONBWO_START|NONBWO_END|BWO_START|
BWO_END|LOCKS_RECOVERY_COMPLETE|
FORWARD_RECOVERY_COMPLETE|CACHE_AVAILABLE|
NON_RLS_CLOSE
DSNAME|CACHE_NAME
either specifies the 44-character name of the data set to which the quiesce request applies, or (when the quiesce_type is CACHE_AVAILABLE) the 16-character name of the cache structure which has become available.
[IMMEDIATE]
applies when the quiesce_type is QUIESCE or NON_RLS_CLOSE, and indicates whether units of work which have updated the data set will be forced to complete immediately, or whether the request will wait for such units of work to complete naturally. It can have either of these values:
YES|NO
[CONCURRENT]
applies when the quiesce_type is NONBWO_START or BWO_START, and indicates whether the concurrent copy technique is being used. It is purely informational, and has no effect on the processing. It can have either of these values:
YES|NO
[QUIESCE_TOKEN]
is a token which is supplied by SMSVSAM when certain quiesce requests are initiated, and must be passed back when the quiesce complete is issued.

Output parameters

RESPONSE
is DFHFCQU’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is INVALID, EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
INVALID INVALID_QUIESCE_TYPE
EXCEPTION DSNB_NOT_FOUND
DISASTER
ABEND
DISASTER_PERCOLATION
DFHFCRR_ERROR
DFHFCQI_ERROR
DFHFCFS_ERROR
DFHTM_FAILURE

FCRR RESTART_RLS Function

This function performs a restart of the RLS component of file control. The exact processing depends on the type of restart being performed.

COLD and INITIAL

The RLS control ACB is registered, and RLS is cold started, both via calls to DFHFCCA.

WARM and EMERGENCY

The RLS control ACB is registered, and recovery information is inquired upon from SMSVSAM, both via calls to DFHFCCA. If the recovery information indicates that there are data sets in lost locks status, then the corresponding DSNBs are marked as being lost locks, and preparation for lost locks recovery is carried out. Any orphan locks are eliminated.

DYNAMIC

This type of restart occurs when a new instance of the SMSVSAM server becomes available following a previous server failure.

Having waited for file control restart to complete if it was still in progress, and for any in-progress dynamic RLS restart to complete, RLS access is drained if this has not already been done, the control ACB is registered, and recovery information is inquired upon from SMSVSAM, all three via calls to DFHFCCA. If the recovery information indicates that there are data sets in lost locks status, then the corresponding DSNBs are marked as being lost locks, and preparation for lost locks recovery is carried out. Any orphan locks are eliminated. The CICS recovery manager is called to unshunt any units of work that are backout-failed due to the SMSVSAM server failure or a general file backout failure, and any units of work that are commit-failed due to the SMSVSAM server failure.

Input parameters

TYPE_OF_RESTART
indicates the type of RLS restart being performed, and can have any of these values:
COLD|WARM|EMERGENCY|DYNAMIC

Output parameters

RESPONSE
is DFHFCRR’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is INVALID, EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
INVALID
INVALID_FUNCTION
INVALID_RESTART_TYPE
EXCEPTION
REGISTER_CTL_ACB_FAILED
COLD_START_RLS_FAILED
DRAIN_RLS_FAILED
LOST_LOCKS_INFO_LOST
INQUIRE_RECOVERY_FAILED
LOST_LOCKS_COMPLETE_FAILED
ORPHAN_RELEASE_FAILED
DISASTER
DSSR_FAILED
TM_LOCATE_FAILED
TM_UNLOCK_FAILED
ABEND
DISASTER_PERCOLATION

FCRR RESOURCE_AVAILABLE function

This function causes the CICS recovery manager to be notified of the availability of the specified resource. When the resource_type is DSET, an RMRE AVAIL call is issued for the specified data set. When the resource_type is CACHE, an RMRE avail call is issued for every data set that has outstanding work shunted due either to a cache failure or to a general file backout failure. When the resource_type is OTHER, an RMRE AVAIL call is issued for the specified resource.

Input parameters

RESOURCE_TYPE
is the type of resource which has become available, and can have any of these values:
DSET|CACHE|OTHER
RESOURCE_NAME
is the 44-character field containing the name of the resource which has become available.
RESOURCE_NAME_LENGTH
is a halfword containing the actual length of the resource name.

Output parameters

RESPONSE
is DFHFCRR’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is INVALID or DISASTER. Possible values are:
RESPONSE Possible REASON values
INVALID
INVALID_FUNCTION
INVALID_RESOURCE_TYPE
DISASTER
ABEND
DISASTER_PERCOLATION

FCRR LOST_LOCKS_RECOVERED function

This function is called when lost locks recovery for a data set has been completed by all CICS regions that were sharing it, and causes the flag in the DSNB which indicates that the data set is in lost locks state to be cleared.

Input parameters

RESOURCE_NAME
is the 44-character field containing the name of the resource (data set) for which lost locks recovery has been completed.

Output parameters

RESPONSE
is DFHFCRR’s response to the call. It can have any of these values:
OK|EXCEPTION|DISASTER|INVALID|KERNERROR|PURGED
[REASON]
is returned when RESPONSE is INVALID, EXCEPTION or DISASTER. Possible values are:
RESPONSE Possible REASON values
INVALID INVALID_FUNCTION
EXCEPTION SPHERE_UNKNOWN
DISASTER
TM_LOCATE_FAILED
TM_UNLOCK_FAILED
ABEND
DISASTER_PERCOLATION
[[ Contents Previous Page | Next Page Index ]]