SET TRAPMSG
Authorization
General User
Purpose
Use the SET TRAPMSG command when a CMS problem is encountered that cannot be explained and it is necessary to capture a sequence of events when a particular message ID occurs. The SET TRAPMSG command is set to indicate which message should cause a trap to spring, and optionally, to specify how much storage to dump.
The message trap can be activated by issuing SET TRAPMSG ON with the respective message ID and dump range. It can be used whenever a message is received that needs further explanation or debugging to find the cause of the message. SET TRAPMSG should generally be used only when contact of a support group for further analysis is necessary. For example, use the SET TRAPMSG command to cause a VMDUMP to be taken when the specified message ID is displayed.
Operands
- ON
- Turn the message trap on.
- OFF
- Turn the message trap off.
- msgid
- The msgid operand must be in this
xxxmmm####s format. Where:
- xxx
- specifies the prefix or application identifier. For example, DMS, is a three character alphanumeric string therefore, the first character must be alphabetic.
- mmm
- specifies the module code (a three character alphanumeric string; other valid characters that can indicate which module generated the message are $, #, @, +, –, :, and _). ‘???’ can be used as the wild card or the place holder.
- ### or ####
- specifies the message number.
- s
- specifies the severity code. A ‘?’ can be used as a wild card or a place holder.
- msgno
- The message number is a 1-4 digit decimal number, ranging from 0-9999. If you choose to specify
this format, an example of the message header might look like
DMS??? ###?
orDMS??? ####?
. ‘?’ means wild card. - hexloc1
- 0
- The hexloc1 operand is the starting virtual storage address dumped. If the value you specify for hexloc1 is not a multiple of 4 kilobytes (KB), the control program (CP) will round the hexloc1 specified down to a 4KB boundary. If you omit the hexloc1 operand, the default is zero. You may also specify hexloc2 with the hexloc1 operand. hexloc1 has to be in the range of your virtual machine and it cannot be greater than the hexloc2.
- :
- –
- are symbols used with hexloc1 and hexloc2 to define the virtual storage address range to be dumped.
- hexloc2
- END
- The hexloc2 operand is the ending virtual storage address dumped. hexloc2 has to be in the range of your virtual machine and it cannot be less than hexloc1. If the value you specify for hexloc2 is not equal to the starting location (hexloc1) and is not a multiple of 4KB, CP will round the hexloc2 up to the next 4KB boundary. If you do not specify the hexloc2 operand, the default is END, which is vmsize-1. vmsize is the defined size of the virtual machine.
- FORmat *
- FORmat nn
- Specifies a one or two digit format number. This identifies different versions of the message text that have the same message number. The formats are numbered from 1-99. The default is *, which means any format number. A format of zero is not allowed.
- RUN
- STOP
- The STOP option stops CMS and goes to CP when the message trap springs, but before the dump is
generated. This allows you to examine storage, set a trace, or do other CP commands after the
message trap springs. Enter a
B
to take the dump and resume processing. The default is RUN. The STOP option will place the virtual machine into CP READ mode after a message trap springs. - NODCSS
- DCSS
- Specifies CP takes a dump of all the user discontinuous saved segments not within user storage. If the user has DCSSs that are wholly within user storage, these are not added to the dump in response to the DCSS option. If a DCSS is partly within user storage and partly outside, only those segments outside user storage are dumped in response to this option. The default is NODCSS.
- TO *
- TO userid
- Transfers the dump to the virtual card reader of the specified user ID. If you enter an asterisk (*) after the keyword TO, or do not specify the TO at all, the system sends the dump to the virtual card reader of the virtual machine you issued the SET TRAPMSG command from. The default is TO *.
- NODATaspace
- DATaspace
- This option dumps SFS data space storage associated with the VM user ID. This option only applies to CMS SFS data space. The default is NODATASPACE.
- REPlace
- NOREPlace
- Specify REPLACE to replace an existing message trap. If REPLACE is not specified and a message trap is already active, an error message will be issued. The default is NOREPLACE.
Usage Notes
- The default dump range is ‘0 to vmsize-1’ unless specified upon invocation.
- If only one address is specified for the dump range, it will be set as the starting dump range. The ending dump range will be set to vmsize-1.
- The message trap will stay active even after a trap is sprung and dumps have been taken. Issue
SET TRAPMSG OFF
to turn the message trap off. - Attention: If the default dump range is used (0 to vmsize-1) and the user's machine is large, or if the user has a large data space or saved segment, the spool space may be depleted, which will cause a system malfunction.
- Only one message trap can be active. An error message will be issued if a trap is already active and a user enters another SET TRAPMSG command without specifying the REPLACE option.
- The dump will generate a VMDUMP format spool file when the trap springs. The type of virtual machine being dumped is CMS. The dump can be viewed through the Dump Viewing Facility.
- The operation of SET TRAPMSG is not dependent on the setting of EMSG and it does not affect the setting of EMSG.
- This command can also be used to trap messages in the user's application by way of APPLMSG and XMITMSG.
- This command does not work if the message header was included in the text string by way of APPLMSG with the TEXT or TEXTA option.
- If either DATASPACE, DCSS or both options are specified, the dump for the data space storage and DCSS storage will be combined into one with the primary dump.
- Only messages in the CMS system or user repository can be trapped.
- The STOP option will stop CMS and go to CP when the message trap springs. No dump has been taken yet when going into CP.
- If you are running in the batch mode, do not set the STOP option; it will be ignored.
- The default setting for TRAPMSG is OFF.
- If the dump fails, see DIAGNOSE X'94' in z/VM: CP Programming Services.
Limitations of SET TRAPMSG
Only one message can be trapped at a time. In some cases, a group of messages may be received, but only one of the messages can be trapped at once.
Replacing a Message Trap
To replace a message trap, use the same command described above by incorporating the REPlace option.
Turning Off a Message Trap
To turn off a message trap, issue SET TRAPMSG OFF
. Additionally, when you re-IPL
or log off the virtual machine any previous message trap setting will no longer be in effect.
Querying a Message Trap
To find out whether a message trap has been set, issue the QUERY TRAPMSG command. It will respond with either the message ID that was set with the dump range or a suitable message indicating no message trap is currently set. For more information, see QUERY TRAPMSG.
Obtaining a Dump Triggered by a Message
Once a message trap has been set, the situation that forces the message to occur should be recreated for the Dump to automatically be taken. The dump file will be a standard VMDUMP format spool file placed in the user's or user ID's reader (specified in the command input through the TO option). The dump file can be read into the user's virtual machine with the DUMPLOAD utility. It can then be printed, transferred to another virtual machine, and discarded.
Performance
Because message trap will be checked every time a message is issued from the CMS message facility, system response time may be adversely affected.
Responses
(possible when message trap is triggered)
DMS1297I Dump failed; DIAGNOSE X'94' returns condition code = cc; return code = rc |
DMS1297I Dump has been taken |
DMS1297I Dump failed; DIAGNOSE X'94' returns condition code = cc; return code = rc |
DMS1297I Dump has been taken |
DMS2047I TRAPMSG dump started; please wait |
DMS2047I TRAPMSG dump started for data space: ASIT = xxxxxxxxxxxxxx; please wait |
Messages and Return Codes
- DMS065E option option specified twice [RC = 24]
- DMS066E option and option are conflicting options [RC = 24]
- DMS095E Invalid address address [RC = 24]
- DMS149E Userid userid not valid [RC = 32]
- DMS771E Invalid message header [RC = 24]
- DMS771E Invalid message number [RC = 24]
- DMS2053E Address range addr1-addr2 is not completely within your virtual machine [RC = 24]
- DMS2054E Message trap already active; specify REPLACE option [RC = 28]
- DMS2055I STOP option ignored for TRAPMSG command
- DMS2516E Invalid address range: addr1-addr2, start greater than end [RC = 24]