msgrcv (BPX1QRC, BPX4QRC) — Receive from a message queue

Function

The msgrcv service receives messages from a message queue.

Requirements

Parameters

Message_Queue_ID

Supplied parameter

Type:

Integer

Length:

Fullword

Specifies the message queue identifier.

Message_Address

Supplied parameter

Type:

Address

Length:

Fullword (doubleword)

The name of a fullword (doubleword) field that contains the address of a buffer that is mapped by MSGBUF or MSGXBUF (see BPXYMSG — Map interprocess communication message queues).

Message_Alet

Supplied parameter

Type:

Address

Length:

Fullword

The name of the fullword that contains the ALET for Message_Address, which identifies the address space or data space where the buffer resides.

You should specify a Message_Alet of 0 if the buffer is in the user's address space (current primary address space).

You should specify a Message_Alet of 2 if the buffer resides in the home address space.

If a value other than 0 or 2 is specified for the Message_ALET, the value must represent a valid entry in the dispatchable unit access list (DUAL).

Message_Length

Supplied parameter

Type:

Integer

Length:

Fullword

Specifies the length of the message text that is to be placed in the buffer that is pointed to by Message_Address parameter.

In 31-bit mode, if Msg_Info is specified, this buffer is 20 bytes longer than Message_Length; otherwise this buffer is 4 bytes longer than Message_Length. In 64-bit mode, if Msg_Info is specified, this buffer is 28 bytes longer than Message_Length; otherwise this buffer is 8 bytes longer than Message_Length.

The message that is received may be truncated (see MSG_NOERROR of Message_Flag). A value of zero with MSG_NOERROR is useful for receiving the message type without the message text.

Message_Type

Supplied parameter

Type:

Integer

Length:

Fullword (doubleword)

Specifies the type of message requested, as follows:

• If Message_Type is equal to zero, the first message on the queue is received.
• If Message_Type is greater than zero, the first message of Message_Type is received.
• If Message_Type is less than zero, the first message of the lowest type that is less than or equal to the absolute value of Message_Type is received.

Message_Flag

Supplied parameter

Type:

Integer

Length:

Fullword

MSG_NOERROR specifies that the received message is to be truncated to Message_Length (mapped in BPXYMSG). The truncated part of the message is lost, and no indication of the truncation is given to the caller.

MSG_INFO specifies that the received message is to be of the MSGXBUF and not the MSGBUF format, mapped in BPXYMSG. MSG_INFO specifies that extended information is to be received. This is similar to the msgxrcv() C language function.

Ipc_NOWAIT specifies the action that is to be taken if a message of the desired type is not on the queue, as follows:

• If Ipc_NOWAIT is specified, the caller is to return immediately with an error (ENOMSG).
• If Ipc_NOWAIT is not specified, the calling thread is to suspend execution until one of the following occurs:
  • A message of the desired type is placed on the queue.
  • The message queue is removed from the system (EIDRM).
  • The caller receives a signal (EINTR).

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the msgrcv service returns -1, or the number of MSG_MTEXT bytes returned.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

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

Return_code	Explanation
E2BIG	MSG_MTEXT is greater than Message_Length, and MSG_NOERROR is not set. The following reason code can accompany the return code: JRMsq2Big.
EACCES	Operation permission is denied to the calling task: JRIpcDenied. If the message queue was built with the Ipc_RcvTypePID, and the MSG_TYPE was other than the invoker's process ID, the following reason code accompanies the return code: JRTypeNotPID.
EIDRM	The Message_Queue_ID was removed from the system while the invoker was waiting. The following reason code can accompany the return code: JRIpcRemoved.
EINTR	The function was interrupted by a signal. The following reason code can accompany the return code: JRIpcSignaled.
EINVAL	Message_Queue_ID is not a valid message queue identifier; or the Message_Length parameter is less than 0. The following reason codes can accompany the return code: JRIpcBadID or JRMsqBadSize.
EFAULT	The Message_Address parameter specified an address that caused the syscall to program check. The following reason code can accompany the return code: JRBadAddress.
ENOMSG	The queue does not contain a message of the desired type, and Ipc_NOWAIT is set. The following reason code can accompany the return code: JRMsqNoMsg.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

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

1. Within the type specifications, the longest waiting thread will be reactivated first (FIFO). For example, if there are two threads waiting on message type 3 and one thread waiting on message type 2, when a message send for type 3 occurs, the oldest waiter for message type 3 receive is posted first.
2. Read access to the specified message queue is required.

Related services

• msgctl (BPX1QCT, BPX4QCT) — Perform message queue control operations
• msgget (BPX1QGT, BPX4QGT) — Create or find a message queue
• msgsnd (BPX1QSN, BPX4QSN) — Send to a message queue

Characteristics and restrictions

The caller of the msgrcv service is restricted by ownership, read, and read-write permissions that are defined by msgget and msgctl Ipc_SET.