Statements and parameters for DIAGxx

ADDRESS(addr1|addr1–addrx,[addr2|addr2–addrx]...)
Specifies that the system is to produce trace records only for requested storage of specific addresses. You can specify up to eight storage addresses. Each address must be a hexadecimal number from 0 to 7FFFFFFF. If you do not specify this parameter, the system produces trace records for requested storage of all addresses.
You can specify a specific address, a range of addresses, or any combination of both, as shown in the following examples:
  • ADDRESS(0–FFFFFF). The system produces trace records for all addresses less than 16 megabytes.
  • ADDRESS(8000,70000000–7FFFFFFF) The system produces trace records for addresses 8000 and 70000000–7FFFFFFF.

If you specify a range of addresses, ensure that the address at the end of the range is greater than or equal to the address of the beginning of the range. A request matches a range if any byte of the request is within the range.

ADDRESS filtering does not apply to a subpool FREEMAIN request, causing a trace record to be produced for the subpool FREEMAIN, as well as an associated "Releasing Subpool" trace record. (For a description of the "Releasing Subpool" trace record, refer to Formatted GFS Trace Output in z/OS MVS Diagnosis: Tools and Service Aids, under GETMAIN, FREEMAIN, STORAGE (GFS) Trace.)

ASID({asid1|asid1-asidx}[,{asid2|asid2-asidx}]...)
Indicates that the system is to produce trace records only for one or more specified address space identifiers (ASIDs). Each ASID must be a hexadecimal number from 0 to 7FFF. The ASID that the system checks when it determines whether to produce a trace record is as follows:
CSA Storage=
If CSA tracking is on, the associated ASID is the one indicated by the OWNER parameter on GETMAIN or STORAGE. If CSA tracking is off (or for a request to release storage, was off when the storage was obtained), the associated ASID is unknown, causing no ASID filtering to be done and a trace record to be produced.
Private Storage=
The target address space of the storage.
SQA Storage =
If SQA tracking is on, the associated ASID is the one indicated by the OWNER parameter on GETMAIN or STORAGE. If SQA tracking is off (or for a request to release storage, was off when the storage was obtained), the associated ASID is unknown, causing no ASID filtering to be done and a trace record to be produced.

ASID 0 matches common storage requests with OWNER=SYSTEM.

If you omit this parameter, the system produces trace records for all ASIDs. You can specify 1 - 32 ASIDs.

You can specify a specific ASID, a range of ASIDs, or any combination of both, as shown in the following examples:
  • ASID(5,6,9) - The system produces trace records for ASIDs 5, 6, and 9.
  • ASID(5-7,9,11-13) - The system produces trace records for ASIDs 5, 6, 7, 9, 11, 12, and 13.

If you specify a range of ASIDs, ensure that the ASID at the end of the range is greater than the ASID at the beginning of the range.

ASLR(NO|YES|YES3164|YES64)
Indicates whether address spaces on this system are subject to address space layout randomization (ASLR). For information about the implications of enabling ASLR and how to exclude individual jobs from ASLR, see Address space layout randomization in z/OS MVS Initialization and Tuning Guide. The ASLR values are:
NO
Indicates that the 24-bit and 31-bit low private area and the 64-bit private area of address spaces are not subject to address space layout randomization.
YES
Indicates that the 24-bit and 31-bit low private area and the 64-bit private area of address spaces are subject to address space layout randomization.
YES3164
Indicates that only the 31-bit low private area and the 64-bit private area of address spaces are subject to address space layout randomization.
YES64
Indicates that only the 64-bit private area of address spaces is subject to address space layout randomization.
Default: NO
AUTOIPL SADMP(sadmp info) MVS(mvs info) [NUCLABEL {ENABLE|DISABLE}(BLWRSTO2)]
(sadmp info)
Either (device,loadparm) or (NONE).
  • For SADMP(device,loadparm), if the system is about to enter a wait state, SADMP is loaded from this volume with this load parameter.
  • For SADMP(NONE), if the system is about to enter a wait state, SADMP is not loaded.
