Retrieve Lock Information (QWCRLCKI) API

The Retrieve Lock Information (QWCRLCKI) API generates a list of information about lock holders of the item specified.

Authorities and Locks

Object Library Authority

*EXECUTE

Object Library ASP Device Authority

*EXECUTE

Note: If the user does not have *EXECUTE authority to the object's library and *EXECUTE authority to the object library's ASP device, the user must have *JOBCTL authority or GUI thread control authority.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold. For example, this may mean that the number of lock information entries returned in the receiver variable doesn't match the value in the number of lock information entries available.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable provided. The length of the receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of the receiver variable specified is larger then the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.

Format name

INPUT; CHAR(8)

The name of the format used to retrieve lock information. You can specify this format:

LCKI0100

Lock Information Format. See LCKI0100 Format for more information.

Object identification

INPUT; CHAR(*)

The information that is used to identify the entity that may be locked. See Format of Object Identification for more information.

Object identification format

INPUT; CHAR(8)

The format of the entity identification information. Possible format names are:

LOBJ0100	Object name. See LOBJ0100 Format for more information on this format.
LOBJ0200	Object lock handle. See LOBJ0200 Format for more information on this format.

Number of key fields to be returned

INPUT; BINARY(4)

The number of key fields to be returned in the LCKI0100 format. If the lock holder type returned is a lock space then the values returned in the key fields will be blank or zero.

Key of fields to be returned.

INPUT; ARRAY(*) of BINARY(4)

The list of fields returned in the LCKI0100 format. For a list of valid fields, see Valid Keys.

Filters

INPUT;CHAR(*)

Filters used for the lock information that is returned. See the Filter Format for further information.

Filter format

INPUT; CHAR(8)

The format of the lock filter used on the returned data. The possible format name is:

LKFL0100

See LKFL0100 Format for details on the filters contained in this format.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Format of Object Identification

The formats for the object identification are specified.

LOBJ0100 Format

An external object is specified in this format. See the field descriptions for restrictions that may exist.

Field Descriptions

Member name. Lock information is retrieved on the specified member of a database file. This is valid only when a database file has been specified for object parameters. For other than database files, use *NONE. Special values used are:

Object identification size. The amount of data provided for the LOBJ0100 format. This field must be set to 64.

Object library ASP name specified. The name of the auxiliary storage pool (ASP) device that contains the object's library. This parameter must be * if the library portion of the qualified object name is *CURLIB or *LIBL. Special values used are:

Object library name specified. The name of the library where the object is located. You can use these special values for the library name:

Object name specified. The name of the external i5/OS object whose lock information entries are to be placed in the list.

Object type specified. The type of i5/OS object. For a list of all the available external i5/OS object types, see the Control Language (CL) topic.

Record lock indicator. The indicator that controls the retrieval of record locks that may exist if the object specified is a file and member. If the object specified is not a database file and member or the special value of *ALL is specified for member, then the value 0 must be used for this field. One of the following values are required for this field.

Relative record number. The record number in the specified database file and member for which lock information is to be returned. If the object specified is not a database file and member, the value 0 must be used for this field. The following special value is allowed:

Reserved. This field must be set to hexadecimal zeros.

LOBJ0200 Format

This format is used to find locks where a handle was passed that has been returned in a previous lock call to the Retrieve Job Locks (QWCRJBLK) API. This call must have been made in the same thread for the handle to be valid. The following fields are used if LOBJ0200 input format is specified.

Field Descriptions

Object lock handle. A value that identifies the object that is stored from a previous API call. The handle is a temporary value. A storage limitation will allow a thread to create up to 1 million valid handles. Once the storage limit has been reached the oldest handle information will be overwritten. This can cause a handle to no longer be valid.

Object identification size. The amount of data provided for the LOBJ0200 format. This field must be set to 68.

Filter Format

The format of the lock filter used on the returned lock information.

LKFL0100 Format

Field Descriptions

Filter lock holder type. Filters information that is returned so it contains only information about a type of lock holder.

Filter lock scope. Filters information that is returned so it contains only information about locks that have a certain lock scope.

Filter lock state. Filters information that is returned so it contains only information about locks that have a certain lock state.

Filter lock status. Filters information that is returned so it contains only information about locks that have a certain lock status.

Filter member lock type. Filters information that is returned so it contains only information about locks that have a certain member lock type.

Filter size. The size of the filter information passed. Valid values are:

Lock Information Format

The formats for the lock information.

LCKI0100 Format

Header Section

Lock Information Entry Format

Key information format

Field Descriptions

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned. Only complete lock information entries are returned.

Data. The data returned for the key field.

Displacement from lock information to holder identification. The byte displacement from the start of the current lock information entry to the holder identification.

