osi_kmsgget — Create or find a message queue

Function

The osi_kmsgget service returns a message queue ID.

This is a secondary interface to the msgget service. It is provided for use by a PFS running in a colony address space. For information about the msgget service, see msgget (BPX1QGT, BPX4QGT) — Create or find a message queue 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_kmsgget,(Key,
              Message_Flag,
              Return_value,
              Return_code,
              Reason_code)

Parameters

Key

Supplied parameter

Type:: Integer
Length:: Fullword

Identification for this message queue. This is a user-defined value that serves as a lookup value to determine if this message queue already exists, or the reserved value Ipc_PRIVATE.

Message_Flag

Supplied parameter

Type:: Integer
Length:: Fullword

Valid values for this field include any combination of the following (additional bits cause an EINVAL):

Ipc_CREAT: Creates a message queue if the key that is specified does not already have an associated ID. Ipc_CREATE is ignored when Ipc_PRIVATE is specified.
Ipc_EXCL: Causes the msgget function to fail if the key that is specified has an associated ID. Ipc_EXCL is ignored when Ipc_CREAT is not specified, or when Ipc_PRIVATE is specified.
S_IRUSR: Permits the process that owns the message queue to read it.
S_IWUSR: Permits the process that owns the message queue to alter it.
S_IRGRP: Permits the group that is associated with the message queue to read it.
S_IWGRP: Permits the group that is associated with the message queue to alter it.
S_IROTH: Permits others to read the message queue.
S_IWOTH: Permits others to alter the message queue.

The values that begin with an Ipc_ prefix are defined in BPXYIPCP, and are mapped onto S_TYPE, which is in BPXYMODE.

The values that begin with an S_I prefix are defined in BPXYMODE, and are a subset of the access permissions that apply to files.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the osi_kmsgget service returns -1 or the message queue identifier.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the osi_kmsgget service stores the return code. The osi_kmsgget 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_kmsgget service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	A message queue identifier exists for the Key parameter, but operation permission, as specified by the low-order 9-bits of the Message_Flag parameter, is not granted (the "S_" items). The following reason code can accompany the return code: JRIpcDenied.
EEXIST	A message queue identifier exists for the Key parameter, and both Ipc_CREAT and Ipc_EXCL are specified. The following reason code can accompany the return code: JRIpcExists.
EINVAL	The Message_Flag operand included bits that are not supported by this function. The following reason code can accompany the return code: JRIpcBadFlags.
ENOENT	A message queue identifier does not exist for the Key parameter, and Ipc_CREAT was not set. The following reason code can accompany the return code: JRIpcNoExist.
ENOSPC	The system limit of the number of message queue IDs has been reached. The following reason code can accompany the return code: JRIpcMaxIDs.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the osi_kmsgget service stores the reason code. The osi_kmsgget 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

If the thread knows the message queue ID, it can issue a msgctl, msgsnd, or msgrcv. msgget is not needed.
This function returns the message queue identifier that is associated with the Key parameter.
This function creates a data structure, which is defined by MSQID_DS, if one of the following is true:
- The Key parameter is equal to Ipc_PRIVATE.
- The Key parameter does not already have a message queue identifier that is associated with it, and Ipc_CREAT is set.
Upon creation, the data structure that is associated with the new message queue identifier is initialized as follows:
- Ipc_CUID and Ipc_UID are set to the effective user ID of the calling task.
- Ipc_CGID and Ipc_GID are set to the effective group ID of the calling task.
- The low-order 9-bits of Ipc_MODE are equal to the low-order 9-bits of the Message_Flag parameter.
- MSG_QBYTES is set to the system limit that is defined by parmlib.
The message queue is removed from the system when BPX1QCT (msgctl) is called with command Ipc_RMID.
Users of message queues are responsible for removing them when they are no longer needed. Failure to do so ties up system resources.

Related services

osi_kmsgctl — Perform message queue control operations

Characteristics and restrictions

This service is invoked from a colony address space.
There is a maximum number of message queues that are allowed in the system.
The caller is restricted by ownership, read, and read/write permissions that are defined by OSI_kmsgget and OSI_kmsgctl Ipc_SET.