(mvs info)
Either (device,loadparm,loadtype) or (LAST,loadtype) or (NONE)
loadtype
Either CLEAR or NORMAL.

If ,loadtype is not specified, it defaults to ,CLEAR.

Notes:
  1. SADMP specified with a device and load parameter and MVS™ specified with NONE causes the AutoIPL function to IPL SADMP only.
  2. SADMP specified with NONE and MVS specified with a device and load parameter or with LAST causes the AutoIPL function to re-IPL MVS immediately, with no SADMP taken.
  3. SADMP with a device and load parameter and MVS with a device and load parameter or with LAST causes SADMP to be IPLed, followed by MVS.
  4. Any valid specification of AUTOIPL causes any prior AutoIPL information to be replaced.
  5. SADMP (NONE) and MVS (NONE) both specified effectively deactivates the AutoIPL function.
  6. The SADMP loadparm value can be specified so that SADMP executes without prompts to the operator. For information on coding the SADMP load parameter, see Procedure A: Initialize and run stand-alone dump in z/OS MVS Diagnosis: Tools and Service Aids.
  7. The MVS with LAST parameters do not support HyperSwaps in which the IPL, IODF, and SADMP secondary volumes are not part of an alternate subchannel set (that is, the primary and secondary device pairs do not have identical device numbers and all reside in a single subchannel set). Therefore, if MVS with LAST was specified in that environment and a HyperSwap® swapped different device numberHyperSwap within subchannel set zero and no intervening IPL occurred, the MVS with LAST function will still attempt to use the original IPL, IODF, and SADMP volumes before the swap.
  8. device is a 4-digit device number that can be prefixed by *. The asterisk prefix denotes that the device in the currently active subchannel set should be used. If an asterisk does not prefix the device number, the device in subchannel set 0 is used.

    This function is intended for HyperSwap environments that use alternate subchannel sets. Environments without HyperSwap or HyperSwap environments that do not use an alternate subchannel set will not benefit from using *.

  9. Only in a HyperSwap environment that uses an alternate subchannel set will the MVS with LAST parameters ensure that AUTOIPL uses the device number from the appropriate subchannel set in the event of a HyperSwap.
  10. AUTOIPL, when requested to IPL an MVS system, will, by default, specify the CLEAR option that can lead to an elongated response time for the function. The request can be made to perform better by specifying the Start of changeCLEAREnd of change suboption for AUTOIPL. The result of requesting this option is that the AUTOIPL initiated IPL will be done using the NORMAL option.
    Note: This processing can result in the unavailability of reconfigurable storage when the IPL is done so the specification of this option should only be used when necessary.
  11. Start of changeAn IPL of MVS or SADMP that is initiated via AUTOIPL will be the same type of IPL (CCW or List-Directed) as the last IPL that was initiated by an operator. If that IPL was List-Directed, the Secure or not Secure setting for AUTOIPL will also be the same as the last IPL that was initiated by an operator.End of change
For more information about AutoIPL, see Using the automatic IPL function in z/OS MVS Planning: Operations.
CBLOC [VIRTUAL24(structure1,structure2, ...)] [VIRTUAL31(structure1,structure2, ...)] [REAL31(structure1,structure2, ...)] [REAL64(structure1,structure2, ...)]
VIRTUAL24
Provides the names of structures to be located in 24-bit virtual storage.
VIRTUAL31
Provides the names of structures to be located in 31-bit virtual storage.
Structure names:
IHALCCA
When a CPU is brought online, the location of its LCCA is determined by which list includes IHALCCA. If neither of the lists include IHALCCA, the LCCA is in 31-bit virtual storage. If both lists include IHALCCA, the resulting location is undefined. The LCCA of the IPL CPU is built in 24-bit storage before DIAGxx is processed.

If additional standard CPs are brought online later in the IPL process, the IPL CPU is automatically configured offline and back online, with its LCCA located according to the CBLOC specification.

IHAPCCA
When a CPU is brought online, the location of its PCCA is determined by which list includes IHAPCCA. If neither of the lists include IHAPCCA, the PCCA is in 31-bit virtual storage. If both lists include IHAPCCA, the resulting location is undefined. The PCCA of the IPL CPU is built in 24-bit storage before DIAGxx is processed.

