gtpc2m8c | C/C++ Language Support User's Guide |
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:
- Correct the CF locking restart token.
- 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:
- Submit a new operation (such as LEMIC_LOCATELOCK,
LEMIC_LOCATEMOD, LEMIC_READ, or
LEMIC_READUSER) that will return a valid list number.
- Submit the original operation again using a valid list number.
- LN_DNX
- The list number does not exist.
Do the following:
- Submit a new operation (such as LEMIC_LOCATELOCK,
LEMIC_LOCATEMOD, LEMIC_READ, or
LEMIC_READUSER) that will return a valid list number.
- 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
- A waitc call is issued implicitly with this function.
- Attention: Using this function can cause corruption of
the locking control information on the CF. This corruption can lead to
errors that cannot be predicted and online database integrity problems.
- The calling program returns storage when the storage is no longer
needed.
- If the specified CF or CF locking structure is not valid, a system error
is issued.
- See the c$cflp.h header to determine the required
input fields and the information included on return in the ICFLP_DATA control
area.
- The reply code for individual requests must be checked to determine the
success or failure of that specific request.
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.