osi_kipcget — Query interprocess communications

Function

The osi_kipcget service queries shared memory, messages and semaphors for the "next or specified member".

It is a secondary interface to the w_getipc service and is provided for use by a PFS that is running in a colony address space. For information about the w_getipc service, see w_getipc (BPX1GET, BPX4GET) — Query interprocess communications in z/OS UNIX System Services Programming: Assembler Callable Services Reference.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state; any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	Any
AMODE:	31-bit
ASC mode:	Any
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

           
CALL osi_kipcget(Ipc_Token | Ipc_Member_ID,
                 Buffer_Address,
                 Buffer_Length,
                 Command,
                 Return_value,
                 Return_code,
                 Reason_code);

Parameters

Ipc_Token

Supplied parameter

Type:: Integer
Length:: Word

Specifies a token that corresponds to a message queue, shared memory segment, or semaphore member ID. Zero represents the first member ID. The token that is to be used in the next invocation is passed back in Return_value. Ipc_Token is ignored when Ipc_OVER is specified.

Ipc_Member_ID

Supplied parameter

Type:: Integer
Length:: Word

Specifies a message queue ID, semaphore ID, or shared member ID.

Buffer_address

Supplied parameter

Type:: Address
Length:: Fullword

Address of the buffer structure that is defined by IPCQ. For the structure that describes this buffer, see Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Reference.

Buffer_Length

Supplied parameter

Type:: Address
Length:: Fullword

Length of the structure that is defined by IPCQ. This parameter is set to IPCQ#LENGTH. Field IPCQLENGTH differs from IPCQ#LENGTH when the system call is at a different level than the included IPCQ. An error is returned if this length is less than 4. The buffer is filled to the lesser of IPCQ#LENGTH or the value specified here.

Command

Supplied parameter

Type:: Integer
Length:: Fullword

Command	Description
Ipcq#ALL	Retrieve next shared memory, message and semaphore member.
Ipcq#MSG	Retrieve next message member.
Ipcq#SEM	Retrieve next semaphore member.
Ipcq#SHM	Retrieve next shared memory member.
Ipcq#OVER	Overview of system variables. Ignores the value of the first operand (Ipc_Token).

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the osi_kipcget service returns the next Ipc_Token (a negative number), 0, or -1 (error). If Ipc_Token is specified, 0 indicates end of file. If Ipc_Member_ID is specified, 0 indicates success.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the osi_kipcget service stores the return code. The osi_kipcget service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The osi_kipcget service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	One of the following errors occurred: The Ipc_Member_ID is not valid for the command that was specified. The Command parameter is not a valid command. The buffer pointer was zero; or the buffer length was less than 4. The following reason codes can accompany the return code: JRBuffTooSmall, JRIpcBadID, or JRBadEntryCode.
EFAULT	An input parameter specified an address that caused the callable service to program check. The following reason code can accompany the return code: JRBadAddress.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the osi_kipcget service stores the reason code. The osi_kipcget service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

With Ipc_Token, return_values should be tested for 0 (end of file) or -1 (error). Other values are negative and will be the next Ipc_Token.
With Ipc_Member_ID, return_values should be tested for -1 (error).
A member's accessibility can change if the permissions are changed.
A given Ipc_Token may not always retrieve the same member.
If a specific member is desired and has been found using Ipc_Token, subsequent requests may place it at that token or later (never earlier).
The address of the osi_kipcget routine is passed to the PFS in the OSIT structure when the PFS is initialized.

Related services

None.

Characteristics and restrictions

This service may be invoked only from a colony address space.