CRTMSGQ (Create Message Queue)

CRTMSGQ Command syntax diagram

 

Purpose

The Create Message Queue (CRTMSGQ) command creates a user-defined message queue and stores it in a specified library. The message queue should be put in a library for which all users who are sending messages to and receiving messages from the queue have *USE authority. The messages sent can be either predefined messages or immediate messages. The message queue has the following attributes initialized when it is created: the DLVRY parameter is set to *HOLD, PGM is set to *DSPMSG, SEV is set to 00, and RESET is set to *NO. These initialized attributes cannot be specified on the CRTMSGQ command and the CHGMSGQ command must be used to change them after the queue is created.

Note: Message queue QSYSOPR is shipped with a message queue full action of *WRAP. If the value is changed to *SNDMSG and the queue needs to be recreated because it was damaged, the value is reset to the shipped value of *WRAP.

 

Required Parameters

MSGQ
Specifies the qualified name of the message queue being created.

The name of the message queue can be qualified by one of the following library values:

*CURLIB: The message queue is created in the current library for the job. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library where the message queue is created.

message-queue-name: Specify the name of the message queue being created.

 

Optional Parameters

FORCE
Specifies whether changes made to the message queue description or messages added to or removed from the queue are immediately forced into auxiliary storage. This ensures that changes to the queue, or messages sent or received, are not lost if a system failure occurs.

*NO: Changes made to the message queue, including its messages, are not immediately forced to auxiliary storage.

*YES: Changes to the message queue description and to the messages in the queue are immediately forced to auxiliary storage.

SIZE
Specifies the initial storage size of the message queue, the size of each increment added to its storage, and the number of times an increment of the specified the size can be added. The storage size is expressed in kilobytes (K). The message queue size is increased when a message is sent to the message queue and there is not enough room for it in the queue. If SIZE is not specified, SIZE(3 1 *NOMAX) is assumed.

Element 1: Initial Size

One of the following is used to specify the initial storage size of the message queue.

3: Initially, the message queue has 3K of storage assigned to it (1K equals 1024 bytes of storage).

initial-K-bytes: Specify the value that specifies the initial size of the queue. The specified value cannot equal 0.

Element 2: Increment Value

One of the following is used to specify the amount of storage in kilobytes added to the message queue's size.

1: The message queue size is increased by 1K of storage for each increment added.

increment-value: Specify the number of kilobytes added for each increment.

Element 3: Maximum Number of Increments

One of the following is used to specify the maximum number of storage space increments that can be added to the message queue's size.

*NOMAX: The system maximum is used.

number-of-increments: Specify the maximum number of increments that can be added to the queue size. A value of 0 prevents any additions to the initial size of the queue.

AUT
Specifies the authority given to users who do not have specific authority to the message queue, who are not on an authorization list, and whose user group has no specific authority to the message queue.

*LIBCRTAUT: The public authority for the message queue is taken from the value on the CRTAUT parameter of the target library (the library that is to contain the message queue). The public authority is determined when the message queue is created. If the CRTAUT value for the library changes after the message queue is created, the new value does not affect any existing objects.

*CHANGE: The user can perform all operations on the object except those limited to the owner or controlled by object existence authority and object management authority. The user can change and perform basic functions on the object. Change authority provides object operational authority and all data authority. If the object is an authorization list, the user cannot add, change, or remove users.

*ALL: The user can perform all operations except those limited to the owner or controlled by authorization list management authority. The user can control the object's existence, specify the security for the object, change the object, and perform basic functions on the object. The user also can change ownership of the message queue.

*USE: The user can perform basic operations on the message queue. The user is prevented from changing the object. Use authority provides object operational authority, read authority, and execute authority.

*EXCLUDE: The user cannot access the message queue.

authorization-list-name: Specify the name of the authorization list used.

ALWALR
Specifies whether the queue being created allows alerts to be generated from alert messages that are sent to it.

*NO: Does not allow alerts to be generated from this message queue.

*YES: Allows alerts to be generated from this message queue.

CCSID
Specifies the coded character set identifier (CCSID) associated with this message queue. The CCSID applies only to immediate messages and message data that is defined as a character field that can be converted (*CCHAR).

*HEX: Messages sent to, received from, or displayed from this message queue are not converted. The message queue CCSID is 65535.

*MSG: Messages sent to this message queue are not converted. The CCSID specified by the sending job is saved in case a conversion is needed for a display or receive function. The message queue CCSID is 65534.

*JOB: The CCSID of the message queue will be the CCSID of the job running this command.

coded-character-set-identifier: Specify the CCSID associated with this message queue. Messages sent to this message queue are converted to this CCSID. Valid values range from 1 through 65535. See the Globalization topic in the Information Center for a list of valid CCSID values.

For more information about the message handler and its use of CCSIDs, see the Globalization topic in the Information Center.

MSGQFULL
Specifies the action to take when the message queue is full.

*SNDMSG: When the message queue is full, CPF2460 (Message queue could not be extended.) is sent to the program or user that is sending a message to the full message queue.

*WRAP: When the message queue is full, the oldest informational and answered messages are removed from the message queue to allow space for new messages to be added. If the removing of the informational and answered messages does not provide space to add the requested message, then unanswered inquiry messages are removed until there is space to add the requested message. The default reply is sent before an unanswered inquiry message is removed. When the message queue is wrapped, CPI2420 or CPI2421 will be sent to the queue that was full to indicate it was wrapped. If there is no space on the queue to send these messages they are sent to the joblog of the user that was sending the message to the queue and they are sent to QHST if the full queue is QSYSOPR.

Note: When a queue uses *WRAP and a job sends a message to the queue that causes a wrap, messages are removed for the following conditions in order to perform the wrap:

  • the queue is in break or notify mode for a job

  • a job is in a message wait state because it did a receive function on the queue with a wait time specified

  • the queue is allocated by a job via the ALCOBJ command

Only the system wrap function can remove messages from queues in these conditions. Other jobs still are not allowed to remove messages from the queues during these conditions. With *SNDMSG, these conditions do not allow another job to remove messages from the queue.

Also when a queue specifies *WRAP and it is in break mode, the wrap function only removes messages that have been received by the break-handling program. For example, if the break-handling program did not receive all messages from the the queue and it was becoming full, CPF2460 could be issued because messages could not be removed to perform the wrap.


TEXT
Specifies the text that briefly describes the message queue. More information on this parameter is in Commonly used parameters.

*BLANK: Text is not specified.

'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Example for CRTMSGQ 

CRTMSGQ   MSGQ(MYQ)  SIZE(3 3 *NOMAX)
  TEXT('This message queue is for inventory
  transactions')  AUT(*CHANGE)

This command creates the message queue MYQ and stores it in the current library (*CURLIB) by default. All users are authorized to send messages to the queue and to read its messages.

The message queue is created with an initial size of 3 kilobytes (KB) and increased in size in 3 KB increments. The restriction on its maximum size is the system limit for objects, which is about 16,000 KB.

Error messages for CRTMSGQ

*ESCAPE Messages

CPF2108
Object &1 type *&3 not added to library &2.
CPF2112
Object &1 in &2 type *&3 already exists.
CPF2113
Cannot allocate library &1.
CPF2151
Operation failed for &2 in &1 type *&3.
CPF2182
Not authorized to library &1.
CPF2283
Authorization list &1 does not exist.
CPF2402
Library &1 not found
CPF247E
CCSID &1 is not valid.
CPF2497
Size for &1 in &2 exceeds machine limit.
CPF9838
User profile storage limit exceeded.