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
|
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.
- 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.