If additional standard CPs are brought online later in the IPL process, the IPL CPU is automatically configured offline and back online, with its PCCA located according to the CBLOC specification.

IHAASVT
When the system is IPLed, the location of its ASVT is determined by which list includes IHAASVT. If neither of the lists include IHAASVT, the ASVT is in 24-bit virtual storage. If both lists include IHAASVT, the resulting location is undefined.
CNZSSICB
When SSI Functions 9, 10, or 14 are called upon, their respective control blocks are created in 31-bit storage.
REAL31
Provides the names of structures to be backed in 31-bit real storage.
REAL64
Provides the names of structures to be backed in 64-bit real storage.
Start of changeStructure names:
IHAASCB
The real storage backing of ASCBs is determined by which list includes IHAASCB. If neither of the lists includes IHAASCB, ASCBs are backed in 64-bit real storage. If both lists include IHAASCB, the real storage backing is undefined.
IHAWEB
The real storage backing of WEBs is determined by which list includes IHAWEB. If neither of the lists includes IHAWEB, WEBs are backed in 64-bit real storage. If both lists include IHAWEB, the real storage backing is undefined.
End of change
CSA (ON|OFF)
The status of the common service area (CSA and ECSA) tracking function. Specifying CSA(ON) might lead to a small performance degradation and an increase in ESQA use. Omitting this parameter leaves the status of CSA/ECSA tracking unchanged.
DATA(data1[,data2]...)
Specifies the data items that you want to include in the trace. The data items are listed in the following table.
Data Information included in trace.
ALL All trace information (BASIC plus REGS). If you omit the DATA keyword, the default is DATA(ALL).
REGS The contents of the caller's registers when the system processed the linkage instruction to GETMAIN, FREEMAIN, or STORAGE.
BASIC All of the trace information except REGS. The BASIC data is included in every trace record.

RETADDR, RETCODE, TYPE, SVCNUM, ADDR, LENGTH, SPKEY, FLAGS, ASID, and TCB are accepted for compatibility with older releases and are ignored.

FREEMAINEDFRAMES(NO)
FREEMAINEDFRAMES(YES) [EXCLUDEJOBLIST([job1[,job2…]])]
Start of changeTo enhance performance on IBM z13® and later hardware, the system does not free the real frame that is backing a low private virtual page following a FREEMAIN (that is, when the page no longer contains any GETMAIN-assigned storage ranges); however, the system overwrites the contents of the frame to ensure that sensitive information is removed. Such a frame is referred to as a freemained frame. Freemained frames do not cause the count of frames that are owned by the address space to be decremented, nor do they cause the count of available frames within the system to be incremented.
FREEMAINEDFRAMES(NO)
Disables the freemained frames feature on a system-wide basis. The high freemained frames feature is also disabled when this option is specified.
FREEMAINEDFRAMES(YES) [EXCLUDEJOBLIST([job1[,job2…]])]
Enables the freemained frames feature, except for the specified jobs. If the job name of either a START, MOUNT, LOGON, or initiated program matches a value that is specified in the EXCLUDEJOBLIST parameter, that job is excluded from the freemained frames feature. Up to eight job names can be specified and can include the * and ? wildcard characters, where the * character is allowed in any position.

When you exclude a job, all existing freemained frames, including high freemained frames, are purged from the associated address space.

Reissuing the SET DIAG command with different EXCLUDEJOBLIST values cannot increase the total number of excluded jobs; the last EXCLUDEJOBLIST specification overrides any previous specifications.

Disabling this feature for selected jobs cause performance degradation for the entire system, not just for the specified jobs.

Example: The following statement disables the freemained frames feature for all initiators under JES2: 
FREEMAINEDFRAMES(YES) EXCLUDEJOBLIST(INIT)

This feature is active by default on z13® and later hardware and only applies to region private storage below the 2 GB bar, which is defined as subpools 0-127, 129-132, 240, 244, 250-252.

