STDEBUG
Authorization
General User
Purpose
Use the STDEBUG command to monitor CMS storage management activity (OBTAIN and RELEASE requests) within your virtual machine. You can invoke STDEBUG multiple times, with each invocation building on the previous one. For more information, see Usage Note 3.
Operands
- subpl
- specifies you want storage calls for storage in this subpool or these subpools to be traced.
Subpool names can be from 1-8 characters, cannot contain blanks or nondisplayable characters, and are case sensitive. Use the ALL option to display information on subpools with names you can't directly specify. For subpool names containing nonblank, nonprintable characters, pass the names from a program using the extended plist. For more information about how to do this, see z/VM: CMS Application Development Guide for Assembler.
Options
- OBtain
- applies the traps specified by INTO, FROM, and the list of subpool names to requests to obtain
free storage such as:
- CMSSTOR OBTAIN
- DMSFREE
- GETMAIN
- NOOBtain
- does not apply the traps specified by INTO, FROM, and the list of subpool names to OBTAIN requests.
- RElease
- applies the traps specified by INTO, FROM, and the list of subpool names to requests to release
free storage such as:
- CMSSTOR RELEASE
- DMSFRET
- FREEMAIN
Whenever a SUBPOOL RELEASE or SUBPOOL DELETE is issued, the UNALLOC function is displayed instead, indicating how the storage was released.
- NOREleas
- does not apply the traps specified by INTO, FROM, and the list of subpool names to RELEASE requests.
- NOMSG
- suppresses storage management error messages if the caller to storage management specified MSG=NO on the macro invocation. NOMSG is the default on the initial invocation of STDEBUG.
- MSG
- displays all suppressed error messages, even if the caller to storage management specified MSG=NO.
- ABEnd
- performs ABEND processing on error conditions when ERROR= ABEND was specified on the macro invocation. ABEND is the default on the initial invocation of STDEBUG.
- NOAbend
- means do not perform ABEND processing on error conditions even if ERROR=ABEND was specified on the macro invocation. Instead, return control to the caller as if ERROR=* had been specified on the invocation.
- RUN
- continues processing generally, and does not place the virtual machine into CP READ after storage management messages have been issued. RUN is the default on the initial invocation of STDEBUG.
- STop
- places the virtual machine into CP READ after a Storage Management trace or error message has
been displayed.
If you specify STOP without specifying MSG, you may go into CP READ with no indication why. This is because the caller to storage management specified MSG=NO on the call, and you did not specify MSG on STDEBUG to override that setting. Therefore the message is suppressed when you enter CP read, as requested by STOP.
- NUC
- includes calls from the CMS nucleus in the trace. These calls are bounded by NUCALPHA on the low end and NUCOMEGA on the high end, and they must also fall within the specified FROM range. NUC is the default on the initial invocation of STDEBUG.
- NONUC
- does not include calls from the CMS nucleus in the trace, even if they fall within the specified FROM range.
- CONsole
- displays trace messages as CP messages. CONsole is the default on the initial invocation
of STDEBUG. Note: STDEBUG uses CP messages for output. Do not use the console as the output device when an application connected to the *MSG or *MSGALL CP system services is executing. The external interrupts caused by the CP messages generated by STDEBUG in themselves cause calls to Storage Management, which are then trapped and cause more messages to be issued.
Direct messages to an alternate user ID with the USERID option or to another device with the PUNCH option.
STDEBUG does not issue messages to the console when SET FULLSCREEN is ON, unless they are being directed to a different user ID (with the USERID option) than the one being traced.
- PUNch vdev
- writes the trace data to the unit record output device specified by
vdev.
The device specified by vdev can be any valid unit record output device; it does not have to the standard CMS devices, such as X'D' for the punch or X'E' for the printer. This allows you to use devices that do not conflict with those being used by the application you are tracing.
- USERID userid
- directs the CP messages, generated when the CONSOLE option is specified, to the alternate user
ID specified by userid. The initial value of USERID is the virtual machine
invoking STDEBUG. You can reset it to this original value any time by issuing:
or:STDEBUG (USERID *
STDEBUG (END
- FROM range
- traps only the calls to storage management where the address of the call is within the specified
range. (If any byte of an address is within the range, the address is considered to be within the
range.) A range may be a single address, a pair of addresses separated by a
-
or:
, or an address followed by a period and a byte count. You may also specify END after the delimiter to include storage from the starting address to the end of the virtual machine.- hexloc1
- is the starting address of the range.
- hexloc2
- is the ending address of the range.
- bytecount
- is the number of bytes to be mapped.
Blanks are not allowed within a range specification, but each range must be separated from the other ranges by one or more blanks. X'0-END' is the default on the initial invocation of STDEBUG.
- INTO range
- traps only the calls to Storage Management where the storage being obtained or released falls within the specified range. For more information on the valid ranges, see the preceding description of the FROM operand. X'0-END' is the default on the initial invocation of STDEBUG.
- ANYSub
- resets a previous specification of a list of subpool names, and base the tracing of obtain and release calls on the current setting of FROM and INTO for any subpool. ANYSUB is the default on the initial invocation of STDEBUG.
- END
- ends and resets all tracing of calls to Storage Management.
- ALL
- traces all calls to storage management for any subpool or address range. Specifying STDEBUG (ALL
is the same as specifying:
STDEBUG (OB RE ANYSUB RUN MSG NUC CON INTO 0-END FROM 0-END
Usage Notes
- STDEBUG installs itself as a nucleus extension the first time it is invoked. It may thereafter be invoked as an immediate command.
- Calls invoked from assembler language programs by SVC 202 or CMSCALL must provide both an extended and tokenized plist. If the extended plist is not available, an error will occur.
- STDEBUG may be invoked multiple times. Each time, previously specified options may
be changed or new options may be specified that are added to the previous options.
Specifying an option over its opposite on a previous invocation overrides the previous setting.
Specifying an option over the same setting on a previous invocation maintains the setting.
The END and ALL options also set other options to certain values invoked on top of previous invocations, resetting them if necessary:- END
- sets values NOOBTAin, NORELEase, NOMSG, ABEND, RUN, NUC, CONSOLe, USERID, FROM, INTO, and ANYSUB.
- ALL
- sets values OBTAin, RELEase, MSG, RUN, NUC, CONSOLe, FROM, INTO, and ANYSUB.
Examples
The following example shows 5 invocations of STDEBUG, one after another, with explanation in each step of how each subsequent invocation builds on or changes the previous one:
-
STDEBUG (OB myprog
The first call traces only obtain requests. As this is the first invocation of STDEBUG, the tracing would be for storage in the address range of X'0-END' and a caller range of X'0-END'. In addition, the tracing would be to the virtual console and the user ID is the invoker of STDEBUG. It traces any subpool.
-
STDEBUG (RE INTO 20000-30000 myprog
The second call does not change the tracing of obtain requests and adds the tracing of release requests. It also limits tracing to only storage within the specified address range.
-
STDEBUG NUCLEUS (PUN D myprog
The third call does not change anything previously set, but it restricts the tracing to only calls for the NUCLEUS subpool. In addition, the tracing is now directed to the punch rather than the console.
-
STDEBUG USER XYZ myprog
The fourth call traces the USER and XYZ subpools instead of the NUCLEUS subpool. All tracing of the NUCLEUS subpool ends. The previous punch and address specifications remain in effect.
-
STDEBUG (ANYSUB CON INTO 0-END myprog
The fifth call resets the tracing to any subpool rather than just the USER and XYZ subpools, and would direct the tracing back to the console rather than the punch. In addition, the address range specified traces storage within the entire virtual machine.
Responses
- Format of the trace information directed to the virtual console with the CONSOLE option:
(1) (2) (3) (4) (5) 08:40:07 * MSG FROM FRODO: OBTAINED 00000510 013FEA38 DMSXEDIT 00ED3D9E 08:40:07 * MSG FROM FRODO: OBTAINED 000002A8 013FB000 DMSXEDIT 00EBC19E 08:40:07 * MSG FROM FRODO: OBTAINED 00000168 013FBE98 DMSXEDIT 00EBC27E 08:40:07 * MSG FROM FRODO: OBTAINED 00003DD8 013EA000 DMSXEDIT 00EC8CE6 08:40:07 * MSG FROM FRODO: OBTAINED 00000800 013FF6C8 DMSBLOKN 00E2AE78 08:40:07 * MSG FROM FRODO: RELEASED 00000800 013FF6C8 DMSBLOKN 00E28F0C 08:40:16 * MSG FROM FRODO: UNALLOC 00001000 00DED000 DMSXEDIT 00EBE9D6 08:40:16 * MSG FROM FRODO: UNALLOC 00001000 013FE000 DMSXEDIT 00EBE9D6
Where:- (1)
- is the name of the event: OBTAINED, RELEASED, or UNALLOC
- (2)
- is the number of bytes obtained or released
- (3)
- is the address of the storage being obtained or released
- (4)
- is the name of the subpool that owns the storage
- (5)
- is the address of the caller to storage management
- Format of the trace information directed to a unit record device with the PUNCH option:
08:52:09 OBTAINED BYTES=000000B8 ADDR=013FEF48 SUBPL=DMSXEDIT CALLER=00EBA162 08:52:09 OBTAINED BYTES=00000780 ADDR=013FC880 SUBPL=DMSXEDIT CALLER=00EBD846 08:52:09 OBTAINED BYTES=00000510 ADDR=013FEA38 SUBPL=DMSXEDIT CALLER=00ED3D9E 08:52:09 OBTAINED BYTES=000002A8 ADDR=013FB000 SUBPL=DMSXEDIT CALLER=00EBC19E 08:52:09 OBTAINED BYTES=00000168 ADDR=013FBE98 SUBPL=DMSXEDIT CALLER=00EBC27E 08:52:09 OBTAINED BYTES=00003DD8 ADDR=013EA000 SUBPL=DMSXEDIT CALLER=00EC8CE6 08:52:09 OBTAINED BYTES=00000800 ADDR=013FF6C8 SUBPL=DMSBLOKN CALLER=00E2AE78 08:52:09 RELEASED BYTES=00000800 ADDR=013FF6C8 SUBPL=DMSBLOKN CALLER=00E28F0C 08:52:10 OBTAINED BYTES=00000008 ADDR=013FFEC0 SUBPL=DMSBLOKN CALLER=00EDA550 08:52:10 RELEASED BYTES=00000008 ADDR=013FFEC0 SUBPL=DMSBLOKN CALLER=00E0E47E 08:52:10 UNALLOC BYTES=00001000 ADDR=00DED000 SUBPL=DMSXEDIT CALLER=00EBE9D6 08:52:10 UNALLOC BYTES=00001000 ADDR=013FE000 SUBPL=DMSXEDIT CALLER=00EBE9D6
Messages and Return Codes
- DMS389E Invalid device address: device [RC=24]
- DMS2513E Extended plist is required. [RC=24]
- DMS2516E Invalid address range: addr1-addr2, start greater than end. [RC=24]
- DMS2518E Error, RC=nn from STDEBUG initialization[RC=rc]
- DMS8503E Invalid STDEBUG parameter list. [RC=24]
Return codes:
- RC
- Meaning
- 99
- STDEBUG was invoked on an unsupported level of CMS.
Additional system messages may be issued by this command. The reasons for these messages and their location are:
Reason | Location |
---|---|
Errors in command syntax | Command Syntax Error Messages |