Create Message Queue (CRTMSGQ)

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 to send messages to and receive 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, the first element of the PGM parameter is set to *DSPMSG and the second element of the PGM parameter is set to *ALWRPY, 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.

Parameters

Message queue (MSGQ)

Specifies the message queue to be created.

This is a required parameter.

Qualifier 1: Message queue

name

Specify the name of the message queue being created.

Qualifier 2: Library

*CURLIB

The current library for the job is used to create the message queue. If no current library entry exists in the library list, the QGPL library is used.

name

Specify the library where the message queue is to be created.

Text 'description' (TEXT)

Specifies the text that briefly describes the object.

*BLANK

No text is specified.

'description'

Enter no more than 50 characters, enclosed in apostrophes.

Force to auxiliary storage (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

All changes to the message queue description and to the messages in the queue are immediately forced to auxiliary storage.

Queue size (SIZE)

Specifies the initial storage size of the message queue, the size of each addition to its storage, and the number of times the size can be increased. The storage size is expressed in kilobytes (KB).

Element 1: Initial storage size

3

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

initial-Kilobytes

Specify the initial size of the queue (must be greater than 0).

Element 2: Increment storage size

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

1

One KB of storage is added to the message queue each time its size is increased.

increment-value

Specify the number of kilobytes added each time the message queue's size is increased.

Element 3: Maximum increments

One of the following is used to specify the maximum number of times the message queue's size can be increased.

*NOMAX

The number of times storage can be added to the message queue is not limited by the user. The maximum size is determined by the system.

number-of-increments

Specify the maximum number of times storage can be added to the queue. Enter a 0 to prevent any additions to the initial size of the queue.

Authority (AUT)

Specifies the authority you are giving to users who do not have specific authority for the object, who are not on an authorization list, and whose group profile or supplemental group profiles do not have specific authority for the object.

*LIBCRTAUT

The system determines the authority for the object by using the value specified for the Create authority (CRTAUT) parameter on the Create Library command (CRTLIB) for the library containing the object to be created. If the value specified for the CRTAUT parameter is changed, the new value will 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 (*OBJEXIST) and object management (*OBJMGT) authorities. The user can change and perform basic functions on the object. *CHANGE authority provides object operational (*OBJOPR) 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 (*AUTLMGT) 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 object.

*USE

The user can perform basic operations on the object, such as running a program or reading a file. The user cannot change the object. Use (*USE) authority provides object operational (*OBJOPR), read (*READ), and execute (*EXECUTE) authorities.

*EXCLUDE

The user cannot access the object.

name

Specify the name of an authorization list to be used for authority to the object. Users included in the authorization list are granted authority to the object as specified in the list. The authorization list must exist when the object is created.

Allow alerts (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.

Coded character set ID (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 information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter for a list of valid CCSID values.

For more information about the message handler and its use of CCSIDs, see the i5/OS globalization topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Message queue full action (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 enough 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.

Examples

CRTMSGQ   MSGQ(MYQ)  SIZE(3 3 *NOMAX)
          TEXT('Message queue 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

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