End of change
FF31HIGH(NO)
FF31HIGH(YES) [EXCLUDEJOBLIST([job1[,job2…]])]
This is automatically set to NO. The FREEMAINEDFRAMES(NO) is specified or changed to NO.

To enhance performance on IBM® IBM z14® and later hardware, the system might not free the real frame that is backing a high private or LSQA page following a FREEMAIN (that is, when the page no longer contains any high private GETMAIN-assigned storage ranges); the system overwrites the contents of the frame to ensure that sensitive information is removed if the frame's key is not 0-7 or not fetch protected. Such a frame is referred to as a high freemained frame. Like Low Private Freemained frames, High Private Freemained Frames do not cause the count of frames that are owned by the address space to be decremented, nor do they cause the count of available frames within the system to be incremented.

FF31HIGH(NO)
Disables the high freemained frames feature on a system-wide basis.
FF31HIGH(YES) [EXCLUDEJOBLIST([job1[,job2…]])]
Enables the high freemained frames feature, except for the specified jobs. If the job name of either a START, MOUNT, LOGON, or initiated program matches a value that is specified in the EXCLUDEJOBLIST parameter, that job is excluded from the freemained frames feature. Up to eight job names can be specified and can include the * and ? wildcard characters, where the * character is allowed in any position. When you exclude a job, all existing high freemained frames are purged from the associated address space. Reissuing the SET DIAG command with different EXCLUDEJOBLIST values will not increase the total number of excluded jobs; the last EXCLUDEJOBLIST specification overrides any previous specifications. Disabling this feature for selected jobs cause performance degradation for the entire system, not just for the specified jobs.
Default: YES
GETFREE(ON|OFF)
Specifies the status of the GFS trace.
JOBNAME(job1[,job2...])
Specifies that the system is to produce trace records only for one or more specified job names. Each job name must be 1 - 8 alphanumeric or national characters. The wildcard characters ? and * can be included.

The job name that the system checks when it determines whether to produce a trace record is the job name for the ASID that would be used to match an ASID filter.

CSA Storage=
If CSA tracking is on, the associated JOBNAME is the one indicated by the OWNER parameter on GETMAIN or STORAGE. If CSA tracking is off (or for a request to release storage, was off when the storage was obtained), the associated JOBNAME is unknown, causing no JOBNAME filtering to be done and a trace record to be produced.
Private Storage=
The target JOBNAME of the storage.
SQA Storage =
If SQA tracking is on, the associated JOBNAME is the one indicated by the OWNER parameter on GETMAIN or STORAGE. If SQA tracking is off (or for a request to release storage, was off when the storage was obtained), the associated JOBNAME is unknown, causing no JOBNAME filtering to be done and a trace record to be produced.
KEY({key1|key1-keyx}[,{key2|key2-keyx}]...)
Specifies the storage keys for which the system is to produce trace records. If you do not specify this parameter, the system produces trace records for all storage keys. You can specify any number of keys or key ranges. Each key must be a decimal number 0 - 15.

If you specify a range of keys, ensure that the key at the end of the range is greater than or equal to the key at the beginning of the range.

You can specify a specific key, a range of keys, or any combination of both, as shown in the following examples:
  • KEY(1,2). The system produces trace records for storage keys 1 and 2.
  • KEY(1-3,15). The system produces trace records for storage keys 1, 2, 3 and 15.

KEY filtering does not apply to a subpool FREEMAIN request, causing a trace record to be produced for the subpool FREEMAIN, as well as an associated "Releasing Subpool" trace record. (For a description of the "Releasing Subpool" trace record, refer to Formatted GFS Trace Output in z/OS MVS Diagnosis: Tools and Service Aids, under GETMAIN, FREEMAIN, STORAGE (GFS) Trace.)

LENGTH({len1|len1-lenx}[,{len2|len2-lenx}]...)
Indicates that the system is to produce trace records only for requested storage of specific lengths (in bytes). You can specify up to eight storage lengths. Each length must be a decimal number 1 - 10 digits (the maximum value is 2147483640 bytes). If you do not specify this parameter, the system produces trace records for requested storage of all lengths.

