osi_kmsgrcv — Receive from a message queue

Function

The osi_kmsgrcv service receives a message from a message queue.

This is a secondary interface to the msgrcv service. It is provided for use by a PFS that is running in a colony address space. For information about the msgrcv service, see msgrcv (BPX1QRC, BPX4QRC) — Receive from 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_kmsgrcv,(Message_Queue_ID,
              Message_Address,
              Message_Alet,
              Message_Length,
              Message_Type,
              Message_Flag,
              Return_value,
              Return_code,
              Reason_code)

Parameters

Message_Queue_ID

Supplied parameter

Type:: Integer
Length:: Fullword

Specifies the message queue identifier.

Message_Address

Supplied parameter

Type:: Address
Length:: Fullword

The name of a field that contains the address of a buffer that is mapped by MSGBUF or MSGXBUF (see Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Reference).

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 in which the buffer resides.

You should specify a Message_Alet of 0 if the buffer resides 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. If Msg_Info is specified, this buffer is 20 bytes longer than Message_Length; otherwise this buffer is 4 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

Specifies the type of message that is 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, which 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 osi_kmsgrcv 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 osi_kmsgrcv service stores the return code. The osi_kmsgrcv 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_kmsgrcv 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. The following reason code can accompany the return code: JRIpcDenied.
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 osi_kmsgrcv service stores the reason code. The osi_kmsgrcv 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

Within the type specifications, the longest waiting thread is 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.
Read access to the specified message queue is required.

Related services

Characteristics and restrictions

This service is invoked only 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_kmsgrcv and OSI_kmsgctl Ipc_SET.