Retrieve an Interprocess Communication Object (QP0ZRIPC) API

Required Parameter Group:

1	Receiver variable	Output	Char(*)
2	Length of receiver variable	Input	Binary(4)
3	Format name	Input	Char(8)
4	Identifier	Input	Binary(4)
5	Error code	I/O	Char(*)

Default Public Authority: *USE

Threadsafe: No

The Retrieve an Interprocess Communication Object (QP0ZRIPC) API lets you generate detailed information about a single interprocess communication (IPC) object. The object is identified by the format name and the identifier that is passed in.

The QP0ZRIPC API places the information about the object in the receiver variable. The information that is written to the receiver variable is dependent on the format name parameter.

Authorities and Locks

Job Authority: Service special authority (*SERVICE) is needed to call this API.
For additional information on this authority, see the iSeries Security Reference book.

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. The minimum length is 8 bytes.

Format name

INPUT; CHAR(8)

The format of the information to be returned in the receiver variable. This parameter will determine the object type (either message queues, semaphore sets, or shared memory) to retrieve the list for. You must use one of the following format names:

RSST0100	This format is described in RSST0100 Format.
RMSQ0100	This format is described in RMSQ0100 Format.
RSHM0100	This format is described in RSHM0100 Format.

Identifier

INPUT; BINARY(4)

The identifier of the IPC object that you would like to retrieve information about. This identifier is returned from the APIs semget(), shmget(), msgget(), or QP0ZOLIP.

Error code

I/O; CHAR(*)

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

RSST0100 Format

This format name is used to return information for a single semaphore set. The following table shows the information returned in the receiver variable for the RSST0100 format. For a detailed description of each field, see Field Descriptions.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Bytes returned
4	4	BINARY(4)	Bytes available
8	8	BINARY(4)	Identifier
12	C	BINARY(4)	Key
16	10	BINARY(4)	Number of semaphores
20	14	CHAR(1)	Damaged
21	15	CHAR(1)	Owner read permission
22	16	CHAR(1)	Owner write permission
23	17	CHAR(1)	Group read permission
24	18	CHAR(1)	Group write permission
25	19	CHAR(1)	General read permission
26	1A	CHAR(1)	General write permission
27	1B	CHAR(1)	Authorized to delete
28	1C	CHAR(16)	Last semop() date and time
44	2C	CHAR(16)	Last administration change date and time
60	3C	CHAR(10)	Owner
70	46	CHAR(10)	Group owner
80	50	CHAR(10)	Creator
90	5A	CHAR(10)	Creator's group

RMSQ0100 Format

This format name is used to return information about a single message queue. The following table shows the information returned in the receiver variable for the RMSQ0100 format. For a detailed description of each field, see Field Descriptions.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Bytes returned
4	4	BINARY(4)	Bytes available
8	8	BINARY(4)	Identifier
12	C	BINARY(4)	Key
16	10	CHAR(1)	Damaged
17	11	CHAR(1)	Owner read permission
18	12	CHAR(1)	Owner write permission
19	13	CHAR(1)	Group read permission
20	14	CHAR(1)	Group write permission
21	15	CHAR(1)	General read permission
22	16	CHAR(1)	General write permission
23	17	CHAR(1)	Authorized to delete
24	18	BINARY(4)	Number of messages on queue
28	1C	BINARY(4)	Size of all messages on queue
32	20	BINARY(4)	Maximum size of all messages on queue
36	24	BINARY(4)	Number of threads to receive message
40	28	BINARY(4)	Number of threads to send message
44	2C	CHAR(16)	Last msgrcv() date and time
60	3C	CHAR(16)	Last msgsnd() date and time
76	4C	CHAR(16)	Last administration change date and time
92	5C	CHAR(10)	Owner
102	66	CHAR(10)	Group owner
112	70	CHAR(10)	Creator
122	7A	CHAR(10)	Creator's group
132	84	CHAR(26)	Last msgsnd() qualified job identifier
158	9E	CHAR(2)	Reserved
160	A0	BINARY(4)	Last msgsnd() process identifier
164	A4	CHAR(26)	Last msgrcv() qualified job identifier
190	BE	CHAR(2)	Reserved
192	C0	BINARY(4)	Last msgrcv() process identifier
196	C4	BINARY(4)	Offset to message type
200	C8	BINARY(4)	Size of message information record
204	CC	BINARY(4)	Offset to wait type
208	D0	BINARY(4)	Size of message receive record
212	D4	BINARY(4)	Offset to wait size
216	D8	BINARY(4)	Size of message send record
These fields repeat for each message on queue.		BINARY(4)	Message type
These fields repeat for each message on queue.		BINARY(4)	Message size
These fields repeat for each thread waiting to receive a message.		BINARY(4)	Message wait type
		CHAR(26)	Message receive qualified job identifier
		CHAR(2)	Reserved
These fields repeat for each thread waiting to send a message.		BINARY(4)	Message wait size
		CHAR(26)	Message send qualified job identifier
		CHAR(2)	Reserved

RSHM0100 Format