Specify each length as a multiple of 8 bytes. If you do not, the system rounds the value up to the next higher multiple of 8.

You can specify a specific length, a range of lengths, or any combination of both, as shown in the following examples:
  • LENGTH(512,1024). The system produces trace records for requested lengths of 512 and 1024 bytes.
  • LENGTH(512,520-528,1024-1032). The system produces trace records for requested lengths of 512, 520-528, and 1024 - 1032 bytes.

If you specify a range of lengths, ensure that the length at the end of the range is greater than or equal to the length at the beginning of the range. If the requested storage is of a variable length, the system uses the length of the storage that was obtained.

LENGTH filtering does not apply to a subpool FREEMAIN request, causing a trace record to be produced for the subpool FREEMAIN and an associated "Releasing Subpool" trace record. (For a description of the "Releasing Subpool" trace record, refer to Formatted GFS Trace Output in z/OS MVS Diagnosis: Tools and Service Aids, under GETMAIN, FREEMAIN, STORAGE (GFS) Trace.)

LOCREAL(loc1[,loc2]...)
Specifies the real storage locations for which trace records should be produced, as specified by the LOC keyword on the GETMAIN or STORAGE macros. For example, LOCREAL(24,31) requests tracing for those storage requests that specified real storage backing below the line (LOC=24 or LOC=(xx,24)) and those storage requests that specified real storage backing in 31-bit storage (LOC=(xx,31)).

LOCREAL(64) traces all storage requests that specify LOC(xx,64) or LOC(xx,PAGEFRAMESIZE1MB).

Valid parameters for LOCREAL are 24, BELOW, 31, ANY, 64, and PAGEFRAMESIZE1MB:
24 | BELOW
The system produces trace records for requests that specify real storage backing below the line.
31 | ANY
The system produces trace records for requests that specify real storage backing in 31-bit storage.
64
The system produces trace records for requests that specify real storage backing in 64-bit storage.
PAGEFRAMESIZE1MB
The system produces trace records for requests that specify LOC(xx,PAGEFRAMESIZE1MB).

If you do not specify this parameter, trace records are produced for all storage locations.

REUSASID(NO|YES)
Specifies whether a reusable ASID is assigned when requested by the START command or the ASCRE macro.
NO
An ordinary ASID is assigned.
YES
A reusable UIDASID is assigned.
Default: YES

The use of reusable ASIDs might result in system 0D3 abends, if products or programs have not been upgraded to tolerate reusable ASIDs. For more information about reusable ASIDs, see z/OS MVS Programming: Extended Addressability Guide.

SUBPOOL({sub1|sub1-subx}[,{sub2|sub2-subx}]...)
Specifies the subpools for which the system is to produce trace records. If you omit this parameter, the system produces trace records for all subpools. You can specify any number of subpools.
You can specify a specific subpool, a range of subpools, or any combination of both, as shown in the following examples:
  • SUBPOOL(129,132) - The system produces trace records for subpools 129 and 132.
  • SUBPOOL(129-131, 227-229, 252) - The system produces trace records for subpools 129, 130, 131, 227, 228, 229 and 252.

If you specify a range of subpools, ensure that the subpool at the end of the range is greater than or equal to the subpool at the beginning of the range.

SQA (ON|OFF)
The status of the system queue area (SQA and ESQA) tracking function. Specifying SQA(ON) might lead to a small performance degradation and an increase in ESQA usage. Omitting this parameter leaves the status of SQA/ESQA tracking unchanged.
TRAPS NAME ([trapname1,{trapname2}...])
Specifies a list of the traps that should be activated. If you issue command SET DIAG=xx and the DIAGxx parmlib member contains a TRAPS NAME statement, the list of TRAPS specified replaces the previous list of activated traps. This deactivates any traps that are not in the new list.

Specifying a null list of trap names deactivates all the TRAPS. If your DIAGxx parmlib member does not contain a TRAPS statement, there is no change to the list of traps that are activated. If you specify multiple parmlib members (DIAG=(03,04)) and both contain TRAPS statements or you code multiple TRAPS statements in a single parmlib member, only the last TRAPS statement is honored.

