Exit XFCFRIN

Exit XFCFRIN is invoked before the execution of a file control request.

The request can have originated from:
  • The execution of an application request to process a user file
  • The receipt of a function-shipped request
  • An internal CICS® request to process a system file.
Exit-specific parameters
UEPTRANID
Address of the 4-byte transaction ID.
UEPUSER
Address of the 8-byte user ID.
UEPTERM
Zero, or the address of the 4-byte terminal ID. If no address is returned, this could mean that this request has been function shipped over an IPIC connection.
UEPPROG
Address of the 8-byte application program name.
UEP_FC_FUNCTION
Address of a byte containing the function. The FCFR functions are derived from those available through the EXEC CICS interface, where certain request options (SET, INTO, UPDATE) have been included in the function values. For example, UEP_FC_FUN_DELETE is derived from EXEC CICS DELETE with the RIDFLD option specified; UEP_FC_FUN_REWRITE_DELETE is derived from EXEC CICS DELETE without RIDFLD. The possible values are:
  • UEP_FC_FUN_READ_INTO
  • UEP_FC_FUN_READ_SET
  • UEP_FC_FUN_READ_UPDATE_INTO
  • UEP_FC_FUN_READ_UPDATE_SET
  • UEP_FC_FUN_WRITE
  • UEP_FC_FUN_REWRITE
  • UEP_FC_FUN_REWRITE_DELETE
  • UEP_FC_FUN_DELETE
  • UEP_FC_FUN_UNLOCK
  • UEP_FC_FUN_START_BROWSE
  • UEP_FC_FUN_READ_NEXT_INTO
  • UEP_FC_FUN_READ_NEXT_SET
  • UEP_FC_FUN_READ_PREVIOUS_INTO
  • UEP_FC_FUN_READ_PREVIOUS_SET
  • UEP_FC_FUN_READ_NEXT_UPDATE_INTO
  • UEP_FC_FUN_READ_NEXT_UPDATE_SET
  • UEP_FC_FUN_READ_PREVIOUS_UPDATE_INTO
  • UEP_FC_FUN_READ_PREVIOUS_UPDATE_SET
  • UEP_FC_FUN_RESET_BROWSE
  • UEP_FC_FUN_END_BROWSE
UEPTSTOK
Address of a 4-byte token that is valid throughout the life of a task. See Using the task token UEPTSTOK.
UEP_FC_FILE_NAME
Address of an 8-byte modifiable field containing the filename.
UEP_FC_BUFFER_P
Address of a fullword containing the address of the buffer provided by the originator of the request, in which the (output) record is to be returned on completion of a READ, READ NEXT, or READ PREV request with the INTO option.
UEP_FC_BUFFER_L
Address of a fullword containing (for READ, READ NEXT, and READ PREV requests) the value of the LENGTH of the buffer into which the record is to be read.
UEP_FC_RECORD_P
Address of one of the following:
  • If the request is a READ, READ NEXT, or READ PREV with the SET option, a fullword in which is to be returned the address (output) of a buffer, into which the record will be placed. The buffer itself is supplied either by CICS file control or, if the exit program bypasses file control, by the exit program.
  • If the request is WRITE or REWRITE, a fullword containing the address of the record to be written.
UEP_FC_RECORD_L
Address of a fullword containing (for READ, WRITE, REWRITE, READ NEXT, and READ PREV requests) the value of LENGTH.
For all READ, READ NEXT, or READ PREV requests, this is an output field, in which the actual length of the record read is placed on return.
Warning: For requests that specify INTO, do not change the value of LENGTH to a value greater than the value specified by the UEP_FC_BUFFER_L field. To do so could cause a storage overlay in the application.

For a WRITE or REWRITE, this is an optional field which, if present, contains the length of the record to be written. If the field is not specified, the fullword contains binary zeroes. In this case, to modify the record length for a remote file use UEP_FC_M_RECORD_L instead.

See also the description of the UEP_FC_SYSID parameter.

