MSGCTL command

From m204wiki
Revision as of 18:21, 19 December 2017 by JDamon (talk | contribs) (Corrected the example for MSGCTL SNAPSEL 6)
Jump to navigation Jump to search

Setting message output

Summary

Privileges
System administrator
Function
Specifies the actions to be taken when Model 204 produces a particular error or informational message

Syntax

MSGCTL {M204 | USER | MSIR}.msg-number [msg-option [msg-option]... ] [CLASS={P | I | E}] [RETCODEO=online-retcode] [RETCODEB=batch-retcode]

Where:

M204 A standard Model 204 message.
USER A user message.
MSIR A Sirius message.
msg-number The four-digit number of the message.
msg-option One of the following:

Option

Action
AUDITAD Puts the specified message on the audit trail as an AD line.
AUDITER Puts the specified message on the audit trail as an ER line.
AUDITMS Puts the specified error message on the audit trail as an MS line.
AUDITRK Puts the specified message on the audit as an RK line.
COUNT Increments, by one, the message count whenever this message is issued. If the message count exceeds the value of the ERMX parameter, the user's session and processing are stopped.
DUMPALL Dumps the entire Model 204 region. Provides the maximum amount of information for problem determination.
NOACTION Ignores the original option that was assigned the message and returns to main processing.
NOAUDIT Suppresses the auditing of a specific error message. Use with caution, since preventing certain messages from going to the journal could make problem diagnosis more difficult.
NOAUDITAD Puts the specified message on the audit trail as an MS line.
NOAUDITER Puts the specified message on the audit trail as an RK line.
NOAUDITMS Suppresses auditing the specified MS message.
NOAUDITRK Put the specified message on the audit trail as an AD line.
NOAUDITW Suppresses the specified message on Janus Web threads if WEBAUDIT=1. Use with caution, since preventing certain messages from going to the journal could make problem diagnosis more difficult.
NOCOUNT Does not increment, by one, the message count whenever this message is displayed.
NODUMP Does not generate a dump.
NOOPR Does not display the specified message on the operator's console.
NOPREFIX Suppresses the display of the message prefix and number.
NOSAVE Does not save the specified message in the message save table. Note that messages sent to the operator and messages that cause SNAPs are always added to the message save table, regardless of the selection of the SAVE or NOSAVE options.
NOSNAP Suppresses the production of a SNAP when the specified error condition occurs.
NOTERM Does not display the specified message on the user's terminal or for single user jobs in CCAPRINT.

Note: Model 204 passes return codes back in login and logout messages; if you set the NOTERM option for login and logout messages, you cannot get the return code.
NOUP or NOUPPER Reverses the effect of a previous UP option, thus returning the specified message to its original displayed format.
OPR Displays the specified message message on the operator's console.
PREFIX Displays a message prefix (M204 or USER) and message number along with the message.
SAVE Puts a copy of the specified message on the message save table whenever that message is issued. Use the VIEW ERRORS command to examine the saved message.
SNAP SNAP produces the same information as SNAPALL.
SNAPALL The SNAP includes all allocated storage except the Model 204 load module.
SNAPPDL The SNAP includes the registers, module map (alpha and address order), allocated storage map, pushdown list trace, user's server, KOMM, disk buffers containing Model 204 file pages held by the current user (maximum of 4), file directory of current file, and patch information.
SNAPSEL n SNAP includes everything in SNAPPDL as well as other items specified by n. The settings for n can be added together. For example, to output the disk buffers for Tables B and C on a divide by zero error:

MSGCTL M204.0554 SNAPSEL 6

Value of n Result
1 Output all Table A and FCT disk buffers for the current file and no CCATEMP disk buffers.
2 Output all Table B disk buffers for the current file and no CCATEMP disk buffers.
4 Output all Table C disk buffers for the current file and no CCATEMP disk buffers.
8 Output all Table D disk buffers for the current file and no CCATEMP disk buffers.
16 Output the disk buffers requested by the previous settings for all files open by this user and no CCATEMP disk buffers. This setting directs the buffer output and coordinates with one of the previous settings.
32 Output all data structures except those which pertain to record locking, resource locking and disk buffers.
64 Output those data structures which pertain to record locking and resource locking.
128 Output all CCATEMP disk buffers and no Model 204 file disk buffers.
TERM Causes the specified message to be displayed on the user's terminal or for single user jobs in CCAPRINT.
UP or UPPER Forces the specified message to be displayed in uppercase.
CLASS
CLASS=P Resets the message so that it is treated as a prompting message. Since you cannot suppress the printing of prompting messages at the terminal, the message is displayed at the APSY user's terminal.

