STDEBUG

Read syntax diagramSkip visual syntax diagram STDEBUG subpl(1Options)
Options
Read syntax diagramSkip visual syntax diagramNOOBtainOBtainNOREleasREleaseNOMSGMSGABEndNOAbendRUNSTopNUCNONUCCONsolePUNchvdevUSERID*USERIDuserid ANYSub END ALL FROM0 - ENDFROMRangeINTO0 - ENDINTORange
Range
Read syntax diagramSkip visual syntax diagramhexloc1-:ENDhexloc2.ENDbytecount
Notes:
  • 1 You can enter Options in any order between the parentheses.
    All defaults are for the initial invocation and remain in effect unless changed in a later invocation.

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:
STDEBUG (USERID *
or:
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.
The values hexloc1, hexloc2, and bytecount must be from 1-8 hexadecimal digits. Leading zeros are optional.

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

  1. STDEBUG installs itself as a nucleus extension the first time it is invoked. It may thereafter be invoked as an immediate command.
  2. 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.
  3. 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:

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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

  1. 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
  2. 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