msgsnd (BPX1QSN, BPX4QSN) — Send to a message queue

Function

The msgsnd service sends a message to a message queue.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN = HASN
AMODE (BPX1QSN):	31-bit task or SRB mode
AMODE (BPX4QSN):	64-bit task mode only
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 BPX1QSN,(Message_Queue_ID,
              Message_address,
              Message_Alet,
              Message_Size,
              Message_Flag,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4QSN with the same parameters. The Message_address parameter is a doubleword.

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 the message to be sent. This area is mapped by MSGBUG of MSGXBuf. The message type is the first word of the message. It must be greater than zero.

Message_Alet

Supplied parameter

Type:: Address
Length:: Fullword

The name of the fullword that contains the ALET for Message_address that identifies the address space or data space where 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_Size

Supplied parameter

Type:: Integer
Length:: Fullword

Specifies the length of the message text that is pointed to by the Message_address parameter. The length does not include the 4-byte type that precedes the message text. For example, a message with a MSG_TYPE and no MSG_MTEXT would have a Message_Size of zero. A zero-length message is accepted.

Message_Flag

Supplied parameter

Type:: Integer
Length:: Fullword

Specifies the action that is to be taken if one or more of these conditions are true:

Placing the message on the message queue would cause the current number of bytes on the message queue (msg_cbytes) to be greater than the maximum number of bytes that are allowed on the message queue (msg_qbytes).
The total number of messages on the message queue (msg_qnum) is equal to the system-imposed limit.

The actions to be taken are as follows:

If Ipc_NOWAIT is specified, the caller returns immediately with an error (EAGAIN).
If Ipc_NOWAIT is not specified, the calling thread suspends execution until one of the following occurs:
- The message is sent.
- 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 msgsnd service returns -1 or 0. The message was sent unless a -1 is received.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

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

Return_code	Explanation
EACCES	Operation permission is denied to the calling task: JRIpcDenied. If the message queue was built with Ipc_SndTypePID, and the MSG_TYPE was other than the invoker's process ID, the following reason code accompanies the return code: JRTypeNotPID.
EAGAIN	The message cannot be sent, and Message_Flag is set to Ipc_NOWAIT. The following reason codes can accompany the return code: JRMsqQueueFullMessages, JRMsqQueueFullBytes.
EIDRM	The Message_Queue_ID was removed from the system while the caller was waiting. The following reason code can accompany the return code: JRIpcRemoved.
EINTR	The function was interrupted by a signal, and the message was not sent. The following reason code can accompany the return code: JRIpcSignaled.
EINVAL	Message_Queue_ID is not a valid message queue identifier; the value of MSG _TYPE is less than 1; or the value of Message_Size is less than zero or greater than the system—imposed limit. The following reason codes can accompany the return code: JRIpcBadID, JRMsqBadSize, or JRMsqBadType.
EFAULT	The Message_address parameter specified an address that caused the service to program check. The following reason code can accompany the return code: JRBadAddress.
ENOMEM	There were not enough system storage exits to send the message; the message was not sent. The following reason code can accompany the return code: JrSmNoStorage.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

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

Write access to the specified message queue is required.
See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.

Related services

Characteristics and restrictions

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

Examples

For an example using this callable service, see BPX1QSN (msgsnd) example.