The following traps are supported:
IarCp64InitFree
The IARCP64 services initialize storage to contain nonzero values on a REQUEST=FREE.
Note: IarCp64InitFree is intended to be used in a test environment to surface programs that reference storage after it has been freed with IARCP64 REQUEST=FREE. Because this will potentially cause more pages to be backed, consume more CPU cycles and possibly cause more page faults, do not activate this option in a production environment.
IarCp64InitGet
The IARCP64 service is to initialize storage to contain nonzero values on a REQUEST=GET.
Note: IarCp64InitGet is intended to be used in a test environment to surface programs that obtain cells from a cell pool with IARCP64, but fail to initialize it before using it. Because this will likely cause more pages to be backed and possibly more page faults, do not activate this option in a production environment.
IarRucsaFlt
Issues a diagnostic SC0D-05005C00 abend when a fault on user-key CSA storage occurs while IEASYSxx RUCSA is defined and the faulter does not have SAF READ authority to CLASS(FACILITY) PROFILE(IARRSM.RUCSA). The abend is retried and not exposed to the faulter. It can be used to create a system memory dump and LOGREC entry to help identifying software that faults on RUCSA.
IarSt64InitFree
The IARST64 service is to initialize storage to contain nonzero values on a REQUEST=FREE.

This option is intended to be used in a test environment to surface programs that reference storage after it has been freed with IARST64 REQUEST=FREE. Because this will potentially cause more pages to be backed, consume more CPU cycles and possibly cause more page faults, do not activate this option in a production environment.

IarSt64InitGet
The IARST64 service is to initialize storage to contain nonzero values on a REQUEST=GET.

This option is intended to be used in a test environment to surface programs that obtain storage with IARST64, but fail to initialize it before using it. Since this will likely cause more pages to be backed and possibly more page faults, activating this option in a production environment should be avoided.

IarSt64Trailer
The IARST64 REQUEST=GET service is to force trailer processing for storage requests, even if it means to increase the size of the obtained storage cell to make room for the trailer.

This option is intended to be used in a test environment to surface programs that modify storage past the end of the requested storage size. When storage is freed with IARST64 REQUEST=FREE, the service abends the caller if it detects that the trailer has been overlaid. Since this will potentially increase the size of the storage cell, it can reduce the number of cells per extent, which can cause more pages to be backed, consume more CPU cycles and possibly cause more page faults, activating this option in a production environment should be avoided.

IEARISGNLTRACE
Turns on system tracing of RISGNL.
IEARPSGNLTRACE
Turns on system tracing of RPSGNL.
IEASCHEDULETRACE
Turns on system tracing of SCHEDULE and IEAMSCHD. Adding tracing of SRB scheduling might cause a small degradation in performance.
IeaSlipConfirm
Checks to see whether JOBNAME or ASID is specified when MODE=HOME is specified on the SLIP command. If both JOBNAME and ASID parameters were omitted, SLIP issues message IEE088D asking if you would like to continue. This trap is used only for V2R1 systems and is obsolete in V2R2. In V2R2, SLIP always issues message IEE088D when MODE=HOME is specified without JOBNAME and ASID.
Start of changeVSM ALLOWEARLYRUCSA(NO|YES)End of change
Start of change
NO
When restricted use common service area (RUCSA) is defined and VSM ALLOWUSERKEYCSA is NO, the following uses of RUCSA Start of changemightEnd of change abend:
  • Creating or referencing RUCSA storage within an address space that is started during system IPL before the security product has been initialized.
  • Creating RUCSA storage while running under the Master address space
  • Creating or referencing RUCSA storage within user exits or started task initialization routines that run before the completion of job selection.
YES
When RUCSA is defined, the previously described early usage conditions are permitted. Do not specify VSM ALLOWEARLYRUCSA(YES) if early usage has not been recorded by SMF type 30 records. For more information on determining whether early use conditions exist, see Restricted use common service area (RUCSA/extended RUCSA) in z/OS MVS Initialization and Tuning Guide.

