STORMAP

Range

Options

Notes:

¹ You can enter Options in any order between the parentheses.
² This default can change when other options are specified.
³ For use with REXX and EXEC 2 only.

Authorization

General User

Purpose

Use the STORMAP command to map the storage within your virtual machine.

Operands

range

specifies one or more address ranges to be included in the map. (If any part of a storage block falls within the range, the storage block 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. The 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.

Options

SUM

writes STORMAP summary data to the output devices. This data includes:

VMSIZE: The size of your virtual machine in bytes.
NUCALPHA: The address of NUCALPHA, which is the starting address of the CMS nucleus.
NUCSIGMA: The address of NUCSIGMA, which is the end of executable code within the CMS nucleus and the start of the index to the message repository. The saved S- and Y-STATs are stored above the message index.
NUCOMEGA: The address of NUCOMEGA, which is the end of the CMS nucleus area.
NUCALPHA and NUCOMEGA mark the starting and ending addresses of the Named Saved System when CMS is IPLed by system name.
NUCPHI: The start of CMS nucleus storage above the 16MB line.
NUCCHI: The end of used CMS nucleus storage above the 16MB line.
TOLT16MB: Total free storage on the unallocated free storage queue below the 16MB line.
LGLT16MB: The size of the largest block of contiguous free storage on the unallocated free storage queue below the 16MB line.
TOGT16MB: Total free storage on the unallocated free storage queue above the 16MB line.
LGGT16MB: The size of the largest block of contiguous free storage on the unallocated free storage queue above the 16MB line.
TOTLUNAL: The total amount of free storage on the unallocated free storage queue both above and below the 16MB line. This is equal to TOLT16MB + TOGT16MB.

The default is SUM.

NOSUM

does not write STORMAP summary data to the output device.

HEADer

includes a header for the data items written to the output device, and separates the items with blank lines. This is the default.

NOHEADer

does not include a header, or separate the items with blank lines.

TYPe

displays the output on the console. This is the default.

NOType

does not display the output on the console. If NOTYPE is specified and the FILE option is omitted, no report is produced.

FILE

writes the output to a file called STORMAP DATA A, erasing STORMAP DATA A first if it previously existed.

APPend

Used with the FILE option, appends the output to STORMAP DATA A rather than first erasing that file.

Records written to STORMAP DATA A are fixed length fields of length 80.

ALL

produces a full STORMAP report, including the summary information and the mapping of your entire virtual machine's storage.

Specifying STORMAP (ALL is equivalent to specifying:

STORMAP 0.END (TYPE HEADER SUM ALLOC UNALLOC FULL PART

Only the following options may be specified with ALL:

TYPE or NOTYPE
FILE or FILE APPEND
SUM or NOSUM
HEADER or NOHEADER
EXTSET
EXTCLR
STEM
SUBPOOL

If ALL is specified with any other parameter, you receive an error message.

FULL

maps full pages of storage. A full page of storage is defined as a 4KB (4096 bytes) page that is either entirely allocated or entirely unallocated.

If FULL is specified without an address range or subpool name, all full pages are mapped within the constraints of the ALLOC and UNALLOC options.

Note: For more information on how the PART/FULL and ALLOC/UNALLOC sets of options interact, see Usage Note 3.

PART

maps partial pages of storage in terms of allocated or unallocated storage. A partial page of storage is defined as a 4KB (4096 bytes) page that is only partially in use responding to requests for free storage, but which still contains some unallocated storage.

If PART is specified without an address range or subpool name, all partial pages are mapped within the constraints of the ALLOC and UNALLOC options.

ALLOC

maps allocated blocks of storage.

If ALLOC is specified without an address range or subpool name, all allocated storage is mapped within the constraints of the PART and FULL options.

UNALloc

maps unallocated blocks of storage.

If UNALLOC is specified without an address range or subpool name, all unallocated storage is mapped within the constraints of the PART and FULL options.

SUBpool name

specifies the name of a subpool. Specifying a subpool name constrains all other options to act only on storage in that subpool. In this way, you can map specific regions of allocated or unallocated storage in the subpool. The subpool name can be from 1-8 characters, cannot contain blanks or nondisplayable characters, and is case-sensitive. Use the ALL option to display information about a subpool with names you cannot directly specify. For subpool names that contain nonblank, nonprintable characters, you can pass the names from a program using the extended plist.

If the SUBPOOL option is not specified, the other options (or defaults) specified are applied to ALL subpools defined in your virtual machine.

EXTSET nnnn

makes CMS wait until the hexadecimal external interrupt code specified by nnnn occurs before processing the other parameters you have specified.

EXTSET is intended to be used when you want to produce a map while the virtual machine is not at the CMS Ready message. For example, it may be in CP read, during a CP Trace of a program. If you call STORMAP with the EXTSET nnnn option before the trace starts, whenever you want the map during the trace, you can use the CP EXTERNAL command to cause the external interrupt and the subsequent STORMAP call with all the desired options already set.

Note: If the virtual machine is disabled for external interrupts at the time the CP EXTERNAL command generates the external interrupt, the previously saved STORMAP command may not be executed immediately. After completion of STORMAP, control will resume at the point where the external interrupt was generated, that is, back in CP read.

You may have as many STORMAP (or SUBPMAP) EXTSETs specified as you want, with the same code or different codes for each one. When any particular external interrupt causes STORMAP or SUBPMAP to be called, all EXTSET's saved with the specified code are called, each in turn.

It is, therefore, possible to have a setup where you have a STORMAP map going to disk, one to the console, and a SUBPMAP map going to the console as well, all when the specified external interrupt occurs.

EXTCLR nnnn

clears ALL saved parameter combinations for the external interrupt code nnnn. If the same interrupt code was in use for SUBPMAP, it will be left active for SUBPMAP. If not, a HNDEXT CLR is issued against the external interrupt code.

If STORMAP is dropped with NUCXDROP, any HNDEXT exits defined by the EXTSET option will be cleared unless active for SUBPMAP as well.

Unlike EXTSET, EXTCLR also executes other parameters if specified on the call, and displays a map. If you do not want a map in this case, specify NOSUM NOHEAD with EXTCLR.

STEM xxxxxx

(for invocation from REXX and EXEC2 only) specifies the character string xxxxxx is the prefix of a variable used to pass data to a REXX or EXEC2 program with the EXECCOMM interface. (Header information is not supplied.) The names of the individual data items requested are concatenated to this prefix and the values of the variables are set accordingly.

The STEM option is most useful when xxxxxx is the stem of a REXX compound variable ending with a period, like XYZ.

If you have specified the SUM option, the items usually returned with SUM are concatenated to the prefix xxxxxx, resulting in REXX variables like XYZ.NUCALPHA, if your prefix was XYZ (XYZ for EXEC2).

If you have requested storage mapping data, the line number for each line is concatenated to the prefix. (A line number for each line will be set as it would appear on the screen.) The variable xxxxxx.0 is set to the number of lines defined. Therefore, if the mapping took 10 lines, XYZ.0 is set to 10.

When the STEM option is used, STORMAP translates the name specified to uppercase, up to the first period, or to the end of the string.

The STORMAP command uses the S form of EXECCOMM. For more information on EXECCOMM, see z/VM: REXX/VM Reference.

Usage Notes

STORMAP 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 occurs.

Defaults

Entering STORMAP with no options or parameters is equivalent to entering:

STORMAP (TYPE SUM HEADER

Similarly, the PART/FULL set of options has defaults that depend on what you specified for ALLOC/UNALLOC.

These basic defaults can change when other options are specified. Table 1 shows what options are in effect when you specify different options.

Table 1. STORMAP Default Parameters
Parameters Specified	Equivalent to Entering
STORMAP	STORMAP (TYPE SUM HEADER
STORMAP (ALL	STORMAP (ALLOC UNALLOC PART TYPE SUM HEADER FULL
STORMAP (FILE	STORMAP (FILE NOTYPE SUM HEADER
Call STORMAP '(STEM XYZ.'	Call STORMAP '(STEM XYZ. NOTYPE SUM HEADER'
STORMAP 20000.500	STORMAP. 20000.500 (NOSUM ALLOC UNALLOC PART FULL TYPE HEADER
STORMAP (SUBPOOL USER	STORMAP (SUBPOOL USER NOSUM ALLOC UNALLOC PART FULL TYPE HEADER
STORMAP (ALLOC	STORMAP (ALLOC PART FULL TYPE NOSUM HEADER
STORMAP (UNALLOC	STORMAP (UNALLOC PART FULL TYPE NOSUM HEADER
STORMAP (PART	STORMAP (PART ALLOC UNALLOC TYPE NOSUM HEADER
STORMAP (FULL	STORMAP (FULL ALLOC UNALLOC TYPE NOSUM HEADER

Examples

Figure 1. Example of STORMAP with No Parameters or Options

Ready;
stormap
                                  Storage Map
                                  ------- ---
 
VMSIZE       NUCALPHA     NUCSIGMA     NUCOMEGA    NUCPHI      NUCCHI
00600000     00E00000     00F9FA08     01100000    01000000    01045358
 
                          Unallocated Free Storage Queue
                          ----------- ---- ------- -----
 
      <16MB                      >16MB
Total       Largest      Total      Largest     Total Unallocated
0042B000    00350000     00000000   00000000    0042B000
Ready;

Figure 2. Example of STORMAP with Address Ranges

Ready;
stormap 13000.1000 15000-20000
                                  Storage Map
                                  ------- ---
 
 
Address Range: 00013000 - 00013FFF
 
Subpool  Start    End      Bytes   Pages Key Attributes
DMSBLOKN 00010000 00013FFF 00004000    4 F0  ALLOC GLOBAL SYSTEM
 
Address Range: 00015000 - 00020000
 
Subpool Start    End      Bytes    Pages  Key Attributes
        00014000 00D3CFFF 00D29000  3369  --  UNALLOC
Ready;

Where:

Field

Description

Subpool

is the name of the subpool in which the storage resides. If no subpool name is listed, this storage is on the unallocated free storage queue.

Start

is the starting address of a block of storage in which the requested piece to be mapped resides.

End

is the ending address of a block of storage in which the requested piece of storage to be mapped resides.

A piece may be mapped by one or several blocks. Each block of storage that falls within the specified range and matches the requested attributes is displayed on a separate line with a starting and ending address.

Bytes

is the hexadecimal number of bytes from Start to End for the particular block of storage.

Pages

If Bytes is a multiple of 4096, it is displayed here as a decimal number of pages. If bytes is less than 4096, p is displayed, meaning it is a partially allocated page of storage.

Full and partial pages are shown as separate blocks even if they were obtained or released as one contiguous piece of storage. For example, if a page and a half of storage is obtained on one call, it is displayed by STORMAP as one fully allocated page of free storage followed by a half page of partially allocated storage.

Key

is the storage protection key of the page in which the block resides. Blocks of storage on the unallocated free storage queue have -- displayed under the key field.

Attributes

are the storage attributes associated with the block of storage. The possible attributes are:

Attribute and Meaning
ALLOC: means the piece of storage is allocated. If the pages column is a decimal number, the piece of storage is fully allocated. If the pages column contains a lowercase p, the piece of storage is partially allocated.
UNALLOC: means the piece of storage is unallocated. If the pages column is a decimal number, the piece of storage is fully unallocated. In this case, the key field contains --. If the pages column contains a lowercase p, the piece of storage is partially unallocated and the key field contains the key the page has been set to.
Fully unallocated storage is always on the unallocated free storage queue and no subpool name is displayed. Partially unallocated storage always has a subpool name displayed.
GLOBAL: means this piece of storage is in a GLOBAL subpool.
SHARED: means this piece of storage is in a SHARED subpool.
PRIVATE: means this piece of storage is in a PRIVATE subpool.
SYSTEM: means the GLOBAL subpool is SYSTEM, meaning it survives abends.

Messages and Return Codes

DMS095E Invalid address address [RC=24]
DMS389E Invalid hexadecimal number: nnnn [RC=24]
DMS2512E External interrupt code nnnn is not set by STORMAP [RC=16]
DMS2513E Extended plist is required. [RC=24]
DMS2514E STEM cannot be specified outside of the REXX or EXEC2 environment. [RC=24]
DMS2515E Invalid stem variable. [RC=24]
DMS2516E Invalid address range: addr1-addr2, start greater than end. [RC=24]
DMS2517E Error on Call to EXECCOMM, RC= nn. [RC=8]
DMS2517E Error on Call to FSWRITE, RC= nn. [RC=20]
DMS2518E Error, RC= nn from STORMAP Initialization. [RC=rc]
DMS2518E Error, RC= nn from HNDEXT SET. [RC=16]
DMS2519E Error detected in STORWORK savearea at address xxxxxxxx [RC=998]
DMS3952E Conflicting option option. [RC=12]
DMS8503E Invalid STORMAP parameter list [RC=24]

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

Return codes:

RC: Meaning
0: Finished correctly
8: Error on EXECCOMM processing
12: Conflicting options were specified
16: Error on HNDEXT macro invocation
20: Error on FS macro file I/O
24: A not valid parameter list was specified
28: NUCXLOAD error
99: STORMAP was invoked on an unsupported level of CMS
104: Insufficient storage
998: DMSFRQ detected data corruption in the DMSFRWSW (STORWORK) control block