UEP_FC_MAX_RECORD_L
Address of a fullword containing the (output) maximum record length of the file. (CICS function shipping uses this value to update the file's entry in the remote file control table.)
UEP_FC_RECORD_ID_P
Address of a fullword containing the address of the RIDFLD (record identifier) value. For a discussion of when the record identifier is an input or an output field, see Table 1.
UEP_FC_RECORD_ID_L
Address of the halfword value of KEYLENGTH, which is the (possibly partial) length of the record identifier.

KEYLENGTH is an optional input parameter on READ, WRITE, DELETE, START BR, READ NEXT, READ PREV, and RESET BR requests. If the field is not specified, the halfword contains binary zeroes. In this case, to modify the key length for a remote file use UEP_FC_M_RECORD_ID_L instead.

See also the description of the UEP_FC_SYSID parameter.

UEP_FC_FULL_RECORD_ID_L
Address of the halfword value of the full length of the record identifier.

The full length of the record identifier is returned as a mandatory output field on READ NEXT and READ PREV requests. The value is used by CICS function shipping.

UEP_FC_RECORD_ID_TYPE
Address of a byte containing (for READ, WRITE, DELETE, START BR, READ NEXT, READ PREV, and RESET BR requests) the RIDFLD type. On input to the exit, this parameter will be set to one of:
UEP_FC_KEY
VSAM KSDS or AIX® PATH access
UEP_FC_RBA
VSAM ESDS or KSDS via RBA access
UEP_FC_RRN
VSAM RRDS access
UEP_FC_DEBKEY
BDAM deblocking by key (READ, DELETE, START BR, and RESET BR requests only)
UEP_FC_DEBREC
BDAM deblocking by relative record (READ, DELETE, START BR, and RESET BR requests only)
UEP_FC_XRBA
VSAM extended ESDS access
UEP_FC_REQID
Address (for START BR, READ NEXT, READ PREV, RESET BR, and END BR requests) of the halfword value of REQID.
UEP_FC_NUMREC
Address of the fullword value of NUMREC (output), in which (if the request is DELETE with RIDFLD) the number of records that have been deleted is returned.
UEP_FC_KEY_COMPARISON
Address of a byte containing (for READ, START BR, and RESET BR requests) the key comparison setting. On input to the exit, this parameter will be set to one of:
UEP_FC_EQUAL
Key-equal-to comparison is to be used.
UEP_FC_GTEQ
Key-greater-than-or-equal-to comparison is to be used.
UEP_FC_GENERIC
Address of a byte containing (for READ, DELETE, START BR, and RESET BR requests) the generic key setting. On input to the exit, this parameter will be set to one of:
UEP_FC_GENERIC_KEY
Generic key is to be used for key search.
UEP_FC_FULL_KEY
Full key is to be used for key search.
UEP_FC_MASS_INSERT
Address of a byte containing (for WRITE requests) the mass insert setting. On input to the exit, this parameter will be set to one of:
UEP_FC_SEQUENTIAL_WRITE
Records are to be written in sequential mode.
UEP_FC_DIRECT_WRITE
Records are to be written in direct mode.
UEP_FC_READ_INTEGRITY
Address of a byte containing (for non-update READ, READ NEXT, and READ PREV requests) the read integrity setting. (In current versions of CICS, this setting applies only to VSAM RLS.) On input to the exit, this parameter will be set to one of:
UEP_FC_CR
Consistent read integrity is to be used.
UEP_FC_FCT_VALUE
Read integrity is according to the setting in the FILE definition.
UEP_FC_NRI
The record is to be read with no read integrity.
UEP_FC_RR
Repeatable read integrity is to be used.
UEP_FC_TOKEN
Address of a fullword containing the value of TOKEN.

If the request is READ, READ NEXT, or READ PREV with update, and the address is not null, the area is an output field in which the token is to be returned.

If the request is REWRITE, DELETE without RIDFLD, or UNLOCK, the area is an input field.

UEP_FC_SYSID
Address of a 4-byte area that is to contain the SYSID identifying the remote region. On input to the exit, the area contains either:
  • The value of the SYSID option of the API call, or
  • Blanks (if SYSID was not specified).

To redirect the request to a different region, the exit program must place the SYSID of the target region in this output area.

If this parameter is set by the exit program, the request is function-shipped by file control without any reference to the file's attributes. If the key length has not been included on the request, the exit program must establish its value by setting the UEP_FC_RECORD_ID_L parameter.

Similarly, if the request is WRITE or REWRITE, and the record length has not been specified on the request, the exit program must establish its value by setting the UEP_FC_RECORD_L parameter.

UEP_FC_LENGTH_ERROR_CODE
Address of a 1-byte output area containing the length error code to be returned after a request has completed. The possible values are:
  • UEP_FC_LENGTH_OK
  • UEP_FC_BUFFER_LEN_TOO_SMALL
  • UEP_FC_RECORD_LEN_TOO_LARGE
  • UEP_FC_BUFFER_LEN_NOT_FILE_LEN
  • UEP_FC_RECORD_LEN_NOT_FILE_LEN
UEP_FC_DUPLICATE_KEY_CODE
Address of a 1-byte output area indicating whether the request found more than one record for the supplied key. The possible values are:
  • UEP_FC_DUPLICATE KEY
  • UEP_FC_NOT_DUPLICATE KEY
UEP_FC_ACCMETH_RETURN_CODE
Address of a 4-byte output area in which access-method-dependent information is to be returned when either of the responses UEP_FC_REASON_ACCMETH_REQUEST_ERROR or UEP_FC_REASON_IO_ERROR is returned.

The returned value is placed in bytes 2–5 of the EIBRCODE.

UEP_FC_RESPONSE
Address of a 1-byte output area containing the response after a request has completed:
UEP_FC_RESPONSE_OK
Processing has completed without errors.
UEP_FC_RESPONSE_EXCEPTION
Processing has completed with an error condition. The reason is set in UEP_FC_REASON.
UEP_FC_RESPONSE_DISASTER
An error has occurred which prevents processing from completing. Typically, this is as a result of a DISASTER response from an XPI function call, or corruption of data addressed from UEPGAA or UEPTSTOK.

If you set this response, the caller of file control will assume that first-failure data capture has been performed. If you are percolating a DISASTER response from an XPI request, first-failure data capture will have been performed already; if not, you should attempt to capture sufficient information to successfully diagnose the error. The DFHDUDUX SYSTEM_DUMP XPI function may be suitable for this purpose.

UEP_FC_RESPONSE_INVALID
The exit program was invoked with an invalid parameter list, indicating a CICS internal logic error. Note that an invalid parameter list that indicates an application error should give an EXCEPTION response.
UEP_FC_RESPONSE_PURGED
An XPI function call has received a PURGED response. Setting this response is equivalent to setting the UERCPURG return code, except that any changes to the parameter list are honored.
UEP_FC_REASON
Address of a 1-byte output area containing, after a request has completed with an EXCEPTION response, the reason. The possible reasons are:
  • UEP_FC_REASON_ACCMETH_REQUEST_ERROR
  • UEP_FC_REASON_DELETE_AFTER_READ_UPDATE
  • UEP_FC_REASON_DELETE_BEFORE_READ_UPDATE
  • UEP_FC_REASON_DUPLICATE_READ_UPDATE
  • UEP_FC_REASON_DUPLICATE_RECORD
  • UEP_FC_REASON_DUPLICATE_REQID
  • UEP_FC_REASON_END_OF_FILE
  • UEP_FC_REASON_FILE_DISABLED
  • UEP_FC_REASON_FILE_NOT_OPEN
  • UEP_FC_REASON_FILE_NOT_FOUND
  • UEP_FC_REASON_FULL_KEY_WRONG_LENGTH
  • UEP_FC_REASON_GENERIC_DELETE_NOT_KSDS
  • UEP_FC_REASON_GENERIC_KEY_TOO_LONG
  • UEP_FC_REASON_ILLEGAL_KEY_TYPE_CHANGE
  • UEP_FC_REASON_INSUFFICIENT_SPACE
  • UEP_FC_REASON_INVALID_UPDATE_TOKEN
  • UEP_FC_REASON_IO_ERROR
  • UEP_FC_REASON_KEY_LENGTH_NEGATIVE
  • UEP_FC_REASON_KSDS_AND_XRBA
  • UEP_FC_REASON_NO_VARIABLE_LENGTH
  • UEP_FC_REASON_NOTAUTH
  • UEP_FC_REASON_NOT_EXTENDED
  • UEP_FC_REASON_READPREV_IN_GENERIC_BROWSE
  • UEP_FC_REASON_RECORD_NOT_FOUND
  • UEP_FC_REASON_REWRITE_BEFORE_READ_UPDATE
  • UEP_FC_REASON_RIDFLD_KEY_NOT_RECORD_KEY
  • UEP_FC_REASON_UNKNOWN_REQID_ENDBR
  • UEP_FC_REASON_UNKNOWN_REQID_READNEXT
  • UEP_FC_REASON_UNKNOWN_REQID_READPREV
  • UEP_FC_REASON_UNKNOWN_REQID_RESETBR
UEP_FC_EXIT_TOKEN
Address of a 4-byte token to be passed to XFCFROUT. This allows you, for example, to pass a work area to exit XFCFROUT.
UEP_FC_M_RECORD_L
Address of a fullword containing the modified record length field. You can use this to change the LENGTH, for remote files only, when the LENGTH field is not specified on the API call. If the LENGTH field is specified on the API call, to change the LENGTH use UEP_FC_RECORD_L instead, because changing the value at the address stored by UEP_FC_M_RECORD_L has no effect.
UEP_FC_M_RECORD_ID_L
Address of a halfword containing the modified key length field. You can use this to change the KEYLENGTH, for remote files only, when the KEYLENGTH field is not specified on the API call. If the KEYLENGTH field is specified, to change the KEYLENGTH use UEP_FC_RECORD_ID_L instead, because changing the value at the address stored by UEP_FC_M_RECORD_ID_L has no effect.
Return codes
UERCNORM
Continue processing.
UERCBYP
Bypass CICS processing of this request. If the exit program has been invoked for a function-shipped request, the mirror transaction is permitted to terminate.
UERCBYPL
Bypass CICS processing of this request. If the exit program has been invoked for a function-shipped request, the mirror transaction must not terminate.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.
API and SPI calls
None can be used.