CHGMSGQ (Change Message Queue)

CHGMSGQ Command syntax diagram

 

Purpose

The Change Message Queue (CHGMSGQ) command changes the attributes of the specified message queues. If the delivery mode is being changed to *BREAK or *NOTIFY and if the message queue is not already in *BREAK or *NOTIFY mode or specifically allocated to another job, it is implicitly allocated by this command. The DLVRY, PGM, and SEV parameters are not contained in the Create Message Queue (CRTMSGQ) command, but default values are assigned to them by the system when the message queue is created. This command can also be used to reset the status of old messages to that of new messages so they can be received again without the use of message reference keys.

 

Restrictions

  1. The user must have *USE and *DLT authorities for the queue.

  2. The message queues being changed cannot be allocated with either a *SHRRD or *EXCL lock by another job. If the queue is allocated by another job when the CHGMSGQ command is attempted, an error message will be sent. One exception to this is that no lock is required when changing the CCSID of a workstation message queue.

  3. If you are changing multiple message queues with the generic support you are not allowed to change the value on the DLVRY parameter to *BREAK or to *NOTIFY.

  4. The QHST message queue has a a message queue full action of *SNDMSG and this value cannot be changed. The CPF2433 message (Function not allowed for system log message queue QHST.) is issued if the message queue full action is changed for QHST.

  5. 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 name of the message queue whose attributes are being changed.

*WRKSTN: The attributes of the work station's message queue are being changed. This parameter is not valid for a batch job.

*USRPRF: The attributes of the message queue associated with the signed-on user profile are being changed.

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

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

*USRLIBL: Only the libraries in the user portion of the job's library list are searched.

*ALL: All libraries in the system, including QSYS, are searched.

*ALLUSR Libraries

library-name: Specify the name of the library to be searched.

*ALL: All message queues in the libraries identified in the library qualifier are changed.

generic*-message-queue-name: Specify the generic name of the message queue whose attributes are being changed. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk (*) is a substitute for any valid character. A generic name specifies all objects with names that begin with the generic prefix for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete object name. If the complete object name is specified and the library qualifier is *USRLIBL, *ALL, or *ALLUSR, all message queues of the specified name are changed.

message-queue-name: Specify the name of the message queue whose attributes are being changed.

 

Optional Parameters

DLVRY
Specifies how the messages sent to this message queue are delivered. The method of delivery is in effect only as long as the message queue is allocated to the job. When the queue is deallocated, the delivery mode is changed to *HOLD for work station, system operator, and user message queues. However, if *DFT is specified for a system operator or user message queue, the delivery mode remains *DFT.

Note: When the delivery mode of a message queue is changed to *BREAK or *NOTIFY, the message queue is allocated with an *EXCL lock. The *EXCL lock will remain on the queue until the delivery mode is changed to *HOLD or *DFT, or the job that contains the lock on the queue ends.

*SAME: The value does not change.

*HOLD: The messages are held in the message queue until they are requested by the user or program. The display station user uses the Display Messages (DSPMSG) command to show the messages; a program must issue a Receive Message (RCVMSG) command to receive a message and handle it.

*BREAK: The job to which the message queue is allocated is interrupted when a message arrives at the message queue, and the program specified in the PGM parameter is called. If the job is an interactive job, the audible alarm is sounded (if installed). The delivery mode cannot be changed to *BREAK if the message queue is also being used by another job.

When changing to *BREAK mode, the PGM parameter defaults to *DSPMSG for the break program and *ALWRPY for allow other jobs to reply if a program name is not specified or if PGM(*SAME) is specified.

*NOTIFY: The job to which the message queue is allocated is notified when a message arrives at the message queue. For interactive jobs at a display station, the audible alarm is sounded and the Message Waiting light is turned on. For batch jobs, no notification occurs; the message is simply held in the queue (the same as for *HOLD). The delivery mode cannot be changed to *NOTIFY if the message queue is also being used by another job.

*DFT: The default reply to the inquiry message is sent. If no default reply is specified in the message description of the inquiry message, the system default reply, *N, is used. The message is not put on the message queue unless the message queue is QSYSOPR.

PGM
Specifies the qualified name of the program called when a message arrives at the message queue and break delivery has been specified. It also indicates whether or not to allow other jobs to reply to messages on the message queue when it is placed in *BREAK delivery mode with a break handling program other than *DSPMSG specified. Because the QSYSOPR message queue receives messages that require manual operator action, only *DSPMSG should be specified or assumed if the message queue being changed is QSYSOPR. The following parameters are passed to the break delivery program:

  • Message queue name (10 characters). The name of the message queue to which the message was sent.

  • Library name (10 characters). The name of the library containing the message queue.

  • Message reference key (4 characters). The reference key of the message sent to the message queue.

    One of the following can be used to specify the name of the break handling program.

Single Values

*SAME: The value does not change, unless the message queue is being changed to break delivery. Then the value is changed to *DSPMSG and the allow other jobs to reply value is set to *ALWRPY.

*DSPMSG: The DSPMSG command is processed when a message arrives for break delivery and the allow other jobs to reply value is set to *ALWRPY. For interactive jobs, the messages are shown on the display. Also, at the display station, the audible alarm is sounded (if these are installed) and the Message Waiting light is turned on. For batch jobs, the message is sent to a spooled printer file.

