osi_kmsgsnd — Send a message to a message queue

Function

The osi_kmsgsnd service sends a message to a message queue.

This is a secondary interface to the msgsnd service. It is provided for use by a PFS that is running in a colony address space. For information about the msgsnd service, see msgsnd (BPX1QSN, BPX4QSN) — Send to 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_kmsgsnd,(Message_Queue_ID,
              Message_address,
              Message_Alet,
              Message_Size,
              Message_Flag,
              Return_value,
              Return_code,
              Reason_code)

Parameters

Message_Queue_ID

Supplied parameter

Type:: Integer
Character set:: N/A
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 the message that is to be sent. This area is mapped by MSGBUF. The message type is the first word of the message, and 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 in which the buffer resides.

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

You should specify a Message_address 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 has a Message_Size of zero.

Message_Flag

Supplied parameter

Type:: Integer
Length:: Fullword

Specifies the action that is to be taken if one or more of the following 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 that are 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 osi_kmsgsnd 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 osi_kmsgsnd service stores the return code. The osi_kmsgsnd 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_kmsgsnd 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. The following reason code can accompany the return code: JRIpcDenied.
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 invoker 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 syscall to program check. The following reason code can accompany the return code: JRBadAddress.
ENOMEM	There are 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 osi_kmsgsnd service stores the reason code. The osi_kmsgsnd 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

None.

Related services

Characteristics and restrictions

This service may only be invoked from a colony address space.
The caller is restricted by ownership, read, and read/write permissions that are defined by OSI_kmsgsnd and OSI_kmsgctl Ipc_SET.