Start of changeSAF READ authority to the IARRSM.RUCSA resource profile in the FACILITY class is still required except for address spaces that are always started early in system IPL, before the security product has completed initialization.End of change

Default: Start of changeNOEnd of change
End of change
VSM ALLOWUSERKEYCSA(NO)
NO
ALLOWUSERKEYCSA(NO) is tolerated but no value other than NO is allowed because user-key CSA storage is not supported outside of a restricted use common service area (RUCSA). When a RUCSA is not defined, prevents user-key CSA from being allocated by failing any attempt to obtain user-key storage from a CSA subpool (through GETMAIN or STORAGE OBTAIN) with an appropriate abend.

When a RUCSA is defined, only users with SAF READ authority to the IARRSM.RUCSA resource in the FACILITY class can use user-key CSA.

For more information about RUCSA, see Restricted use common service area (RUCSA/extended RUCSA) in z/OS MVS Initialization and Tuning Guide.

Default: NO
VSM BESTFITCSA(NO|YES)
Indicates how GETMAIN or STORAG|OBTAIN processes requests for (E)CSA storage.
NO
Indicates to use a "first fit" algorithm in certain situations such as when you use the STARTBDY and CONTBDY options. It matches the default behavior on all current releases of z/OS®. However, in some environments, this option can lead to (E)CSA fragmentation.
YES
Indicates to always use a "best fit" algorithm. It minimizes (E)CSA fragmentation to help prevent user and system outages because of requests for (E)CSA storage that the system cannot satisfy.
Default: Start of changeNO, to provide seamless migration. The default value represents the historical behavior; instead, specify YES to always benefit from the “best fit” behavior. End of change
VSM CHECKREGIONLOSS(bbb{K|M},aaa{K|M})
Indicates the amount of region size loss that can be tolerated in an initiator address space. The initiator remembers the initial maximum available region size (below and above 16 MB) before it selects its first job. After the termination of each job run in the initiator, if the maximum available region size (below or above 16 MB) has decreased from the initial value by more than the CHECKREGIONLOSS specification, the initiator terminates with message IEF093I or IEF094A, depending on whether the subsystem automatically restarts the initiator. JES2, JES3, WLM, OMVS, and APPC all automatically restart initiators, so initiator issues IEF093I in most cases. CHECKREGIONLOSS allows the installation to avoid 822 abends in subsequent jobs that are selected by an initiator. The available region size of the initiator has decreased because of storage fragmentation or problems that have caused storage not to be freed.

Because the initiator notifies the owning subsystem that the initiator is being terminated on the job termination SSI call, the CHECKREGIONLOSS detection must be done before some storage that will eventually be freed actually gets freed. The SWA subpool is an example (and for some jobs, a large example) of this. The detection processing recognizes storage that is part of the SWA subpool, and treats it as if it was freed. However, if you are looking at a memory dump of an IEF093I message, you still need to manually ignore the SWA storage.

Some fragmentation (especially above 16 MB) is normal. A job that uses a lot of SWA (or other system control blocks in high extended private) might cause fragmentation because this forces another system control block that persists across jobs to be allocated at a lower address. The VSM cell pool extents (VSMP eye catcher at the beginning of a 4 KB page) are an example of persistent storage. Compression of VSM cell pool extents requires a large amount of CPU time (much more than the CPU time for terminating and restarting an initiator). Recycling of initiators under the control of CHECKREGIONLOSS is the intended mechanism for dealing with fragmentation.

In addition to normal fragmentation, IEF093I might in some cases expose a storage leak problem that can be investigated and fixed. Differentiating between normal fragmentation and a storage leak is a time consuming manual process done by analyzing dumps.

Selecting the CHECKREGIONLOSS values:
  • Select values small enough to avoid 822 abends for the jobs in your installation that have the largest REGION requirements. That depends on the size of your private area above and below 16 M, and the REGION requirements of your largest jobs.
  • Select values large enough so that the frequency of IEF093I messages is not excessive, and so that the frequency of initiator recycling is not a performance issue.
    Start with something like: 
    CHECKREGIONLOSS(256K,10M)
    Decrease the values if you see 822 abends, and increase the values if you frequently see IEF093I messages.
    Note: This DIAGxx parmlib parameter is enabled after z/OS V2R4.