Displacement from lock information to key information. The byte displacement from the start of the current lock information entry to the key information requested.

Extended object attribute returned. The extended attribute of the object for which the list of locks is returned, such as a program or a file type. Extended attributes further describe the object. For example, an object type of *FILE may have an extended object attribute of PHY (physical file), LGL (logical file), DSP (display file), SAV (save file), and so forth.

Extended object name returned. The name of the object for which the lock information entries are placed in the list. This field will be blank if the name is for an internal system object or an internal system object space location, and the user does not have *JOBCTL special authority.

Holder identification. This field contains information about the lock holder. This can be either a qualified job name as described in Job Format specifier or a lock space identifier as described in Lock Space Format specifier.

Holder type. This value is set to indicate what type of holder is holding or is waiting to hold a lock on the specified object.

Key field. The field returned. See Valid Keys for the list of valid keys.

Length of data. The length of the data returned for the field.

Length of field information returned. The total length of information returned for this field. This value is used to increment to the next field in the list.

Length of lock information entry. The length of a lock information entry. This value is used to increment to the next entry.

Lock count. The number of identical locks.

Lock request handle. This value is used to identify a handle to lock request process information. Using the Retrieve Lock Request Information (QWCRLRQI) API and passing in this handle you can retrieve additional information about the program that requested this lock. See QWCRLRQI API for additional information

Lock scope. The scope of the lock. The possible values are:

Lock space identifier. This field contains a value only when the lock scope value is lock space scope and the lock is being waited on by a thread. This field will then contain the lock space ID value for which the lock is being waited on.

Lock state. The lock condition for the lock request. The possible values are:

Lock status. The status of the lock. The lock may be a single request or part of a multiple lock request for which some other object specified in the request has been identified as unavailable. The possible values are:

Member lock type. If the lock is on a member then this field indicates the type of member lock, otherwise it will be blank. The possible values are:

Member name returned. The name of the member that lock information is being returned for. Blanks will be returned if the object is not a member of a database file.

Number of keys returned. The number of keys that were returned.

Number of lock information entries available. The number of lock information entries that were found.

Number of lock information entries returned. The number of lock information entries that are returned.

Object ASP name returned. The name of the ASP in which the object is located. The following special values may also be returned:

Object ASP number returned. The numeric identifier of the ASP containing the locked object. The following values may be returned:

Object library ASP name returned. The name of the ASP in which the object's library is located. The following special values may also be returned:

Object library ASP number returned. The numeric identifier of the ASP device containing the object's library. The following special values may also be returned:

Object library name returned. The name of the library that contains the object whose lock information entries are placed in the list.

Object type returned. The type of object for which locks are retrieved. For a list of all the available external i5/OS object types, see External object types in the Control Language (CL) topic. For a list of all internal system object types, see Internal object types.

Offset to list of lock information entries. The offset in bytes from the beginning of the receiver variable to the first entry.

Relative record number. The relative record number for which record lock information is being returned. If this is not a record lock then this value will be zero.

Reserved. An unused field.

Type of data. The type of data returned.

Type of entity. This is a value that will identify the type of entity for which the lock information is returned. The following values may be returned:

Valid Keys

The following table contains a list of valid keys.

See Field Descriptions in the Work Management API Attributes Descriptions for the descriptions of the valid key fields. All fields are scoped to the job unless specifically noted. See Considerations for Attribute Scope and Thread Safety in the Work Management API Attributes Descriptions for complete information.

Note: If the holder type is a lock space holder then character fields will contain blanks and the binary fields will be zero.

Holder ID

This field contains an identifier for the job or lock space that is holding or waiting to hold a lock on the specified object or space location.

Job Format

For a job, the returned data in this field will be in this format.

Field Descriptions

Holder identification size. The size of the holder identification.

Job name. The simple job name of the job that issued the lock request. If the job name is MACHINE and the job user name entry is blank, the lock is held by an internal machine process.

Job number. The system assigned job number of the job that issued the lock request. This value will be blank if the job name is MACHINE and the user name entry is blank.

Thread handle. A value which addresses a particular thread within a job holding a thread scope lock or the thread waiting for a lock, otherwise this is zero. While the thread identifier uniquely identifies the thread within the job, the thread handle can improve performance when referencing the thread.

Thread identifier. A value which uniquely identifies a thread within a job holding a thread scope lock or the thread waiting for a lock, otherwise this is zero.

Reserved. This field will be blank.

User name. The user name under which the job that issued the lock request is started. If the job name is MACHINE and the lock is held by an internal machine process then this field will be blank.

Lock Space Format

For a lock space the returned data in this field will be in this format.

Field Descriptions

Holder identification size. The size of the holder identification.

Holder lock space identifier. The identifier of the lock space that holds a lock.

Reserved. A blank field.

Error Messages