USTOR - Storage Display Utility (Control User)

Using the USTOR utility program, you can:

• Display virtual storage;

• Alter contents of virtual storage;

• Monitor storage modifications by system tasks;

• Scan storage for a given character string;

• Display Com-plete internal buffer usage;

This section describes the techniques for using the USTOR utility program to perform the functions outlined above.

This document covers the following topics:

• Command Format

• Main Storage Display

Command Format

Initial access to USTOR is gained by entering the call request:

*USTOR 

Entry of this call request establishes communication with the USTOR utility program. Once communication is established, the USTOR commands and functions are available for use.

Note that USTOR is fully conversational, that is, the functions can be entered any time after USTOR has been initiated. The USTOR functions may also be invoked at the time USTOR is initially invoked with the command format:

*USTOR function 

If more than one function is applicable to the display desired, multiple functions can be entered when USTOR is invoked. In this situation, the function codes must be separated by commas.

Main Storage Display

If you initially invoke the USTOR utility without arguments, a display of the contents of main storage in hexadecimal format is generated, beginning at location zero. The following figure illustrates a typical display of the contents of main storage.

KEY=0 FETCH REF CHG PAGE-PROTECTED
00000000  040C0000  81099500  00000000  00000000  *    a n        *
00000010  00FCD590  00000000  070C1000  8100F89E  *  N-       a 8-*
00000020  070C0000  000B272C  040C0000  8109F470  *           a 4 *
00000030  00000000  00000000  070E0000  00000000  *               *
00000040  00000000  00000000  00000000  00FCD590  *             N-*
00000050  00000000  00000000  040C0000  81096D18  *           a - *
00000060  040C0000  00BE9F60  000C0000  817A9680  *      --   a:0-*
00000070  00080000  817A9040  040C0000  80FE2080  *    a:-    -  -*
00000080  00000000  00021202  00040101  00040016  *               *
00000090  008CD000  00000000  00000000  00000000  * -             *
000000A0  00000000  00FFF8D8  00000000  00000000  *      8Q       *
000000B0  00000000  00000000  00010026  00FCF2E8  *             2Y*
000000C0  00000000  00000000  00000000  00000000  *               *
000000D0  00000000  00000000  00000000  00000000  *               *
000000E0  00000000  00000000  00000000  00000000  *               *
000000F0  00000000  00000000  00000000  00000000  *               *
00000100  00000000  00000000  00000000  00000000  *               *
00000110  00000000  00000000  00000000  00000000  *               *
00000120  00000000  00000000  00000000  00000000  *               *
00000130  00000000  00000000  00000000  00000000  *               *
00000140  00000000  00000000  00000000  00000000  *               *
00000150  00000000  00000000  00000000  00000000  *               *

Note the following:

• The default display is in interpretive mode;

• The default display is the number of lines defined in the TIBTAB for this terminal less one. Normally, the default display is 23 lines for a 3277 model 2;

• Hexadecimal main storage addresses are given in the left-most margin;

• The key of the storage location addressed is given in the first data line display.

Main Storage Addressability Features

Once the main storage display is obtained, there are several USTOR features that enable you to address main storage locations. The following table summarizes the main storage addressability features and lists the corresponding commands, where applicable:

Contents Feature

Indirect addressing is accomplished by use of the contents feature. This feature refers to a location in storage and uses the 24-bit contents at that location as the main storage address to be displayed. The format is:

C(nnn)

To display the contents of a 31-bit address in storage use the format:

X(nnn)

where the character C must be entered and the parentheses must be entered as illustrated. Users who wish to access a 31-bit address indirectly should note that X must be entered instead of C in the following examples. The variable within the parentheses must be one of three items:

• A main storage address - C(2A0) uses the fullword found at location X'2A0' as the address of main storage to be displayed. X(2A0) indicates that the address found at location X'2A0' will be treated as a 31-bit address.

• An address relative to the current location - C(+16) uses the fullword found at the current location plus 16 (decimal) as the address of main storage to be displayed. If the fullword found at current location plus 16 (decimal) is to be treated as a 31-bit address, X(+16) should be used.

