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:

You can use the QP0ZOLIP API to:

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

[ Back to top | UNIX-Type APIs | APIs by category ]