The REGION JCL Parameter
I have wanted to write this column for a long time. The JCL REGION parameter is one of the most confusing of all JCL parameters. Using it correctly can be crucial to getting vastly improved throughput for many batch jobs. The confusion about the REGION parameter stems from many factors. Some are historical. Others are due to misconceptions. I will attempt to explain as many of these factors as possible and hopefully, clarify the REGION parameter's usage.
REGION does NOT acquire storage
This is the first misunderstanding that needs clarification. I'll state this as: If a REGION= parameter is coded in a JCL stream or at TSO logon, this DOES NOT cause any storage to be acquired by the operating system. Or, if I code "REGION=0M" on a job card, my job does NOT attempt to GETMAIN all of the virtual storage on the operating system.
Coding a REGION parameter influences only two data values within a control block known as the Local Data Area (LDA, DSECT IHALDA). These two binary fullword values store the maximum amount of virtual storage that address spaces can GETMAIN. Be clear on this: Programs being executed acquire storage. Not the JCL itself.
Why two values? Simple. One field stores the 24-bit ("below the 16 megabyte line") maximum and the other stores the 31-bit ("above the 16 megabyte line") maximum. This dual nature of the REGION parameter, limiting both 24 and 31 bit storage, is critical and will be fully explained later.
Jobcard Coded REGION Overrides Step-Coded REGION
At first, this might seem a bit upside down. Doesn't coding a STEPLIB override any JOBLIB that might be coded? It seems natural that a step-coded value would override the global declaration from the jobcard.
It doesn't work that way. The STEPLIB/JOBLIB situation is an exception. If you code a REGION=50M on your jobcard, it will apply to all steps in the job – even steps that code a different REGION value.
Knowing that the REGION declaration doesn't actually acquire any storage but instead, establishes a limit, I recommend always coding REGION on the jobcard.
Defaults and Exits
This is where the REGION processing gets tricky. I am going to try to explain this as clearly as possible but be forewarned: The defaults and exit-modified values for REGION vary widely from installation to installation. I can't speak to absolutes here because every single z/OS site usually has a different set of default values.
To begin, ask yourself: What if a REGION parameter is not even coded? What limiting values will end up in the LDA? Figure 1 describes how to use the BROWSE command of DDLIST under TSO/ISPF to locate and examine the LDA for your TSO session.
What is the default for REGION?
All REGION discussion that follows applies to what are known as "V=V (or ADDRSPC=VIRT) type of job steps – 99.999% of all work on z/OS.
There is a single question to ask and get answered before you can accurately determine the default limiting amounts for REGION at your site. That question is:
Has your installation established their own defaults by way of either the IEFUSI or IEALIMIT exits? Or, have IBM's "factory defaults" been left in place?
Refer to the Tip of the Month for some help in determining the answer to this question.
REGION Values Fall Into Ranges
Much of the following discussion is based upon the explanations in Section 16.13.3 – REGION Defaults – in the z/OS V1R6 MVS JCL Reference manual. I suggest reading this bit of IBM documentation in conjunction with my explanations. I have tried to simplify things a bit and to underscore the fact that the values coded on a REGION parameter fall into ranges when it comes to what type of REGION you are seeking to limit.
REGION=0M or REGION=0K
The value of zero is a special case. Coding a zero REGION size sets the limits to all of the 24-bit and 31-bit virtual storage available to the address space. Typical defaults are between 8M-10M for 24-bit storage and between 1600M-1900M for 31-bit storage. It DOES NOT acquire any memory and may be further limited by an IEALIMIT or IEFUSI exit.
Also, remember that the REGION parameter applies only to virtual storage limits for the address space (job, step, TSU, etc) that it is coded on. To view the available private storage for an address space (the REGION= amount you can potentially use), you would need an RMF post processor VSTOR report or some other tool that displays a virtual storage map – something like Mark Zelden's IPLINFO REXX exec, TASID, ShowMVS or MXI. If your site has one installed, MVS monitors like OMEGAMON, TMON and MAINVIEW can also display a virtual storage map.
REGION=1K through REGION=16384K
When you code a value between 1K and 16M (note that 16384K = 1,024 X 16), the limit will be applied only to 24-bit storage. For the 31-bit limit, the job will either get the IBM default of 32M or an exit-modified 31-bit limit value.
Note that there is a range of "below the line" limiting values that I will call impossible values. These values fall between approximately REGION=8192K-16384K. If an exit doesn't intercept these impossible values and alter them dynamically (to an amount less than the 24-bit maximum amount), your job will get an S822 abend every time if it uses REGION values in the impossible range. Refer to Figure 2 for a simple piece of JCL to test for the impossible REGION values.
If this one-step IEFBR14 (with no DD names) gets an S822 when using REGION values in the impossible range, this is a good indication that no exits are in place that are dynamically altering REGION limits.
REGION=16385K through REGION=32768K
REGION values between 16M (+ 1K) up to and including exactly 32M limits the job step to the defined site maximum for 24-bit storage. The 31-bit limit will always be either 32M or an exit-modified 31-bit limit value.
REGION=32769K through REGION=2047M
REGION values between 32M (+ 1K) up to and including exactly 2047M limits the job step to the defined site maximum for 24-bit storage. The 31-bit limit will be either the coded value or an exit-modified 31-bit limit value.
In the IBM documentation, the following sentence appears several times when describing how the region below 16 megabytes might be influenced:
"The resulting size of the region below 16 megabytes depends on system options and what system software is installed."
This varies from site to site but a typical default maximum for "below the line" storage is between 9M-10M. In other words, no job step can EVER request more below the line storage than this. If it does, this is considered an impossible REGION value and either your job will abend with an S822 or the impossible value will be lowered by an exit.
Certainly, the REGION parameter of z/OS JCL is one of the most confusing of all JCL parameters. One thing to keep in mind is the very nature of a language such as JCL. JCL, like HTML, is what I call a "static" language. It is designed to create a framework for the invocation of programs, nothing more. It doesn't have the capability of taking its own actions. All of its many keywords and parameters define existing or newly created run-time components. Some JCL parameters set limits or establish other run-time variables but JCL itself has no ability to acquire storage, move values or do anything other than establish a run-time environment for programs.
With this in mind, remember these three key things about how the REGION parameter influences virtual storage in a z/OS JCL stream:
1) It NEVER acquires any storage. It only sets limits.
2) A REGION value coded on the job card overrides any step-coded values.
3) The values coded fall into ranges. Below 16M, the REGION value limits 24-bit storage. Above 32M, you are limiting 31-bit storage.
Tip of the Month: I would like to thank Mr. Mark Zelden for much of the impetus to get working on a full REGION parameter explanation. It was his REXXSTOR REXX exec (available for download at http://www.tsotimes.com
- Spring 2004) that helped me investigate all of the complexities of the REGION parameter. Read Mark's article – What You See Is Not What You Get - in the Spring 2004 issue of The TSO Times for even more REGION details and don't forget to download and try his REXXSTOR program. Also, there is a link at The TSO Times web site to Mark's web page.
Figure 1 – Using the BROWSE command of DDLIST to locate and examine the Local Data Area of your TSO session. This chaining can be followed in any z/OS address space to locate and examine the LDA for storage used and maximum allowed. Note that TSO sessions (TSU) usually have a different default for a 24-bit storage limit than stock batch jobs.
· Invoke DDLIST at any ISPF command line.
· Once in DDLIST, type: BROWSE 224. <- period required, at the command line. This is the address of your TSO session's ASCB.
· Type: BROWSE and move the cursor anywhere within the address at +0 on the screen and press enter (a "point-and-shoot" BROWSE). At the next screen, look for the eye-catching literal "ASCB" in the memory translation area.
· Type: BROWSE and move the cursor anywhere within the address at +30 into the ASCB and press enter. The LDA address is typically very high in memory (begins with X'7F').
· You should now be viewing the LDA of your TSO session. Look for the eye-catching literal "LDA" in the memory translation area at the most recent address that you BROWSED.
· The following offsets into the LDA hold the REGION values:
X'D8' – Maximum amount of 31-bit storage allowed for your TSO session
X'F0' – Current amount of used 31-bit storage
X'D0' - Maximum amount of 24-bit storage allowed for your TSO session
X'E8' – Current amount of used 24-bit storage
X'CC' – The REGION value from either a LOGON screen (possibly defaulted) or an exit
Note that all of these values are fullword binary integers that will need to be converted from hex into decimal.
As an experiment, split the screen and get into edit on a large dataset. Return to the LDA display and press enter, watching the value at X'F0' (current amount of used 31-bit storage). Did it increase?
For the full context of the LDA, refer to DSECT IHALDA.
Figure 2 – Testing for impossible REGION values. Begin with a REGION=9000K and then increment the REGION value – either by K or by M. If you do not get an S822 abend, an exit is intercepting and changing the impossible REGION value. No DD names are needed. Simply code an EXEC line naming PGM=IEFBR14 with a REGION parameter. Add a job card but do not code a REGION on the job card.
//add a jobcard
//TESTS822 EXEC PGM=IEFBR14,REGION=9000K