• An asterisk - C(*) uses the fullword found at the current location as the main storage address to be displayed. X(*) must be used if the fullword at the current location is to be treated as a 31-bit address.

Cursor Addressing Feature

By positioning the cursor to any byte within the main storage display and pressing ENTER, the display is scrolled forward, moving the indicated byte to the top of the screen.

Displacement Feature

Displacement addressing means displaying main storage at an address relative to the currently displayed location. This is accomplished by entering a plus (+) for positive displacement or a minus (-) for negative displacement along with one of the following additional features with each display request:

• A number indicating the desired displacement. Note that this number must be preceded by an "X" if it represents a hexadecimal number; otherwise, it is treated as a decimal number.

• A "P" or "H" to increment or decrement the current display by a full page or half a page, respectively.

For example, entering +234 would display main storage at relative location +234 from the currently displayed address. Entering -X2C8 would display main storage at relative location -X2C8 from the currently displayed address.

Mode Feature

The mode feature determines the display characteristics to be generated by USTOR. Three primary display characteristics are available. Each is determined by entering the mode command function to obtain the desired characteristic.

The mode command functions are:

L	Determines the number of lines to be written for each display.
HEX	Gives the display in machine internal hexadecimal mode only.
INT	Gives the display both in hexadecimal and character translation modes.

• The L mode function:
  is convenient for restricting the number of lines displayed at the terminal. If the terminal in use is not a 3277-type terminal, it may be preferable to change the number of lines in the display. The function may be entered either when USTOR is invoked or any time thereafter.

• The HEX function:
  generates a display in machine internal hexadecimal format only. The hexadecimal addresses that appear in the left margin are in increments of X'20' (decimal 32).

• The INT mode function:
  generates a display in both internal machine hexadecimal format and external translated format. The output is the same basic display as that obtained with the HEX function except that the storage addresses are in increments of X'10' (decimal 16) and the character mode is displayed, line for line, to the right of the hexadecimal display. Note that non-displayable characters are translated to blanks.

Note that the INT display mode is the default when USTOR is invoked.

Paging Feature

After USTOR is invoked, the initial display is the default hexadecimal display of main storage beginning with location 0. Pressing ENTER causes a continuation of the display with the next logical address. The first page of a typical main storage display is illustrated previously in this section. The number of lines or addresses displayed depends upon the line mode used (L, HEX, or INT). Specific locations within the main storage can be addressed directly or indirectly.

Since the type of terminal determines the number of lines to be displayed, the next logical address is in increments based upon the last address in a given display.

Register Feature

Register addressability is the ability to save an address in a USTOR storage area called a register and subsequently display the memory located at that address by referring to the contents of the register. USTOR provides 10 registers (0 through 9) to store addresses.

Specified Address Display Feature

A specific address can be displayed by entering the desired address as a one- to eight-digit character string:

xxxxxxxx

where xxxxxxxx is the desired address.

Note that the address represented by xxxxxxxx is interpreted as a hexadecimal address. Entry of value 80 means an address equivalent to X'80', not decimal 80.

The desired address can be entered either when USTOR is invoked or any time thereafter.

USTOR Commands

In addition to the functions mentioned earlier in this section relating to main storage addressability, USTOR performs other types of functions.

The USTOR functions are invoked by entering the appropriate command. The following table summarizes the available commands.

You can also enter these commands as part of the USTOR invocation sequence or any time thereafter.

Detailed descriptions of each command, its function, format, and features follow below.

AM Command

One to eight bytes of virtual storage acn be altered via the USTOR utility program with the command:

AM address data 

where the arguments are:

address	Specifies a one- to eight-digit hexadecimal number representing the address of the memory location to be modified. Note that the address of the currently displayed memory location must be the same as this address.
data	Specifies the hexadecimal character string to be placed in the memory location specified by the address argument.

For example, the command:

AM 0002C5 1A2A 

alters the two bytes of storage located at 0002C5 to 1A2A. Note that the AM operation is executed in this case only if the currently displayed address is 0002C5.

ASU Command

The ASU command displays the amount and percentage of used and free virtual storage in the Com-plete address space, separately for storage below and above the 16MB line.

z/VSE:

ASU xx (xx = PartitionId) displays these values for the corresponding partition.

