msgctl (BPX1QCT, BPX4QCT) — Perform message queue control operations

Function

The msgctl service provides a variety of message control operations as specified by the Command parameter. These functions include reading and changing message variables within the MSQID_DS data structure, and removing a message queue from the system.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1QCT):	31-bit
AMODE (BPX4QCT):	64-bit
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 BPX1QCT,(Message_Queue_ID,
              Command,
              Buffer,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4QCT with the same parameters. The Buffer parameter is a doubleword.

Parameters

Message_Queue_ID

Supplied parameter

Type:: Integer
Length:: Fullword

Specifies the message queue identifier.

Command

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword field that indicates the message command to be executed. For the structure that contains these constants, see BPXYIPCP — Map interprocess communication permissions. The values for Command are:

Ipc_STAT: Obtain status information about the message queue that is identified by the Message_Queue_ID parameter, if the current process has read permission. This information is stored in the area that is pointed to by argument Buffer and mapped by area MSQID_DS data structure. For the data structure, see BPXYMSG — Map interprocess communication message queues, MSQID_DS DSECT.
Ipc_SET: Set the value of the IPC_UID, IPC_GID, IPC_MODE and MSG_QBYTES for associated Message_queue_ID. The values that are to be set are taken from the MSQID_DS data structure that is pointed to by argument Buffer. Any value for IPC_UID and IPC_GID may be specified. Only mode bits that are defined by msgctl under Message_Flag argument may be specified in the IPC_MODE field. This Command can only be executed by a task that has an effective user ID equal either to that of a task with appropriate privileges (see Authorization), or to the value of IPC_CUID or IPC_UID in the MSQID_DS data structure that is associated with Message_Queue_ID. This information is taken from the buffer that is pointed to by the Buffer parameter. For the data structure, see BPXYMSG — Map interprocess communication message queues, MSQID_DS DSECT.
Ipc_RMID: Remove the message identifier that is specified by Message_Queue_ID from the system, and destroy the message queue and MSQID_DS data structure that are associated with it. This Command can only be executed by a process that has an effective user ID equal either to that of a process with appropriate privileges (see Authorization), or to the value of IPC_CUID or IPC_UID in the MSQID_DS data structure that is associated with Message_Queue_ID.

Buffer

Parameter supplied and returned

Type:: Address
Length:: Fullword (doubleword)

The name of the fullword (doubleword) that contains the address of the buffer into which or from which the message queue information will be copied. This buffer is mapped by MSQID_DS. (See BPXYMSG — Map interprocess communication message queues.)

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the msgctl service returns -1 or 0.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

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

Return_code	Explanation
EACCES	The command specified was Ipc_STAT, and the calling process does not have read permission. The following reason code can accompany the return code: JRIpcDenied.
EINVAL	One of the following occurred: Message_Queue_ID is not a valid Message queue identifier. The Command parameter is not a valid command. The mode bits were not valid (SET). The following reason codes can accompany the return code: JRIpcBadFlags, JRMsqQBytes, or JRIpcBadID.
EPERM	One of the following occurred: The command specified was Ipc_RMID or Ipc_SET. The effective user ID of the caller is not that of a process with appropriate privileges (see Authorization), and is not the value of IPC_CUID or IPC_UID in the MSQID_DS data structure that is associated with Message_Queue_ID. The command specified was Ipc_SET, and an attempt is being made to increase MSG_QBYTES. The effective user ID of the caller does not have superuser privileges. The following reason codes can accompany the return code: JRIpcDenied or JRMsqQBytes.
EFAULT	The Buffer parameter specified an address that caused the syscall to program check. The following reason code can accompany the return code: JRBadAddress.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

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

Changing the access permissions only affects message queue syscall requests that occur after the msgctl service has returned. The msgsnd and msgrcv services, which are waiting while the permission bits are changed by msgctl, are not affected.
Ipc_SET can change permissions, and may affect the ability of a thread to use the next message queue syscall.
Quiescing a message queue stops additional messages from being added, while allowing existing messages to be received. You can quiesce a message queue by clearing (Ipc_SET) write permission bits.
You can also quiesce a message queue by reducing MSG_QBYTES (Ipc_SET) to zero. (Note: It would take a superuser to re-raise the limit.) Requesters are told EAGAIN or wait.
When a message queue ID is removed (Ipc_RMID) from the system, all waiting threads regain control with RV=-1, RC=EIDRM, and RC=JRIpcRemoved.
If you do not wish to change all the fields, first initialize (Ipc_STAT) the buffer, change the desired fields, and then make the change (Ipc_SET).
For Command Ipc_RMID, the remove is complete by the time control returns to the caller.

Related services

Characteristics and restrictions

The invoker is restricted by ownership, read and read-write permissions defined by msgget and msgctl Ipc_SET.

Examples

For an example using this callable service, see BPX1QCT (msgctl) example.