Retrieve an Interprocess Communication Object (QP0ZRIPC) API

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

RMSQ0100 Format

RSHM0100 Format

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

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.