Open List of Interprocess Communication Objects (QP0ZOLIP) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | List information | Output | Char(80) |
| 4 | Number of records to return | Input | Binary(4) |
| 5 | Format name | Input | Char(8) |
| 6 | Filter information | Input | Char(*) |
| 7 | Filter format name | Input | Char(8) |
| 8 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Open List of Interprocess Communication Objects (QP0ZOLIP) API lets you generate a list of interprocess communication (IPC) objects and descriptive information based on the selection parameters. The QP0ZOLIP API places the specified number of list entries in the receiver variable. You can access additional records by using the Get List Entries (QGYGTLE) API. On successful completion of the QP0ZOLIP API, a handle is returned in the list information parameter. You may use this handle on subsequent calls to the following APIs:
- Get List Entries (QGYGTLE)
- Find Entry Number in List (QGYFNDE)
- Close List (QGYCLST)
You can use the QP0ZOLIP API to:
- Open a list of all IPC objects of a specific type (semaphore sets, message
queues, shared memory, named semaphores, or unnamed semaphores).
- Open a list of identifier-based IPC objects (semaphore sets, message
queues, or shared memory) of a specific type with a key in a specified
range.
- Open a list of identifier-based IPC objects of a specific type that are
owned by one or more specified users.
- Open a list of IPC objects of a specific type (semaphore sets, message queues, shared memory, or named semaphores) that were created by one or more specified users.
Only one IPC type (either semaphore sets, message queues, shared memory, named semaphores, or unnamed semaphores) can be returned in one call to this API. The IPC type is determined by the format name parameter.
The records returned by QP0ZOLIP include an information status field that describes the completeness and validity of the information. Be sure to check the information status field before using any other information returned.
Authorities and Locks
- Job Authority
- Service special authority (*SERVICE) is needed to call this API.
For additional information about this authority, see the Security reference topic collection.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable that is used to return the IPC object information that you requested.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable.
- List information
- OUTPUT; CHAR(80)
Information about the list of IPC objects that were opened. For a description of the layout of this parameter, see Open list information format.
- Number of records to return
- INPUT; BINARY(4)
The number of records in the list to put into the receiver variable.
- Format name
- INPUT; CHAR(8)
The format of the information to be returned in the receiver variable. This parameter will determine the type of IPC mechanism to open the list for. You must use one of the following format names:
LSST0100 This format is described in LSST0100 Format. LMSQ0100 This format is described in LMSQ0100 Format. LSHM0100 This format is described in LSHM0100 Format. LNSM0100 This format is described in LNSM0100 Format. LUSM0100 This format is described in LUSM0100 Format.
- Filter information
- INPUT; CHAR(*)
The information in this parameter is used to filter the list of IPC objects. The format of this variable depends on the filter format name.
- Filter format name
- INPUT; CHAR(8)
The name of the format that is used to filter the list of IPC objects. You must use one of the following format names:
FIPC0100 This format is described in FIPC0100 Format.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
FIPC0100 Format
The following shows the format of the filter information for the FIPC0100 format. For detailed descriptions of the field in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Filter on key |
| 1 | 1 | CHAR(3) | Reserved |
| 4 | 4 | BINARY(4) | Minimum key |
| 8 | 8 | BINARY(4) | Maximum key |
| 12 | C | BINARY(4) | Offset to owner profiles array |
| 16 | 10 | BINARY(4) | Number of owner profiles specified |
| 20 | 14 | BINARY(4) | Offset to creator profiles array |
| 24 | 18 | BINARY(4) | Number of creator profiles specified |
| This field repeats for each owner profile name. | CHAR(10) | Owner profile name | |
| This field repeats for each creator profile name. | CHAR(10) | Creator profile name | |
Field Descriptions
Creator profile name. The user profile names that created the IPC objects being returned. These values are used only if the number of creator profiles specified field is greater than one. Possible special values follow:
| *ALL | IPC objects created by any user profile are added to the list. The rest of the user profiles in the array are ignored. |
| *CURRENT | IPC objects created by the current user profile are added to the list. |
Filter on key. Whether filtering will be done based on the key value of the IPC object. Possible values follow:
| 0 | No filtering is done based on the key value. The values of minimum key field and maximum key field are ignored. |
| 1 | Filtering is done based on the values of minimum key field and maximum key field. |
Maximum key. The IPC object's maximum key value. Only the IPC objects with a key greater than or equal to the minimum key and less than or equal to the maximum key will be added to the generated list. This value is only used if the filter on key field is set to one.
Minimum key. The IPC object's minimum key value. Only the IPC objects with a key greater than or equal to the minimum key and less than or equal to the maximum key will be added to the generated list. This value is only used if the filter on key field is set to one.
Number of creator profiles specified. The number of creator profiles specified in the creator profile names array. If this value is zero, no filtering is to be done for the creator user profile.
Number of owner profiles specified. The number of owner profiles specified in the owner profile names array. If this value is zero, no filtering is to be done for the owner user profile.
Offset to creator profiles array. The offset in characters (bytes) from the beginning of the filter information to the beginning of the array of creator profiles.
Offset to owner profiles array. The offset in characters (bytes) from the beginning of the filter information to the beginning of the array of owner profiles.
Owner profile name. The user profile names that own the IPC objects being returned. These values are used only if the number of owner profiles specified field is greater than one. Possible special values follow:
| *ALL | IPC objects that are owned by any user profile are added to the list. The rest of the user profiles in the array are ignored. |
| *CURRENT | IPC objects that are owned by the current user profile are added to the list. |
Reserved. These characters must be set to '00'x.
LSST0100 Format
This format name is used to return list information for semaphore sets. The following table shows the information returned in each record in the receiver variable for the LSST0100 format. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Identifier |
| 4 | 4 | BINARY(4) | Key |
| 8 | 8 | BINARY(4) | Number of semaphores |
| 12 | C | CHAR(1) | Damaged |
| 13 | D | CHAR(1) | Owner read permission |
| 14 | E | CHAR(1) | Owner write permission |
| 15 | F | CHAR(1) | Group read permission |
| 16 | 10 | CHAR(1) | Group write permission |
| 17 | 11 | CHAR(1) | General read permission |
| 18 | 12 | CHAR(1) | General write permission |
| 19 | 13 | CHAR(1) | Authorized to delete |
| 20 | 14 | CHAR(16) | Last semop() date and time |
| 36 | 24 | CHAR(16) | Last administration change date and time |
| 52 | 34 | CHAR(10) | Owner |
| 62 | 3E | CHAR(10) | Group owner |
| 72 | 48 | CHAR(10) | Creator |
| 82 | 52 | CHAR(10) | Creator's group |
LMSQ0100 Format
This format name is used to return list information for message queues. The following table shows the information returned in each record in the receiver variable for the LMSQ0100 format. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Identifier |
| 4 | 4 | BINARY(4) | Key |
| 8 | 8 | CHAR(1) | Damaged |
| 9 | 9 | CHAR(1) | Owner read permission |
| 10 | A | CHAR(1) | Owner write permission |
| 11 | B | CHAR(1) | Group read permission |
| 12 | C | CHAR(1) | Group write permission |
| 13 | D | CHAR(1) | General read permission |
| 14 | E | CHAR(1) | General write permission |
| 15 | F | CHAR(1) | Authorized to delete |
| 16 | 10 | BINARY(4) | Number of messages on queue |
| 20 | 14 | BINARY(4) | Size of all messages on queue |
| 24 | 18 | BINARY(4) | Maximum size of all messages on queue |
| 28 | 1C | BINARY(4) | Number of threads to receive message |
| 32 | 20 | BINARY(4) | Number of threads to send message |
| 36 | 24 | CHAR(16) | Last msgrcv() date and time |
| 52 | 34 | CHAR(16) | Last msgsnd() date and time |
| 68 | 44 | CHAR(16) | Last administration change date and time |
| 84 | 54 | CHAR(10) | Owner |
| 94 | 5E | CHAR(10) | Group owner |
| 104 | 68 | CHAR(10) | Creator |
| 114 | 72 | CHAR(10) | Creator's group |
LSHM0100 Format
This format name is used to return list information for shared memory. The following table shows the information returned in each record in the receiver variable for the LSHM0100 format. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Identifier |
| 4 | 4 | BINARY(4) | Key |
| 8 | 8 | CHAR(1) | Damaged |
| 9 | 9 | CHAR(1) | Owner read permission |
| 10 | A | CHAR(1) | Owner write permission |
| 11 | B | CHAR(1) | Group read permission |
| 12 | C | CHAR(1) | Group write permission |
| 13 | D | CHAR(1) | General read permission |
| 14 | E | CHAR(1) | General write permission |
| 15 | F | CHAR(1) | Marked to be deleted |
| 16 | 10 | CHAR(1) | Authorized to delete |
| 17 | 11 | CHAR(1) | Teraspace |
| 18 | 12 | CHAR(1) | Resize |
| 19 | 13 | CHAR(1) | Reserved |
| 20 | 14 | BINARY(4), UNSIGNED | Segment size |
| 24 | 18 | BINARY(4) | Number attached |
| 28 | 1C | CHAR(16) | Last shmat() date and time |
| 44 | 2C | CHAR(16) | Last detach date and time |
| 60 | 3C | CHAR(16) | Last administration change date and time |
| 76 | 4C | CHAR(10) | Owner |
| 86 | 56 | CHAR(10) | Group owner |
| 96 | 60 | CHAR(10) | Creator |
| 106 | 6A | CHAR(10) | Creator's group |
| 116 | 74 | CHAR(4) | Reserved |
| 120 | 78 | BINARY(8), UNSIGNED | Segment size 64 |
| 128 | 80 | BINARY(8) | Page size |
| 136 | 88 | CHAR(24) | Reserved |
LNSM0100 Format
This format name is used to return list information for named semaphores. The following table shows the information returned in each record in the receiver variable for the LNSM0100 format. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of entry |
| 4 | 4 | BINARY(4) | Value |
| 8 | 8 | BINARY(4) | Maximum value |
| 12 | C | BINARY(4) | Offset to waiting threads |
| 16 | 10 | BINARY(4) | Number of waiting threads |
| 20 | 14 | BINARY(4) | Offset to name |
| 24 | 18 | BINARY(4) | Length of name |
| 28 | 1C | CHAR(16) | Title |
| 44 | 2C | CHAR(1) | Marked to be deleted |
| 45 | 2D | CHAR(1) | Authorized to delete |
| 46 | 2E | CHAR(10) | Creator |
| 56 | 38 | CHAR(10) | Creator's group |
| 66 | 42 | CHAR(1) | Owner read permission |
| 67 | 43 | CHAR(1) | Owner write permission |
| 68 | 44 | CHAR(1) | Group read permission |
| 69 | 45 | CHAR(1) | Group write permission |
| 70 | 46 | CHAR(1) | General read permission |
| 71 | 47 | CHAR(1) | General write permission |
| 72 | 48 | CHAR(26) | Last sem_post() qualified job identifier |
| 98 | 62 | CHAR(2) | Reserved |
| 100 | 64 | CHAR(16) | Last sem_post() thread identifier |
| 116 | 74 | CHAR(26) | Last sem_wait() qualified job identifier |
| 142 | 8E | CHAR(2) | Reserved |
| 144 | 90 | CHAR(16) | Last sem_wait() thread identifier |
| These fields repeat for each thread waiting on the semaphore. | CHAR(26) | Waiting qualified job identifier | |
| CHAR(2) | Reserved | ||
| CHAR(16) | Waiting thread identifier | ||
| This field follows the list of threads waiting on the semaphore. | CHAR(*) | Name of the semaphore | |
LUSM0100 Format
This format name is used to return list information for unnamed semaphores. The following table shows the information returned in each record in the receiver variable for the LUSM0100 format. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of entry |
| 4 | 4 | BINARY(4) | Value |
| 8 | 8 | BINARY(4) | Maximum value |
| 12 | C | BINARY(4) | Offset to waiting threads |
| 16 | 10 | BINARY(4) | Number of waiting threads |
| 20 | 14 | BINARY(4) | Reserved |
| 24 | 18 | CHAR(16) | Title |
| 40 | 28 | CHAR(26) | Last sem_post() qualified job identifier |
| 66 | 42 | CHAR(2) | Reserved |
| 68 | 44 | CHAR(16) | Last sem_post() thread identifier |
| 84 | 54 | CHAR(26) | Last sem_wait() qualified job identifier |
| 110 | 6E | CHAR(2) | Reserved |
| 112 | 70 | CHAR(16) | Last sem_wait() thread identifier |
| These fields repeat for each thread waiting on the semaphore. | CHAR(26) | Waiting qualified job identifier | |
| CHAR(2) | Reserved | ||
| CHAR(16) | Waiting thread identifier | ||
Field Descriptions
Authorized to delete. This value determines if the caller has the authority to delete this IPC object. Possible values follow:
| 0 | The calling thread cannot delete the IPC object. |
| 1 | The calling thread can delete the IPC object. |
Creator. The name of the user profile that created this IPC object.
Creator's group. The name of the group profile that created this IPC object. A special value can be returned:
| *NONE | The creator does not have a group profile. |
Damaged. Whether the IPC object has suffered internal damage. Possible values follow:
| 0 | The IPC object is not damaged. |
| 1 | The IPC object is damaged. |
General read permission. Whether any user other than the owner and group owner has read authority to the IPC object. Possible values follow:
| 0 | General read authority is not allowed to the IPC object. |
| 1 | General read authority is allowed to the IPC object. |
General write permission. Whether any user other than the owner and group owner has write authority to the IPC object. Possible values follow:
| 0 | General write authority is not allowed to the IPC object. |
| 1 | General write authority is allowed to the IPC object. |
Group owner. The name of the group profile that owns this IPC object. A special value can be returned:
| *NONE | The IPC object does not have a group owner. |
Group read permission. Whether the group owner has read authority to the IPC object. Possible values follow:
| 0 | The group owner does not have read authority to the IPC object. |
| 1 | The group owner has read authority to the IPC object. |
Group write permission. Whether the group owner has write authority to the IPC object. Possible values follow:
| 0 | The group owner does not have write authority to the IPC object. |
| 1 | The group owner has write authority to the IPC object. |
Identifier. The unique IPC object identifier.
Key. The key of the IPC object. If this value is zero, this IPC object has no key associated with it.
Last administration change date and time. The date and time of the last change to the IPC object for the owner, group owner, or permissions. The 16 characters are:
| 1 | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| 2-7 | Date, in YYMMDD (year, month, and day) format. |
| 8-13 | Time of day, in HHMMSS (hours, minutes, and seconds) format. |
| 14-16 | Milliseconds. |
Last detach date and time. The date and time of the last detachment from the shared memory segment. If no thread has performed a successful detachment, this value will be set to all zeros. The 16 characters are:
| 1 | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| 2-7 | Date, in YYMMDD (year, month, and day) format. |
| 8-13 | Time of day, in HHMMSS (hours, minutes, and seconds) format. |
| 14-16 | Milliseconds. |
Last msgrcv() date and time. The date and time of the last successful msgrcv() call. If no thread has performed a successful msgrcv() call, this value will be set to all zeros. The 16 characters are:
| 1 | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| 2-7 | Date, in YYMMDD (year, month, and day) format. |
| 8-13 | Time of day, in HHMMSS (hours, minutes, and seconds) format. |
| 14-16 | Milliseconds. |
Last msgsnd() date and time. The date and time of the last successful msgsnd() call. If no thread has performed a successful msgsnd() call, this value will be set to all zeros. The 16 characters are:
| 1 | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| 2-7 | Date, in YYMMDD (year, month, and day) format. |
| 8-13 | Time of day, in HHMMSS (hours, minutes, and seconds) format. |
| 14-16 | Milliseconds. |
Last sem_post() qualified job identifier. The job name, the job user profile, and the job number of the last thread that successfully called sem_post() or sem_post_np() if the job has not ended. The 26 characters are:
| 1-10 | The job name. |
| 11-20 | The user profile. |
| 21-26 | The job number. |
If the thread has ended, then the first 16 characters contain 16 characters that uniquely identify the ended job, followed by 10 spaces. If no thread has used sem_post() to post to the semaphore, then the 26 characters will contain spaces.
Last sem_post() thread identifier. The thread ID of the last thread that successfully called sem_post() or sem_post_np() if the thread has not ended.
Last sem_wait() qualified job identifier. The job name, the job user profile, and the job number of the last thread that returned from a sem_wait(), sem_wait_np(), or sem_wait() call, if the job has not ended. The 26 characters are:
| 1-10 | The job name. |
| 11-20 | The user profile. |
| 21-26 | The job number. |
If the thread has ended, then the first 16 characters contain 16 characters that uniquely identify the ended job, followed by 10 spaces. If no job has used sem_wait() to wait on the semaphore, then the 26 characters will contain spaces.
Last sem_wait() thread identifier. The thread ID of the last thread that returned from a sem_wait(), sem_wait_np(), or sem_wait() call, if the thread has not ended.
Last semop() date and time. The date and time of the last successful semop() call. If no thread has performed a successful semop() call, this value will be set to all zeros. The 16 characters are:
| 1 | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| 2-7 | Date, in YYMMDD (year, month, and day) format. |
| 8-13 | Time of day, in HHMMSS (hours, minutes, and seconds) format. |
| 14-16 | Milliseconds. |
Last shmat() date and time. The date and time of the last successful shmat(). If no thread has performed a successful shmat() call, this value will be set to all zeros. The 16 characters are:
| 1 | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| 2-7 | Date, in YYMMDD (year, month, and day) format. |
| 8-13 | Time of day, in HHMMSS (hours, minutes, and seconds) format. |
| 14-16 | Milliseconds. |
Length of entry. The length of this record in the list.
Length of name. The number of bytes in the name of the semaphore, not including the terminating null character.
Marked to be deleted. Whether the shared memory is marked to be deleted when the number attached becomes zero. Possible values follow:
| 0 | The shared memory segment is not marked for deletion. |
| 1 | The shared memory segment is marked for deletion. |
Maximum size of all messages on queue. The maximum byte size of all messages that can be on the queue at one time.
Maximum value. The maximum value of the semaphore.
Name of the semaphore. The null-terminated name of the semaphore.
Number attached. The number of times any thread has done a shmat() without doing a detach.
Number of messages on queue. The number of messages that are currently on the message queue.
Number of semaphores. The number of semaphores in the semaphore set.
Number of threads to receive message. The number of threads that are currently waiting to receive a message.
Number of threads to send message. The number of threads that are currently waiting to send a message.
Number of waiting threads. The total number of threads that are waiting for this semaphore to reach a certain value.
Offset to name. The offset to where the name field begins.
Offset to waiting threads. The offset to where the fields containing waiting threads begin.
Owner. The name of the user profile that owns this IPC object.
Owner read permission. Whether the owner has read authority to the IPC object. Possible values follow:
| 0 | The owner does not have read authority to the IPC object. |
| 1 | The owner has read authority to the IPC object. |
Owner write permission. Whether the owner has write authority to the IPC object. Possible values follow:
| 0 | The owner does not have write authority to the IPC object. |
| 1 | The owner has write authority to the IPC object. |
Page size. The page size (in bytes) of the storage backing the shared memory segment.
Reserved. A reserved field.
Resize. Whether the shared memory object may be resized. Possible values follow:
| 0 | The shared memory object may not be resized. |
| 1 | The shared memory object may be resized. |
Segment size. The size of the shared memory segment represented in an UNSIGNED BINARY(4) data type. If the size cannot be fully represented in an UNSIGNED BINARY(4) data type, this field will be set to x'FFFFFFFF' and the Segment size 64 field must be used to get the size of the shared memory segment.
Segment size 64. The size of the shared memory segment represented in an UNSIGNED BINARY(8) data type. This field is set in addition to the value set in the Segment size field. The Segment size field can also be used to obtain the size for shared memory segments whose size can be fully represented in an UNSIGNED BINARY(4) data type.
Size of all messages on queue. The byte size of all of the messages that are currently on the queue.
Teraspace. Whether the shared memory object is attachable only to a process's teraspace. Possible values follow:
| 0 | The shared memory object is not attachable to a process's teraspace. |
| 1 | The shared memory object is attachable to a process's teraspace. |
Title. The title of the semaphore. The title contains the 16 characters that are associated with the semaphore when it is created.
Value. The value of the semaphore.
Waiting qualified job identifier. The job name, the job user profile, and the job number of a thread waiting on the semaphore. The 26 characters are:
| 1-10 | The job name |
| 11-20 | The user profile. |
| 21-26 | The job number. |
Waiting thread identifier. The thread ID of a thread waiting on the semaphore.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF0F01 E | *SERVICE authority is required to run this program. |
| CPF2204 E | User profile &1 not found. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| GUI0002 E | &2 is not valid for length of receiver variable. |
| GUI0027 E | &1 is not valid for number of records to return. |
| GUI0115 E | The list has been marked in error. See the previous messages. |
| GUI0118 E | Starting record cannot be 0 when records have been requested. |
| GUI0135 E | Filter key information is not valid. |
| GUI0136 E | Filter information is not valid. |
API introduced: V4R2