ASU ALL displays the values for the home partition plus additional information about dataspaces and 64-bit storage allocations

BFS Command

The BFS command displays the usage of internal buffers. The display provides location, size, and usage rate. The command format is:

BFS 

The following figure illustrates a typical display resulting from this command.

BUFFER NAME LOCATION SIZE FREE %FREE DIFF RESIDENT PGMS 94578BC0 006B3D10 ( 6864K) 00000000 ( 0K) 0.0 0.0 TIBTAB 12A46000 00003C00 ( 15K) 000039C0 ( 14K) 96.2 + 96.2 NUCLEUS 00008000 000672B8 ( 413K) 00000000 ( 0K) 0.0 0.0

BUMP and NOBUMP Commands

The BUMP command causes the currently displayed address to be bumped to the next logical address in memory whenever either the ENTER key is pressed or the LOOP command is in effect. Note that the invocation of USTOR automatically sets the BUMP mode of operation. The command format is:

BUMP 

The NOBUMP command causes the currently displayed address to remain the same whenever either ENTER is pressed or the LOOP command is in effect. The command format is:

NOBUMP 

COMREG Command

The COMREG command causes a display of the Com-plete Communications Region. The command format is:

COMREG 

CVT Command (z/OS only)

CVT stands for the operating system Communications Vector Table. This table is the center of control for operating system functions and is frequently referenced by system maintenance personnel. The CVT command causes a memory display beginning with the memory location of the CVT. The command format is:

CVT 

GETVIS Command (z/VSE only)

The GETVIS command causes a display of free storage in the Com-plete partition. The command format is:

GETVIS 

HEX Command

The HEX command causes the current display to be given in full, internal, hexadecimal format, 32 characters to a line. The address in the left margin, also in hexadecimal, is in increments of X'20' (decimal 32). The command format is:

HEX 

INT Command

The INT command causes a memory display where each line of the display consists of the hexadecimal address of the data in the line, 16 characters in internal hexadecimal format, and the translated external format of the same 16 characters. Note that all non-displayable characters are translated to blanks. The command format is:

INT 

L Command

The L command sets the number of lines to be displayed after a USTOR command is entered. For 3277 model 2 terminals or their logical equivalent, the default number of lines is 23. For hard copy terminals, the default number of lines is one. The L command format is:

L=nn 

where nn is any two-digit integer that specifies the number of lines to be displayed.

LOOP and NOLOOP Commands

The LOOP and NOLOOP commands monitor storage modifications being made by system tasks or application programs. The LOOP command causes USTOR to display memory dynamically; NOLOOP terminates the LOOP facility.

LOOP and NOLOOP are normally used in conjunction with the BUMP and NOBUMP commands. If NOBUMP and LOOP are entered, the same memory location is displayed repeatedly. The format of the LOOP command is:

LOOP 

Note that the display is at I/O response time intervals; no timer facility is provided.

Termination of the LOOP command is caused by an external interrupt from the terminal. To cause this interrupt, press ENTER or power off the terminal.

Note:
If you press ENTER to cause an external interrupt to terminate the LOOP command, you must also enter the NOLOOP command; if not, pressing ENTER a second time causes the LOOP command to become effective again.

The NOLOOP command causes the LOOP command to be ignored. This command is normally entered immediately after termination of the LOOP command (by an external interrupt). The format of the NOLOOP command is:

NOLOOP 

Note that this command has no effect if the LOOP command has not been entered.

LUBS Command (z/VSE only)

The LUBS command displays storage beginning at the LUBs (Logical Unit Blocks) in the partition in which Com-plete is running. The command format is:

LUBS 

This command may be entered either when USTOR is invoked or at any time thereafter.

PARTCR Command (z/VSE only)

The PARTCR command enables the display of the Com-plete z/VSE Partition Communication Region. The command format is:

PARTCR 

PIBS Command (z/VSE only)

The PIBS command displays storage beginning at the PIB (Partition Information Block) table. The command format is:

PIBS 

PUBS Command (z/VSE only)

The PUBS command displays storage beginning at the PUB (Physical Unit Block) table. The command format is:

PUBS 

R Command

