msgget (BPX1QGT, BPX4QGT) — Create or find a message queue

Function

The msgget function returns a message queue ID that it created or that the user is allowed to access.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1QGT):	31-bit
AMODE (BPX4QGT):	64-bit
ASC mode:	Primary mode
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 BPX1QGT,(Key,
              Message_Flag,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4QGT with the same parameters.

Parameters

Key

Supplied parameter

Type:: Integer
Length:: Fullword

Identification for this message queue. This can be 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.
Ipc_RcvTypePID: Creates a message queue that can only be read from (by the msgrcv service) when Message_Type is the process ID of the invoker. This restriction does not apply if the caller of the msgrcv service has the same effective UID as the creator of the message queue.
Ipc_SndTypePID: Creates a message queue that can only be written to (by the msgsnd service) when Message_Type is the process ID of the invoker. This restriction does not apply if the caller of the msgsnd service has the same effective UID as the creator of the message queue.
Ipc_PLO1: Use PLO for serialization.
Ipc_PLO2: Use PLO if practical.
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 msgget service returns -1 or the message queue identifier.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

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

As long as a thread knows the message queue ID, it may issue a msgctl, msgsnd, or msgrcv request (msgget is not needed).
This function returns the message queue identifier that is associated with the Key parameter.
This function creates a data structure that 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 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 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.
In a client/server environment, two message queues could be used: one inbound to the server, created with Ipc_SndTypePID, and the other outbound from the server, created with Ipc_RcvTypePID. This arrangement guarantees that the server knows the process ID of the client and that the client is the only process that receives the server's returned message. The server could call the msgrcv service with PID=0 to see if there are any messages that belong to process IDs that have gone away.
Message_Flags Ipc_PLO1 and Ipc_PLO2 are ignored if the PLO (Perform Lock Operation) instruction is not present on the hardware. (See SCCBPLO in IHASCCB and the Ipc_PLOInUse bit in the S_MODE byte returned with w_getipc.)
Performance of the PLO instruction for serialization varies with the msgrcv() type, the number of messages on the queue, and the number of tasks that are doing msgsnd and msgrcv requests. A msgrcv request with a message type that is less than zero and that has long message queues is expected to be a poor performer. A msgrcv request with a message type that is greater than zero is expected to be an equivalent or good performer. A msgrcv request with a message type equal to zero is expected to be a very good performer.
Message queues that are created with Ipc_RcvTypePID, Ipc_SndTypePID, Ipc_PLO1 and Ipc_PLO2 show these bits, and may show the Ipc_PLOInUse bit in the S_MODE byte that is returned with the w_getipc request.
Message queue PLO serialization is not compatible with the use of select() for message queues. When the msgrcv service detects a select() for a message queue, serialization is changed to use traditional latches.
Performance runs should be made with Ipc_PLO1, because Ipc_PLO2 could switch to latch serialization, and the user would not be aware of this. Upon the first msgrcv() with a message type that is less than zero, the message queue will attempt to switch to latch serialization.

Related services

Characteristics and restrictions

There is a maximum number of message queues that are allowed in the system.
The invoker is restricted by ownership, read, and read-write permissions that are defined by msgget and msgctl Ipc_SET.

Examples

For an example using this callable service, see BPX1QGT (msgget) example.