This format name is used to return information for a single shared memory object. The following table shows the information returned in the receiver variable for the RSHM0100 format. For a detailed description of each field, see Field Descriptions.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Bytes returned
4	4	BINARY(4)	Bytes available
8	8	BINARY(4)	Identifier
12	C	BINARY(4)	Key
16	10	CHAR(1)	Damaged
17	11	CHAR(1)	Owner read permission
18	12	CHAR(1)	Owner write permission
19	13	CHAR(1)	Group read permission
20	14	CHAR(1)	Group write permission
21	15	CHAR(1)	General read permission
22	16	CHAR(1)	General write permission
23	17	CHAR(1)	Marked to be deleted
24	18	CHAR(1)	Authorized to delete
25	19	CHAR(1)	Teraspace
26	1A	CHAR(1)	Resize
27	1B	CHAR(1)	Reserved
28	1C	BINARY(4)	Segment size
32	20	BINARY(4)	Number attached
36	24	CHAR(16)	Last shmat() date and time
52	34	CHAR(16)	Last detach 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
124	7C	CHAR(26)	Last attach or detach qualified job identifier
150	96	CHAR(2)	Reserved
152	98	BINARY(4)	Last attach or detach process identifier
156	9C	BINARY(4)	Offset to times attached
160	A0	BINARY(4)	Number of attach entries
164	A4	BINARY(4)	Size of attach entry
These fields repeat for the number of attach entries.		BINARY(4)	Times attached
		CHAR(26)	Attached qualified job identifier
		CHAR(2)	Reserved

Field Descriptions

Attached qualified job identifier. The job name, the job user profile, and the job number of a job that is attached to the shared memory segment. The 26 characters are:

1-10	The job name
11-20	The user profile
21-26	The job number

Authorized to delete. This value determines if the caller has the authority to delete this IPC object. Possible values follow:

0	The current thread cannot delete the IPC object.
1	The current thread can delete the IPC object.

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.

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 attach or detach process identifier. The process identifier of the thread that performed the last successful attachment or detachment from the shared memory segment. If no thread has attached or detached from the shared memory segment, this field will be zero.

Last attach or detach qualified job identifier. The job name, the job user profile, and the job number of the thread that performed the last successful attachment or detachment from the shared memory segment. The 26 characters are:

1-10	The job name
11-20	The user profile
21-26	The job number

These fields will be all blanks if any of the following are true:

No thread has performed an attachment or detachment on the shared memory.
The last process that did an attachment or detachment on the shared memory has ended.
The last process that did an attachment or detachment on the shared memory is not initialized for signals.

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 msgrcv() process identifier. The process identifier of the thread that performed the last successful msgrcv(). If no thread has done a msgrcv(), this field will be zero.

Last msgrcv() qualified job identifier. The job name, the job user profile, and the job number of the thread that performed the last successful msgrcv(). The 26 characters are:

1-10	The job name
11-20	The user profile
21-26	The job number

These fields will be all blanks if any of the following are true:

No thread has received a message on this message queue.
The last process to receive a message has ended.
The last process to receive a message has not been initialized for signals.

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 msgsnd() process identifier. The process identifier of the thread that performed the last successful msgsnd(). If no thread has done a msgsnd(), this field will be zero.

Last msgsnd() qualified job identifier. The job name, the job user profile, and the job number of the thread that performed the last successful msgsnd(). The 26 characters are:

1-10	The job name
11-20	The user profile
21-26	The job number

These fields will be all blanks if any of the following are true:

No thread has sent a message to this message queue.
The last process to send a message has ended.
The last process to send a message has not been initialized for signals.

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.

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.

Message receive qualified job identifier. The job name, the job user profile, and the job number of the thread that is waiting to receive a message. The 26 characters are:

1-10	The job name
11-20	The user profile
21-26	The job number

Message send qualified job identifier. The job name, the job user profile, and the job number of the thread that is waiting to send a message. The 26 characters are:

1-10	The job name
11-20	The user profile
21-26	The job number

Message size. The message size of a message that is currently on the queue.

Message type. The message type of a message that is currently on the queue.

Message wait size. The message size of a message that a thread is currently waiting to put on the queue.

Message wait type. The message type that a thread is currently waiting to receive.

Number attached. The number of times any thread has done a shmat() without doing a detach. One process can be attached multiple times to the same shared memory segment.

Number of attach entries. The number of entries in the variable length section of RSHM0100.

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 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.

Offset to message type. The offset in characters (bytes) from the beginning of the RMSQ0100 record to the message type field.

Offset to times attached. The offset in characters (bytes) from the beginning of the RSHM0100 record to the times attached field.

Offset to wait size. The offset in characters (bytes) from the beginning of the RMSQ0100 record to the wait size field.

Offset to wait type. The offset in characters (bytes) from the beginning of the RMSQ0100 record to the wait type field.

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.

Reserved. An ignored 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.

Size of all messages on queue. The size, in bytes, of all of the messages that are currently on the queue.

Size of attach entry. The size, in bytes, of each attach entry in the array of attach entries.

Size of message information record. The size, in bytes, of each message information record.

Size of message receive record. The size, in bytes, of the record that is used to store information about a thread waiting to receive a message.

Size of message send record. The size, in bytes, of the record that is used to store information about a thread waiting to send a message.

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.

Times attached. The number of times that this process is attached to the shared memory.

Error Messages

Message ID	Error Message Text
GUI0002 E	&2 is not valid for length of receiver variable.
CPF0F01 E	*SERVICE authority is required to run this program.
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.
CPFA988 E	IPC object &1 does not exist.

API introduced: V4R2

Top | UNIX-Type APIs | APIs by category