MSGCTL command

From m204wiki
Revision as of 01:10, 2 April 2014 by Alex (talk | contribs) (→‎Syntax)
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}.msg-number [msg-option [msg-option]... ] [CLASS={P | I | E}] [RETCODEO=online-retcode] [RETCODEB=batch-retcode]

Where:

M204 specifies a standard Model 204 message.
USER specifies a user message.
msg-number is the four-digit number of the message.
msg-option is one of the following:
MSGCTL command message options

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.

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.

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. The user should 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:

MSGCTL SNAPSEL 6

where n=1

Output all Table A and FCT disk buffers for the current file and no CCATEMP disk buffers.

where n=2

Output all Table B disk buffers for the current file and no CCATEMP disk buffers.

where n=4

Output all Table C disk buffers for the current file and no CCATEMP disk buffers.

where n=8

Output all Table D disk buffers for the current file and no CCATEMP disk buffers.

where n=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.

where n=32

Output all data structures except those which pertain to record locking, resource locking and disk buffers.

where n=64

Output those data structures which pertain to record locking and resource locking.

where n=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 upper case.
CLASS parameters are used on only messages that have been suppressed in an application subsystem (APSY). The CLASS parameters have no effect on messages appearing outside of an APSY. For example, if an APSY suppresses E (error) messages, you can reset the message to I (informational). It will then appear at the user terminal. If both I and E are suppressed, you can reset it to P (prompt) and the message will appear at the terminal.
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, within an APSY for which informational messages are suppressed.
CLASS=E (error) prevents the specified message from being printed at the terminal within an APSY for which error messages are suppressed.
RETCODEO specifies 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 specifies 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 the Model 204 System Manager's Guide for a description of job step return codes. The Model 204 Messages Manual lists the 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 Guide.

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 Messages Manual lists the error number, the text of the message, and the default action that is taken when the event occurs.

Understanding the NOCOUNT option

Caution: Rocket Software strongly recommends that you do not change or suppress the COUNT option that is assigned to some messages. The User Language 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 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.