bbb{K|M}
Specifies the region size below 16 MB.
Value range: Start of change0 - 2046M

A value greater than or equal to 16M effectively disables the feature for below 16M.

End of change
aaa{K|M}
Specifies the region size above 16 MB.
Value range: Start of change0 - 2046M

A value greater than or equal to 2032M effectively disables the feature for above 16M.

End of change
Default: Start of changeCHECKREGIONLOSS(256K,30M)End of change
VSM TRACE
Indicates that the statement defines a GFS trace of storage that is obtained and released.
VSM TRACK
Indicates that the system is to process the VSM tracking parameters.
VSM USEZOSV1R9RULES(NO|YES)
NO
Specifies GETMAIN and STORAGE OBTAIN behavior for user-region private area subpools that are both below and above the line to be implemented. Thus DQEs can be merged where possible.
YES
Causes GETMAIN and STORAGE OBTAIN behavior to be unchanged from its historic behavior.
Default: The default is YES to provide a seamless migration. However, IBM recommends that you specify USEZOSV1R9RULES(NO) to obtain a performance benefit for applications with long DQE/FQE chains for user-region private area subpools.

Examples

Example 1: The following example shows a DIAGxx parmlib member that starts GFS trace for requests to obtain or release virtual storage in subpools 1 through 127 and 229. The GFS trace includes requests for:
  • Address spaces 1 and F
  • A length of 4096 bytes
  • Keys 8, 10, 11, and 12.
GFS trace includes all data in the trace, except for register information. 
    VSM TRACE GETFREE(ON)
              SUBPOOL(1-127,229)
              ASID(1,F)
              LENGTH(4096)
              KEY(8,10-12)
              DATA(RETADDR,RETCODE,TYPE,SVCNUM,
                   ADDR,LENGTH,SPKEY,FLAGS,ASID,TCB)
Example 2: The following example shows a DIAGxx parmlib member that starts GFS trace for requests to obtain or release virtual storage in subpools 129 through 255. The GFS trace includes requests for:
  • All address spaces (the ASID keyword is not specified)
  • Lengths in the 4096-8192 byte range
  • All keys (the KEY keyword is not specified)
GFS trace includes all data in the trace, except for register information. 
    VSM TRACE GETFREE(ON)
              SUBPOOL(129-255)
              LENGTH(4096-8192)
              DATA(RETADDR,RETCODE,TYPE,SVCNUM,
                   ADDR,LENGTH,SPKEY,FLAGS,ASID,TCB)
Example 3: The following example shows a DIAGxx parmlib member that turns CSA/ECSA tracking on and turns SQA/ESQA tracking off: 
    VSM TRACK CSA(ON) SQA(OFF)
Example 4: The following example shows a DIAGxx parmlib member that controls termination and restarting of initiator address spaces when the amount of region loss exceeds 256 K below 16 M or 10 M above 16 M. 
CHECKREGIONLOSS(256K,10M)
Example 5: The following example shows a DIAGxx parmlib member that prevents the use of user key CSA. 
VSM ALLOWUSERKEYCSA(NO)
Example 6: The following example shows a DIAGxx parmlib member that enables the reuse of ASID. 
REUSASID(YES)
Example 7: The following example shows a DIAGxx parmlib member that specifies that LCCAs and PCCAs must be located above 16 MB. 
CBLOC VIRTUAL31(IHALCCA,IHAPCCA)
Example 8: The following example shows a DIAGxx parmlib member that specifies several traps to be activated. All of the diagnostic options that relate to IARCP64 requests are turned on. 
TRAPS NAME(IARCP64INITGET,IARCP64INITFREE,IARCP64TRAILER)
Example 9: The following example shows a DIAGxx parmlib member that turns off all traps. This turns off all of the TRAP options. 
TRAPS NAME()

For examples of output from storage tracking, see z/OS MVS Diagnosis: Tools and Service Aids. For information about the location of GFS trace records, see z/OS MVS Diagnosis: Tools and Service Aids.