USTOR maintains a set of internal storage areas called registers. These registers (0 to 9) are available for the storage of addresses and can be referred to later for recall of the same addresses. The R command permits you to store an address in a given register and, if USTOR does not terminate, recall that address for display purposes. The command format is:

Rn=* 

where the variable n, an integer from 0 to 9, designates in which register to store the desired address. Note that the address to be stored in the designated register is the address currently being displayed. The items R, =, and * must be entered as shown.

If USTOR is not terminated, an address stored in a register can be recalled by entering the command:

Rn 

where n is the integer (0 to 9) that designates the register containing the desired address. The memory location with the address specified in register n is displayed.

S Command

The S command enables the scanning of virtual storage for a specified hexadecimal value. The command format is:

S xxxx 

where xxxx is a one- to four-byte hexadecimal character string (two- to eight-hexadecimal digits). You can specify one of the following formats:

S xxxx	Scan forward, byte by byte, for a value "equal" to the specified character string.
S Xxxxx	Scan forward, byte by byte, for a value "not equal" to the specified character string.
S xxxx(+n)	Scan forward, n bytes at a time, for a value "equal" to the specified character string.
S xxxx(-n)	Scan backward, n bytes at a time, for a value "equal" to the specified character string.
S Nxxxx(+n)	Scan forward, n bytes at a time, for a value "not equal" to the specified character string.
S Nxxxx(-n)	Scan backward, n bytes at a time, for a value "not equal" to the specified character string.
S	Repeat the previous scan request beginning with the current address.

Note that the optional n argument represents any decimal integer.

SYSCOM Command (z/VSE only)

The SYSCOM is the system control program's communication area for z/VSE. This area controls the operating system functions and is frequently referenced by system maintenance personnel.

The SYSCOM command causes a memory display beginning with the memory location of the system COMREG. The command format is:

SYSCOM 

TCBS Command (z/OS only)

The TCBS command obtains a formatted display of the operating system TCB chain. The command format is:

TCBS nnn 

where the variable nnn is used in one of the following options:

null	Display all TCBs.
n	Display all TCBs beginning with the n th TCB. Note that n is any integer from 0 to 99.
P	Display all user (partition) TCBs.
Pn	Display all user (partition) TCBs beginning with the n th user TCB. Note that n is any integer from 0 to 99.

The number of lines in each display is determined by the L command; therefore, if all system TCBs are requested in a display, a maximum of 24 are displayed with a 3277 model 2 terminal.

In z/OS only the TCBs that are within the Com-plete address space are displayed.

The following figure illustrates a typical display of the first page of an operating system TCB chain.

TCBAD PKEY MOTHER TCBRBP FREE JOB STEP PROCSTEP LOPART HIPART #K 8FDE40 000000 8FDAD8 MSTJCLJ2 JES2 8FD080 8FDE40 8FFCC8 MSTJCLJ2 JES2 8FFD70 8FDE40 8FFAB8 COM440 COM440 8E9E88 8FFD70 8FF038 COM440 COM440 8E9CF0 8E9E88 8FF7A0 COM440 COM440 8E9AC0 8E9E88 8E9A00 COM440 COM440 8E9868 8E9E88 8E97A8 COM440 COM440 8E9610 8E9E88 8E9550 COM440 COM440 8E92A0 8E9E88 8FF130 COM440 COM440 8E90F0 8E9E88 8E9030 COM440 COM440 8DFE88 8E9E88 8DFD88 COM440 COM440

TCWS Command

For each system task created by Com-plete at initialization time, a Transaction Control Word (TCW) is maintained in memory to record the status of each task.

The TCWS command displays the TCW control blocks at the terminal. The command format is:

TCWS 

TIB Command

The TIB command displays a designated terminal information control block. The command format is:

TIBn 

where n is an integer designating the Terminal Identification number of the terminal whose information control block is to be displayed.

TRACE Command

The TRACE command displays the Com-plete internal trace table. The command format is:

TRACE 

UCB Command (z/OS only)

The UCB command displays a designated Unit Control Block (UCB). The command format is:

UCB cuu 

where cuu is the channel number and unit number (CUU) for the UCB to be displayed.