List Object Locks (QWCLOBJL) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Format name | Input | Char(8) |
| 3 | Qualified object name | Input | Char(20) |
| 4 | Object type | Input | Char(10) |
| 5 | Member name | Input | Char(10) |
| 6 | Error code | I/O | Char(*) |
Optional Parameter Group 1:
| 7 | Path name | Input | Char(*) |
| 8 | Path name length | Input | Binary(4) |
Optional Parameter Group 2:
| 9 | Qualified object ASP name | Input | Char(10) |
Default Public Authority: *USE
Threadsafe: No
The List Object Locks (QWCLOBJL) API generates a list of lock information about a specific object or database file member and places the list into the specified user space. An object level or member level lock may be specified. If it is a database file, you will get a lock on the member (if requested); otherwise, the lock is on the object. This API provides information similar to that provided by the Work with Object Lock (WRKOBJLCK) command.
Authorities and Locks
- User Space Authority
- *CHANGE
- User Space Library Authority
- *EXECUTE
- User Space Lock
- *EXCLRD
- ASP device
- *EXECUTE
- Object library
- *EXECUTE
A user with *JOBCTL special authority is not required to have *EXECUTE authority to either the auxiliary storage pool (ASP) device or the library containing the object.
If a path name is specified, *X authority is required for directories in the path reqardless of any special authorities the user may have.
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The name of the existing user space that is to receive the created list. The first 10 characters contain the user space name, and the second 10 characters contain the name of the library where the user space is located. You can use these special values for the library name:
*CURLIB The current library is used to locate the user space. If there is no current library, QGPL (general purpose library) is used. *LIBL The library list is used to locate the user space.
- Format name
- INPUT; CHAR(8)
The name of the format used to list object locks. You can specify this format:
OBJL0100 The content and format of the lock information being returned. For more information, see OBJL0100 Format.
- Qualified object name
- INPUT; CHAR(20)
The name of the object whose locks are to be placed in the list. The first 10 characters contain the object name, and the second 10 characters contain the name of the library where the object is located.
If you want to use a path name instead of a qualified object name, use this special value for the object name:
*OBJPATH Use the optional parameters, path name and path name length, to specify the object name. When this special value is specified, the member name field must be the special value *NONE and the Object type field must be blanks. You can use these special values for the library name:
*CURLIB The current library is used to locate the object. If there is no current library, QGPL (general purpose library) is used. *LIBL The library list is used to locate the object.
- Object type
- INPUT; CHAR(10)
The object type of operating system object for which the list of locks is returned. Specify the predefined value that identifies the object type. See the CL programming topic for more information on allowed object types. If a path name has been specified, then this field must contain blanks.
- Member name
- INPUT; CHAR(10)
This parameter is valid only when a database file has been specified in the qualified object name parameter. For other than database files, use *NONE. Possible values are a specific name or a special value:
*NONE No member locks are retrieved, but file level locks are retrieved. If the qualified object name is not a database file, use this value. If a path name is being specified for the object name, use this value. *FIRST The member locks for the first member in the named file are retrieved. *ALL Member locks for all the members in the file are retrieved.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Optional Parameter Group 1
- Path name
- INPUT; CHAR(*)
The path name of the object whose locks are to be placed in the list. Both absolute and relative path names are allowed. The patterns ? and * are not allowed. The home directory of the user is not resolved, thus a tilde (~) in the first character position is not treated as the home directory. This parameter is assumed to be represented in the coded character set identifier (CCSID) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job. The path name delimiter must be a slash (/). If a symbolic link is specified, the link is not followed.
- Path name length
- INPUT; BINARY(4)
The length of the path name, in bytes.
Optional Parameter Group 2
- Qualified object ASP name
- INPUT; CHAR(10)
The name of the ASP device where the object's library is located. This parameter must be * if the library portion of the qualified object name is *CURLIB or *LIBL. It also must be * if the qualified object name is *OBJPATH. If the object is a library and either an ASP device name or *SYSBAS is specified, the library portion of the qualified object name must be QSYS. The following special values may be specified:
* The ASPs that are currently part of the thread's library name space will be searched to locate the object. *SYSBAS The system ASP and all basic ASPs will be searched to locate the object.
Format of the Generated List
The file member list consists of:
- A user area
- A generic header
- An input parameter section
- A header section
- A list data section
For details about the user area and generic header, see User spaces. For details about the remaining items, see the following sections. For detailed descriptions of the fields in the list returned, see Field Descriptions.
When you retrieve list entry information from a user space, you must use the entry size returned in the generic header. The size of each entry may be padded at the end. If you do not use the entry size, the result may not be valid. For examples of how to process lists, see Examples: APIs and exit programs.
Input Parameter Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name specified |
| 10 | A | CHAR(10) | User space library name specified |
| 20 | 14 | CHAR(8) | Format name specified |
| 28 | 1C | CHAR(10) | Object name specified |
| 38 | 26 | CHAR(10) | Object library name specified |
| 48 | 30 | CHAR(10) | Object type specified |
| 58 | 3A | CHAR(10) | Member name specified |
| 68 | 44 | BINARY(4) | Offset to path name specified |
| 72 | 48 | BINARY(4) | Length of path name specified |
| 76 | 4C | CHAR(10) | Object library ASP name specified |
| CHAR(*) | Path name specified | ||
Header Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name used |
| 10 | A | CHAR(10) | User space library name used |
| 20 | 14 | CHAR(10) | Object name used |
| 30 | 1E | CHAR(10) | Object library name used |
| 40 | 28 | CHAR(10) | Object type returned |
| 50 | 32 | CHAR(10) | Extended object attribute returned |
| 60 | 3C | CHAR(10) | Shared file name |
| 70 | 46 | CHAR(10) | Shared file library name |
| 80 | 50 | BINARY(4) | Offset to path name used |
| 84 | 54 | BINARY(4) | Length of path name used |
| 88 | 58 | CHAR(10) | Object ASP name used |
| 98 | 62 | CHAR(10) | Object library ASP name used |
| CHAR(*) | Path name used | ||
OBJL0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Job name |
| 10 | A | CHAR(10) | Job user name |
| 20 | 14 | CHAR(6) | Job number |
| 26 | 1A | CHAR(10) | Lock state |
| 36 | 24 | BINARY(4) | Lock status |
| 40 | 28 | BINARY(4) | Lock type |
| 44 | 2C | CHAR(10) | Member name |
| 54 | 36 | CHAR(1) | Share |
| 55 | 37 | CHAR(1) | Lock scope |
| 56 | 38 | CHAR(8) | Thread identifier |
Field Descriptions
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.
Format name specified. The name of the format used to list object locks.
Job name. The simple job name of the job that issued the lock request. The following special values also may be returned:
| MACHINE | The lock is held by an internal machine process. If this value is returned, the job number and job user name will be blank. |
| *LCKSPC | The lock is attached to a lock space. If this value is returned, the job number and job user name will be blank. |
| *N | The job name cannot be determined. |
Job number. The system-assigned job number of the job that issued the lock request. The following special value also may be returned:
| *N | The job number cannot be determined. |
Job user name. The user name under which the job that issued the lock request is run. The user name is the same as the user profile name and can come from several different sources depending on the type of job. The following special value also may be returned:
| *N | The job user name cannot be determined. |
Length of path name specified. The length, in bytes, of the path name of the object that is specified on the call to the API.
Length of path name used. The length, in bytes, of the path name of the object for which the locks are placed in the list.
Lock scope. The scope of the lock. The possible values are:
| 0 | Job scope |
| 1 | Thread scope |
| 2 | Lock space scope |
Lock state. The lock condition for the lock request. The possible values are:
| *NONE | No lock exists. |
| *SHRRD | Lock shared for read. |
| *SHRUPD | Lock shared for update. |
| *SHRNUP | Lock shared no update. |
| *EXCLRD | Lock exclusive allow read. |
| *EXCL | Lock exclusive no read. |
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:
| 1 | The lock is currently held by the job or thread. |
| 2 | The job or thread is waiting for the lock (synchronous). |
| 3 | The job or thread has a lock request outstanding for the object (asynchronous). |
Lock type. The lock type to be processed. The possible values are:
| 1 | Lock on the object |
| 2 | Lock on the member control block |
| 3 | Lock on the access path used to access a member's data |
| 4 | Lock on the actual data within the member |
Member name. The name of the file member for which the lock was requested. This field is blank if not applicable to object type.
Member name specified. The member name of a database file specified on the call to the API.
Object ASP name used. The name of the ASP device that contains the object for which the locks are placed in the list. The following special value also may be returned:
| *SYSBAS | The object is located in the system ASP or a basic user ASP. |
Object library ASP name specified. The name of the ASP device that contains the object specified on the call to the API. The following special values may also be returned:
| * | The ASPs that are currently part of the thread's library name space will be searched to locate the object. |
| *SYSBAS | The object is located in the system ASP or a basic user ASP. |
Object library ASP name used. The name of the ASP device that contains the library of the object for which locks are placed in the list. The following special value may also be returned:
| *SYSBAS | The library is located in the system ASP or a basic user ASP. |
Object library name specified. The name of the library that contains the object specified on the call to the API. This field is blank if a path name was specified as the object name.
Object library name used. The name of the library that contains the object whose locks are placed in the list. This field is blank if a path name was specified as the object name.
Object name specified. The name of the object specified on the call to the API. This field will contain the special value *OBJPATH if a path name is specified.
Object name used. The name of the object for which the locks are placed in the list. This field will contain the special value *OBJPATH if a path name is specified.
Object type returned. The type of object for which locks are retrieved. This field will contain blanks if a path name is specified.
Object type specified. The type of object for which the list of locks are requested. This field will contain blanks if a path name is specified.
Offset to path name specified. The offset to the path name of the object that is specified on the call to the API.
Offset to path name used. The offset to the path name of the object for which the locks are placed in the list.
Path name specified. The path name of the object that is specified on the call to the API.
Path name used. The actual path name of the object for which the locks are placed in the list.
Share. Whether shared file member locks are associated with the file member.
| 0 | The file is not shared, the file is a physical file, or the field is not applicable to object type. |
| 1 | The file is shared. |
Shared file library name. The name of the library that contains the shared file. This field is blank if not applicable to object type or if there is no shared file. When this field has a value, it applies to all entries in the list.
Shared file name. The name of one shared file whose members are locked. This field is blank if not applicable to object type or if there is no shared file. When this field has a value, it applies to all entries in the list.
Thread identifier. The identifier of the thread that is holding a thread-scoped lock or waiting for a lock. For locks that do not have a lock scope of thread scope, the hexadecimal value 00000000 is returned.
User space library name specified. The name of the library that contains the user space specified in the call to the API.
User space library name used. The name of the library that contains the user space into which the generated list is put.
User space name specified. The name of the user space specified in the call to the API.
User space name used. The user space used to return the list of object locks.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPFA0AB E | Object name not a directory. |
| CPFA0A3 E | Path name resolution causes looping. |
| CPFA0A7 E | Path name too long. |
| CPFA0A9 E | Object not found. |
| CPFA09C E | Not authorized to object. |
| CPF0935 E | Cannot use member name for object type &2. |
| CPF0951 E | QSYS only valid library for object type &2. |
| CPF18A0 D | Object type field not valid. |
| CPF18A1 D | Member name is not valid. |
| CPF18A2 D | Path name parameters not specified. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3141 E | Member &1 not found. |
| CPF3CAA E | List is too large for user space &1. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C1B E | Object identifier not valid for lock type &1. |
| CPF3C1C E | Lock type &1 not valid for file attribute &2. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C31 E | Object type &1 is not valid. |
| CPF3C3A E | Value for parameter &2 for API &1 not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9810 E | Library &1 not found. |
| CPF9811 E | Program &1 in library &2 not found. |
| CPF9812 E | File &1 in library &2 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9825 E | Not authorized to device &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9838 E | User profile storage limit exceeded. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V3R1