gtpc2m8cC/C++ Language Support User's Guide

tpf_lemic -Lock Entry Management Interface

This function issues one or more service requests to a coupling facility (CF) that is being used as an external locking facility (XLF).

Format

#include <c$cflp.h>
int      tpf_lemic(enum lemic_req req,
                   struct icflp *cflp_ptr);

req
A constant value representing the type of service request being performed:

LEMIC_CLEARUSER
Clears all locks, any held lock requests, or any queued lock requests for a particular user from a CF.

LEMIC_DELETE
Removes one or more held locks from a CF.

LEMIC_DELETESET
Removes a set of locks associated with a particular CF list structure from a CF.

LEMIC_LOCATELOCK
Locates a CF and list number where each lock resides for one or more lock names.

LEMIC_LOCATEMOD
Locates a CF and the starting and ending list numbers used for locking by a particular module.

LEMIC_MANAGE
Sends one or more set, release, or withdraw lock commands, in any combination, to a CF.

LEMIC_MONITOR
Registers a user for lock granted and contention notification.

LEMIC_READ
Reads one or more locks in a CF.

LEMIC_READUSER
Reads all locks held by a particular user on a CF.

LEMIC_VERIFYCF
Verifies the connectivity between a processor and a CF.

cflp_ptr
A pointer to the block of storage that is mapped by the c$cflp.h header and must reside in a single page, and that is passed to the service routine.

Normal Return

COMPLETED_OK
The function is completed successfully and control is returned to the next sequential instruction (NSI).

Error Return

ICFLP_SYSERR
An error condition occurred in the CCCFLC service routines.

Exit the application. You can also examine the console logs to find any associated system error dumps.

If this return code is received, the ICFLP_RSC field contains one of the following response codes:

TIMEOUT
The requested operation was not able to be completed because a timeout occurred.

Submit the operation again using the CF locking restart token provided in ICFLP_RT.

INV_RESTOK
A program error occurred because a CF locking restart token that is not valid was provided for an operation that was resubmitted.

Do the following:

  1. Correct the CF locking restart token.
  2. Try the tpf_lemic function again.

DB_FILLED
The data block provided with either a LEMIC_READ or LEMIC_READUSER operation is filled and there are more locks to read.

Submit the LEMIC_READ or LEMIC_READUSER operation again using the CF locking restart token provided in ICFLP_RT and a data block that no longer contains critical data.

LN_MM
A list number mismatch occurred.

Do the following:

  1. Submit a new operation (such as LEMIC_LOCATELOCK, LEMIC_LOCATEMOD, LEMIC_READ, or LEMIC_READUSER) that will return a valid list number.
  2. Submit the original operation again using a valid list number.

LN_DNX
The list number does not exist.

Do the following:

  1. Submit a new operation (such as LEMIC_LOCATELOCK, LEMIC_LOCATEMOD, LEMIC_READ, or LEMIC_READUSER) that will return a valid list number.
  2. Submit the original operation again using a valid list number.

ICFLP_SYSERR
An error condition occurred in the CCCFLC service routines.

Exit the application. Additionally, you can examine the console logs to find any associated system error dumps.

INS_SPACE
An error occurred during a read operation because there is not enough space in the data block.

GLBL_MM
A global lock manager mismatch occurred.

Exit the application. If necessary, see your IBM service representative for more information.

LCL_MM
A lock manager mismatch occurred.

Exit the application. If necessary, see your IBM service representative for more information.

LAU_MM
A list authority mismatch error occurred.

Exit the application. If necessary, see your IBM service representative for more information.

INS_MB_SPACE
A program error occurred because there is not enough message buffer space available to read the locks in a CF or to read all locks held by a particular user on a CF.

Exit the application. If necessary, see your IBM service representative for more information.

ABNORMAL
A program error occurred because of an abnormal locking condition. Some of the set, release, or withdraw commands were not processed by a CF.

Exit the application. If necessary, see your IBM service representative for more information.

RRC_ERROR
An error occurred while processing a monitor operation.

Exit the application. If necessary, see your IBM service representative for more information.

CVCF_ERROR
The CCCFLC service routines were unable to determine the CF or the list number from the information provided with the operation.

Exit the application and review the application code to ensure the operation was set up correctly. If necessary, see your IBM service representative for more information.

CMD_SUPPR
A program error occurred because the function call was suppressed.

Exit the application and review the console logs to determine if the CF specified in the operation was added correctly to the CF locking configuration. If necessary, see your IBM service representative for more information.

CMD_TERM
A program error occurred because the function call ended.

Programming Considerations

Examples

The following example shows the setup and function call for the LEMIC_CLEARUSER operation.

cflp_ptr = getcc( D2, GETCC_TYPE+GETCC_FILL, L4, 0x00 );
 
memcpy( &cflp_ptr>icflp_ctl.icflp_id, "CFLP",
        sizeof( cflp_ptr->icflp_ctl.icflp_id ));
 
cflp_ptr->icflp_ctl.icflp_condata.icflp_cfix = cf_index;
cflp_ptr->icflp_ctl.icflp_condata.icflp_stix =
  (unsigned char)CFL_LOCKSPACE_STRUCTURE_INDEX;
cflp_ptr->icflp_ctl.icflp_condata.icflp_uid  =
  cflt_ptr->icflt_hdrc.icflt_cflgs.icflt_uid;
 
rc = tpf_lemic( LEMIC_CLEARUSER, cflp_ptr );

Related Information

None.