Element 1: Break Handling Program

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

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. 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 to be searched.

program-name: Specify the name of the program that is called when a message arrives for break delivery.

Element 2: Allow Other Jobs to Reply

Indicates whether other jobs can reply to inquiry messages on the message queue when it is placed in *BREAK delivery mode with a break handling program other than *DSPMSG specified. If *DSPMSG is specified for the break handling program then *ALWRPY is assumed for this attribute. If QMHDSMSS is specified for the break handling program in a library other than QSYS, then *ALWRPY will also be assumed for this attribute unless *NOALWRPY is explicitly specified.

*NOALWRPY: When the message queue is in *BREAK mode with a break handling program other than *DSPMSG specified, other jobs can display the message queue, but cannot reply to inquiry messages on the message queue.

*ALWRPY: When the message queue is in *BREAK mode with a break handling program other than *DSPMSG specified, other jobs can reply to inquiry messages on the message queue.

SEV
Specifies the lowest severity code that a message can have and still be delivered to a user in break or notify mode. Messages arriving at the message queue whose severities are lower than the severity code specified on this parameter do not interrupt the job or turn on the audible alarm or the message-waiting light; they are held in the queue until they are requested by using the Display Message (DSPMSG) command. If *BREAK or *NOTIFY is specified on the DLVRY parameter, and is in effect when a message arrives at the queue, the message is delivered if the severity code associated with the message is equal to or greater than the value specified here. Otherwise, the message is held in the queue until it is requested.

*SAME: The value does not change.

severity-code: Specify severity code, ranging from 00 through 99.

RESET
Specifies whether old messages (messages that have been received once and were not removed from the message queue) held in the message queue are reset to the new message status. The messages can then be received in first-in, first-out (FIFO) order as they were originally. This parameter applies only to messages received by a program; it does not affect message displays. If all messages are being cleared, refer to the RMVMSG (Remove Message) command description.

*NO: Old messages in the message queue are not reset to new message status. To receive an old message, to reply to it, or to remove it, enter the message reference key.

*YES: All messages in the message queue, except inquiry messages that have been sent a reply, are reset to the new message status. These messages can then be received as new messages in the same order that they were sent to the message queue.

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.

*SAME: The value does not change.

*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. This can result in program performance problems.

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

*SAME: The value does not change.

*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. This applies only to immediate messages and message data that is defined as a character field that can be converted (*CCHAR).

*SAME: The value does not change.

*HEX: Messages sent, received, 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 is changed to the CCSID of the job running this command.

coded-character-set-identifier: Specify the CCSID to be 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.

Note: When changing the CCSID of a message queue, the messages on the queue are not converted and the CCSID associated with each individual message is not changed. If the message queue is changed back to *MSG the original CCSID of each message are then used.

Changing the CCSID of a message queue that already has messages on it can cause unpredictable results. This can occur when the encoding of the messages does not match the CCSID you specify. Only change the CCSID of the message queue when the CCSID of a message queue does not match the encoding of the messages on it.

For more information on 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.

*SAME: The value does not change.

*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 is 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 was 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 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 is in Commonly used parameters.

*SAME: The value does not change.

*BLANK: Text is not specified.

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

Examples for CHGMSGQ

Example 1: Changing Method of Delivery to Notify Mode 

CHGMSGQ   MSGQ(JONES)  DLVRY(*NOTIFY)

This command changes the method of delivery of the message queue named JONES to notify mode. The user is immediately notified by the attention light and audible alarm (if installed) when a message has been sent to his queue.

Example 2: Changing Method of Delivery to Break Mode 

CHGMSGQ   MSGQ(INV)  DLVRY(*BREAK)  PGM(INVUPDT)

This command changes the delivery mode of the message queue named INV to *BREAK and calls a program named INVUPDT when a message arrives at INV. Other jobs will not be allowed to reply to inquiry messages on message queue INV.

Error messages for CHGMSGQ

*ESCAPE Messages

CPF2401
Not authorized to library &1.
CPF2403
Message queue &1 in &2 not found.
CPF2406
Authority error occurred on call to break program &1 in &2 for message queue &3 in &4.
CPF2408
Not authorized to message queue &1.
CPF2437
MSGQ(*WRKSTN) not allowed unless done interactively.
CPF244E
The delivery specified is not valid with a generic message queue
CPF2446
Delivery mode specified not valid for system log message queue.
CPF2450
Work station message queue &1 not allocated to job.
CPF2451
Message queue &1 is allocated to another job.
CPF247E
CCSID &1 is not valid.
CPF2477
Message queue &1 currently in use.
CPF2485
Number of parameters for break program &1 in &2 message queue &3 in &4 not valid.
CPF2507
MODE(*NOTIFY) not allowed in batch mode.
CPF2522
Break program &1 in &2 for message queue &3 in &4 cannot be called.
CPF2534
MSGQ(*USRPRF) specified and no msg queue with user profile.
CPF8127
&8 damage on message queue &4 in &9. VLIC log-&7.
CPF8176
Message queue for device description &4 damaged.