Note: P does not cause a prompt; it only forces the message to appear at the terminal in an APSY.
CLASS=I (informational) Prevents the specified message from being printed at the terminal if the X'02' bit of the MSGCTL parameter is set. Note that this bit is set within an APSY for which informational messages are suppressed.
CLASS=E (error) Prevents the specified message from being printed at the terminal if the X'04' bit of the MSGCTL parameter is set. Note that this bit is set within an APSY for which error messages are suppressed.
RETCODEO A job step return code in the range 1 to 255 to be associated with the message in Online runs. The actual job step return code is the maximum return code of all messages issued.
RETCODEB A job step return code in the range 1 to 255 to be associated with the message in batch runs. The actual job step return code is the maximum return code of all messages issued.

See Job step return codes for a description and list of job step return codes.

Syntax notes

  • A period, with no space before or after, must be specified between the message prefix, M204 or USER, and the message number.
  • Any number of nonconflicting options can be specified in the MSGCTL command. If conflicting options are specified, for example, PREFIX and NOPREFIX, the option specified last takes effect.
  • You can specify the MSGCTL command before the User 0 parameter line in the CCAIN stream. This lets you format messages displayed during initialization and recovery.
  • The MSGCTL message options — AUDIT, AUDITAD, AUDITMS, AUDITRK — are mutually exclusive. If you enter multiple options for a message, the last option listed is processed.
  • The COUNT option is a separate process and can be used with the AUDIT, AUDITAD, AUDITMS, or AUDITRK option, as needed.

Hierarchical evaluation of message types

The hierarchical structure of messages types is as follows:

  • The NOAUDITER option lowers an ER message to an RK message type.
  • The NOAUDITRK option lowers an RK message to an AD message type.
  • The NOAUDITAD option lowers an AD message to an MS message type.
  • The NOAUDITMS option lowers an MS message, so that it is not audited, as though you had used the NOAUDIT option.

The NOAUDITxx option only processes a message of the xx type. However, NOAUDIT works on any message type.

If NOAUDITxx is specified for a message that is not of type xx, the following message is returned:

M204.1047 NOAUDITxx IS AN INVALID PARAMETER FOR THIS MESSAGE

Example

The following example suppresses the display of the message prefix and number associated with the standard Model 204 password prompt:

MSGCTL M204.0347 NOPREFIX

Usage notes

  • The MSGCTL command lets the system manager change the way Model 204 processes a particular error or informational message. Changes made to a message affect all users in the Online.
  • You can use the MSGCTL command to change processing for either standard Model 204 messages with a Model 204 prefix or for messages with a user prefix developed by the installation. Note that you can also use the MSGCTL parameter to control the display of message prefixes as well as error and informational messages on the user's terminal. User messages are built in the MSGU module distributed with Model 204 and described in the Model 204 installation documentation.
  • Model 204 handles different message event conditions in different ways. For example:
    • A message can be displayed on the operator's console.
    • A message can be displayed on the user's terminal.
    • A message can be written to the journal or audit trail data set.
    • An error can result in the production of a SNAP.
  • For all Model 204 message event conditions, the Model 204 message documentation lists the error number, the text of the message, and the default action that is taken when the event occurs.

Understanding the NOCOUNT option

Attention: Rocket Software strongly recommends that you do not change or suppress the COUNT option that is assigned to some messages. The SOUL compiler depends on using the COUNT option to track errors in your program. If no errors can be reported, your program will seem to compile, only to abend during the run. Also, the lack of messages in your Model 204 journal, audit trail, or other job output can result in the inability to trace and diagnose problems.

How the MSGCTL command can override both the MSGCTL and DEBUGUL parameters

If you use the MSGCTL command, and suppress the display of a message by using the NOTERM keyword, then no matter how the MSGCTL or DEBUGUL parameters are set, the message does not go to the terminal. Conversely, if you want messages displayed at the terminal, enter the MSGCTL command using the following syntax:

MSGCTL {M204 | USER}.msg-number TERM

Understanding the NOACTION option

Error messages have a one-byte indicator that informs message processing whether the message needs to be processed and whether the message has been changed using MSGTL. If a message does not need processing, Model 204 resumes the main processing.

Note: NOACTION has no effect on a restart or a termination message.

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=MSGCTL_command&oldid=104737"