Db2 for zOS 101 Db2 and WLM

Terminology

Service definition

Consists of one or more service policies

Service policy

Contains several workloads
One service policy is active at a time in an LPAR or Parallel Sysplex

Workload
Arbitrary collection Consists of one or more service classes

Service class

Each service class has at least one period
- Each period has one goal
- If > 1 period, all but last have a duration

Goal (5 types)
System
Average response time
% response time
Execution velocity
Discretionary

Classification rules

WLM assigns address spaces and transactions to service classes by classification rules 

 Concepts: service class and classification

Classification

• Assignment of incoming work to a service class, and optional report class
• Based on a wide variety of filters, or qualifiers

 

Service class

Set or group of related work

• Production CICS, IMS, and Db2 address spaced might be in the same service class: STCHI or PRODHI
• Separate report classes can report on CICS, IMS, Db2 separately
  

Service class can combine goals of different types in multiple periods

• Period is a combination of importance (IMP), goal, and duration
• A service class period is the target of WLM measurement and management actions
  

Subsystem types and classification

 

Transaction Type	Allowable Goal Types	Allowable # of Periods
Address space oriented	Response Time Execution Velocity Discretionary	Multiple
Enclave	Response Time Execution Velocity Discretionary	Multiple
CICS/IMS	Response Time	One

Goal Types

System goals
SYSTEM, SYSSTC
- These have fixed dispatch priorities above IMP 1

Response time goals
Average response time
- Includes queue time and execution time
- Better for homogeneous type transactions

Percentile response time
- Reduce effect of outliers 

- Better for heterogeneous type transactions

 

Execution velocity goals (velocity goals)
Intended for work where response time goals are not appropriate
- Address spaces, long running jobs

Discretionary

For low priority, long-running work
- Probably not appropriate for Db2 work

 

Goal types: more detail

Execution velocity goals (velocity goals)

• How fast work should run relative to other work requests when ready, without being delayed for CPU, storage or I/O
• Expressed as a number, e.g. 60 or 40
  Value of 60 means 'ready' work runs 60% of the time
• Differentiate velocity goals within an importance level by 10
• Appropriate velocity goals depend on the number of engines (CPs)

 Response time goals

• Average response time goal of 1 second - if one in 10 transactions takes 10 seconds, you will miss this goal
• Percentile response time goal of 90% complete in 1 second, one transaction in 10 taking 10 seconds will not miss this goal

Importance

For most work, importance 1 (IMP 1) is highest and importance 5 (IMP 5) is lowest

WLM applies resources to IMP 1 first

If IMP 1 work meets its goals, WLM will apply resources to IMP 2, then IMP 3, then IMP 4, etc.

Some service trickles down to DISCRETIONARY

SYSTEM and SYSSTC are internal service classes for system tasks and have the highest dispatching priorities

SYSOTHER is the default service class for unclassified work and runs at a DISCRETIONARY goal

Note: not all work is "most important"

Importance levels and Db2, example

SYSTEM	z/OS
SYSSTC	IRLMs
IMP 1 Highest	DB2PMSTR, DB2PDBM1, DB2PDIST, DB2PWLMx
IMP 2 High	Production DDF txns
IMP 3 Medium
IMP 4 Low	Low priority work
IMP 5 Lowest	Lowest priority work
DISCRETIONARY
SYSOTHER	Default service class

Importance 1 is highest priority after SYSSTC

Db2 address spaces should have velocity goals and a single period defined

Non-production Db2s could be IMP 2 or IMP 3 or IMP 4 if in same LPAR (or Parallel Sysplex) with production Db2

Discretionary work gets service after all other importance levels

• Not appropriate for Db2 address spaces
• Not recommended for Db2 work
• Very little service if CPU 100% busy

 WLM concepts and Db2 (notes)

Importance

• Production Db2 address spaces (MSTR, DBM1, DIST, WLM) should be defined with Importance 1 (IMP 1)
• Non-production Db2 address spaces in a production LPAR should be defined with lower importance: IMP > 1
  • Consider relative to other production work
• Production DDF transactions should generally be defined with IMP below that of production Db2 address spaces
• IRLMs should be defined in SYSSTC

 

Goals for Db2 work

• System - IRLM in SYSSTC
• Velocity goals are appropriate for started tasks or long-running work
  • Db2 address spaces should have velocity goals and only a single period in the service class (MSTR, DBM1, DIST, WLMx)
• Response time goals are appropriate for transactions, including most DDF work
  • Percentile response time-e.g. 90% complete in 0.5 seconds
  • Average response time - e.g. average response time is 0.5 seconds
• Discretionary: below IMP 5. Not appropriate for Db2 work, in general

 

Service class: assigning goal types (example only)

CICS, IMS or TSO transactions
E.g. average response time goal Transactions complete <0.7 seconds

Db2 Address Spaces
Velocity goal; IMP 1
Exec Vel = 70 , Single period

Production DDF Transactions
Percentile response time goal, single period
IMP 2; 90% complete < 0.5 seconds

Non-production DDF: response time goals in first period, response time or velocity in second period

Period 1: IMP 3, 90% complete <0.5 seconds
Period 2: IMP 4, 90% complete < 4 seconds
Period 3: MP 5, Vel = 40

Service class: period switch - example

PERIOD 1
DUR = 300
IMP = 3
R/T = 90% in 0.5 sec

PERIOD 2
DUR = 600
IMP = 4
R/T = 90% in 4 sec

PERIOD 3
IMP = 5
VEL = 40

All transactions assigned to this service class start in Period 1

• WLM manages the transactions in period 1 to the percentile response time goal of 90% completing in half a second, with importance of 3

 Transactions that accumulate 300 service units (DUR = 300) before completing migrate to Period 2

• New service class period; WLM manages the transactions in period 2 to the goal of 90% completing in 4 seconds, with importance of 4
• This means, 90% of those that did not complete in period 1

Transactions that accumulate 900 service units (DUR 300 + DUR 600) before completing migrate to Period 3

• A new service class period; WLM manages the transactions in period 3 to a velocity goal of 40, with importance of 5

"Service units" is a hardware independent measure of CPU consumption. If your transaction consumes 1000 service units on a z13, it should consume 1000 service units on a z14, z15 or z16 (and so on)

WLM managed delays

Processor
Dispatching priority

Non-paging DASD I/O
IOSQ, subchannel pending, control unit queue

Storage
Paging, swapping

Tasks
Multi-programming level, server address space creation
- e.g. WLM address spaces for external stored procedures

WLM cannot manage
-User delay
-Network delay
Any resources or delays not listed at right are shown as UNK (unknown)

Service class periods

WLM heuristic behavior is applied to service class periods

WLM can effectively manage 25-30 active service class periods

• If you have more than 30 active service class periods, WLM may not be able to adjust resources for all of them when the system is busy
• It is precisely when the system is busy that you want WLM to adjust resources to meet your business goals

"Loose" goals are performance goals that are too easily achieved

• Service class periods with loose goals are likely to have a PI < 1, so WLM will always perceive they are meeting their goals.
• Service class periods with loose goals may have a PI < 0.7, in which case they may become a donor
  • WLM may reduce resources for donor service class to apply to recipient service class (one with PI > 1)
    

 Defining Db2 address spaces to WLM

Db2 address spaces are started tasks

• To WLM, the Db2 address spaces have a subsystem type of "STC"

 IRLMs should be defined in service class SYSSTC

Remaining Db2 address spaces should be assigned to a service class with a single period, a velocity goal and appropriate importance. For example,

• Production: IMP 1
• QA, Development and/or Test in same LPAR/Sysplex:
  • IMP > 1 (i.e. lower importance)
  • Adjust based on other production work, such as production batch
• Db2 address spaces include ssnmMSTR, ssnmDBM1, ssnmDIST and ssnmWLMx for stored procedures

Three types of Db2 work

Local subsystem

Allied threads
-CICS
-IMS
-TSO
-WebSphere on zSystems
-MQ on zSystems

DDF threads

DDF requests use enclave SRBS
- zIIP-eligible 

Stored procedures

External stored procedures run in WLM application environments
Native SQL procedures run in DBM1 address space

First type: local attach

Db2 SQL activity runs under dispatchable unit of invoker

• IMS, CICS, TSO, Batch, etc.
• Inherited classification class of invoker
• Priority and management of home unit
• Service attributed back to invoker

 Second type: DDF and enclave SRBs

Why do we need enclaves?

-Manage DDF work separately from ssnmDIST

-Differentiate between high priority and low priority DDF work

Classifying DDF work

Define service classes and appropriate goals for DDF work

DDF Classification Defaults

• Defaults apply if you do not provide any classification rules for DDF work
• Enclaves default to the SYSOTHER service class (i.e. discretionary goal) unless they can be assigned to a service class

Managing DDF Work (Enclaves)

• All goal types are permitted
• Transactions may be subject to period switch
• WLM manages an enclave with its own dispatching priority, etc.

High performance DBAT DDF transactions, we must use velocity goal

WLM Notes

 
1. Goal Definition & Performance Index (PI)
 
Execution velocity goals

• Are very sensitive to configuration changes

 
Unachievable/Unrealistic velocity goals – ie. goal of 90
– Check velocities of SYSTEM and SYSSTC to determine highest achievable velocities
– Smaller n-way partitions will necessitate lower velocity goals
 
A velocity of 99 (conceptually 100) is not physically attainable. This means that the service class is always going to under achieve (PI > 1) so WLM is always going to try to give it more help unless or until the PI gets over 4. At that point it will give up trying to help and performance can get considerably worse.
 
Define the Goals
 
Base your definitions on measurements -

• Especially execution velocity goals can’t be defined without knowing the data

• Use periods of high utilization or contention as a base

 
If you want that WLM always keeps an eye on your service class
 

• Define a tight goal:

• 0.9 < PI < 1.2

• A little bit high temperature isn’t a bad thing

• Only if that doesn’t really help use CPU or Storage Critical

• Can be avoided in many cases

 
Always define goals based on measurement intervals of high system utilization or high system contention periods. This gives you the best indication of whether the goals can be achieved.
 
You should base goals on what can actually be achieved, not what you want to happen. The goals you set are how WLM knows whether your system is running OK, or whether it needs to make changes. If you set goals higher than necessary, WLM moves resources from lower importance work to higher importance work which might not actually need the resources.
 
Velocity goals should be set with a difference of at least 10 to be effective and meaningful – Any service classes with goals closer than 10 should be evaluated to be combined into one service class
 
 
2. Protecting Work & CPU Management
 
Protecting Work: CPU
 
To avoid that lower important work may get a higher dispatch priority than higher important work
 
= Define a tight goal!

• 0.9 < Performance Index < 1.2

• Ensures that a high important service class does not become donor

• But also requires a “constant” flow of work

= Or use CPU Critical as the last resort
 
CPU Critical only protects that work from lower importance work, no protection from work at same or higher importance, better to have the right goal
 
3. CPU Critical Usage Guidelines
 
When to use CPU Critical?
 
Use it seldom
 

• For 1 or 2 service classes

• At best only for importance 1

• Suited is work which doesn’t consume much CPU, which doesn’t show high consuming CPU spikes, and which needs fast access to CPU

• Examples:

• Critical server address spaces

 
Rule: use the similar rule of thumb for work which you would place in SYSSTC
 

• To SYSSTC

• Less than 20% of 1 logical processor

• No high consuming CPU spikes

• CPU Critical

• Less than 5 to 10% of total system consumption (depending on size of system)

• No high consuming CPU spikes

 
When running CICS/IMS with response time goals, and CPU critical is necessary, designate both regions and transactions as CPU critical
 
4. Discretionary Work & Capping
 
Discretionary work
 
In order to better help discretionary work get a chance to run, certain service class periods may become donors to discretionary work:
◦ Velocity goal of 30 or less or response time goal > 1 minute
◦ PI <= 0.81
◦ Not part of a resource group
 
In some cases, velocity goals of 31 (instead of 30) have been used to avoid becoming a donor
 
What to do if you don't like discretionary goal management (capping of work)
 

• Define a resource group without minimum and maximum

• Put service class with a goal eligible for capping into this resource group

• Capping will not take place !!

 
5. Service Class Design & Classification
 
Classify Work
 
Make sure that something really executes in your service classes

• Don’t define anything with less than 2% of CPU resource consumption

• BUT: classify distinct work to distinct service classes, for example:

• Don’t classify short living enclaves and STCs together

• Never classify CICS/IMS transactions together with anything else

• If you use multiple periods

• Make sure that some substantial amount of work is really ending in those periods

• More than 3 are very often counter productive

 
Not more than 25 (max 35) [actively running] service class periods with non discretionary goals
 
Service classes should only be defined for work when sufficient demand exists for them in the system. You can measure the demand either by the service consumption or by the amount of ending transactions during high utilization periods of this work. It probably does not make sense to define service classes with a demand of less than 1% of measured service units at any period or less than 1 transaction ending per minute. It is usually better to combine this work with other similar work
 
And as always, keep number of active service class periods to a range of 25 to 35!!!. Note that service classes with discretionary goals do not count, because they are not managed to goals.
 
6. Resource Groups
 
How to use Resource Groups
Use of minimum

• For medium and lower important work which need to make some progress

• But be very careful

• A resource group minimum supersedes all goals and all importance

• That means the resource group minimum comes first

 
To handle runaway jobs or transactions, consider creating a “sleeper” service class.
Associate the service class with a Resource Group and specify a maximum service unit capacity of 1. “Quiescing a batch job” on page 208 of “System Programmers Guide to Workload Manager” manual shows you how to use this Resource Group setting for batch and you can use this example in other cases.
 
7. SYSSTC / SYSOTHER & Special Classes
 
Unclassified work will default to one of two places
– Started Tasks default to SYSSTC
– All other work defaults to SYSOTHER
 
Recommendations for SYSSTC
– DB2IRLM and IMS IRLM – Lock manager needs high dispatching priority in order to let work flow properly through the system
– “Emergency” TSO ID – Only one TSO ID should be defined to SYSSTC
• All other TSO IDs should be grouped together, no special high priority service class for system programmers or management
 
Monitor the SYSSTC service class’s CPU usage. If high importance and online systems experience delay caused by SYSSTC, adjust SYSSTC by moving heavy CPU users to a different service class.
 
Consider creating a special high velocity, high importance TSO service class for emergencies. If the system hangs, you can use the RESET command to assign your TSO user ID to this class to allow you to investigate. Note that you might still need to wait for WLM to identify that this service class is delayed and adjust its priority. Assigning the TSO user ID to SYSSTC is an alternative.
 
8. CICS & IMS Management
 
Management: CICS and IMS
 
WLM Puts regions which process the same set of transactions to internal service classes
 
WLM creates internal service classes up to 2n-1
 
Only create different service classes if the work really executes in different regions otherwise the result is unpredictable
 
9. CICS & IMS – Goals (Response Time vs Velocity)
 
CICS and IMS – R.T. or Velocity Goal?
Which is the better way to manage online work?
Remember, WLM will set dispatching priority for the region
– Need to have the CICS and IMS Regions dispatched properly
– CICS and IMS have their own internal routines to decide which to run within their regions
– If transactions 0101 and PRD1 both run in AOR1, CICS will decide which to dispatch, NOT Workload Manager
 
Velocity Goals for CICS and IMS
Velocity goals are acceptable for environments with only one partition, or sysplexes with similar sized partitions
– A sysplex with a 4-way and a 20-way may not be a good candidate
 
Can be used when the nature of online transactions does not make classification of transactions goals reasonable
– Vastly different types of transactions would skew response time distribution data
– Two transactions service classes in same region will get same dispatching priority
 
Velocity goals do need to be monitored and may need to be adjusted during any processor changes
– Processor upgrades, LPAR definition changes, etc.
 
Response Time Goals for CICS and IMS
3 major advantages of response time goals
– Easier to understand and can be set to a business SLA
– Normally no need to change when environment is changed
– Can use same goal across entire parallel sysplex, regardless of individual partition size/speed
 
WLM needs to see at least three transactions complete within a 20-minute interval to get useful statistics for a response time goal
 
10. CICS/IMS Special Handling & Best Practices
 
Response Time Goals for CICS and IMS
You may want to exclude test work from being managed towards response time goals
à Too few transactions, no constant utilization and/or no need to manage it in a sophisticated way
 
Execution Velocity Goals for CICS and IMS
Make sense for test environments
à Without a constant flow of transactions
à If test and production runs on the same system or sysplex
à Use response time goals for production
à Use execution velocity goals for test
à Exempt test regions from response time management (Option: REGION)
 
Problem
à CICS TOR need fast access to CPU to get work in and out of the system
à CICS TOR have to wait behind AORs
      à Same dispatch priorities
 
Solution
à De-couple TORs from response time management but ensure that response time management remains in tact
à Option BOTH
 
 
CICS and IMS: Option BOTH
à What to do
      à Separate CICS TORs and AORs to different service classes
      à TOR service class
           à Set to importance 1, define a “high” execution velocity goal, CPU Critical may be an option too
      à Exempt the TORs from being managed towards response time goals by using option BOTH
           à This ensures that the end-to-end context for CICS transactions remains in tact
           à This ensures that CICS transactions (and the AORs) are still managed towards response time goals
           à This maintains all reporting features for CICS
 
à Why does it work
     à Typically TORs (as well as IMS CTL) only consumes 5 to 10% of the CPU of all CICS/IMS work
 
 
11. Transaction & Address Space Behavior
 
Address space classification in transaction management mode
You always need to classify the address spaces through the STC or JES subsystem classification rules. You only use the assigned service class goal during initialization and termination of the address space. The assigned service class goal is also used when there is no transaction during one minute.
 
The CICS address space receives resources and has a dispatching priority. A CICS transaction runs with the resources and dispatching priority of the CICS region. So, we recommend that you have more Application Owning Regions (AORs) than service classes on each z/OS image to make workload management via WLM easier. This decreases the chance of transactions with different goals executing in the same address space. If it happens, the transactions with less aggressive goals get a “free ride,” while WLM tries to honor the more aggressive and more important goals.
 
12. Multiple Periods & Monitoring
 
Notes on Multiple Periods
Workload Manager makes better decisions when there are more samples per service class period
Review RMF Workload Activity Report for service class utilization by period
 
If one period of a multi-period service class is always much smaller than the other periods, consider consolidation
 
For example, typical utilization pattern of three period service class
– SCLAS Period 1 – APPL% = 71.1
– SCLAS Period 2 – APPL% = 0.37
– SCLAS Period 3 – APPL% = 138.0
 
In this case, period 2 should either be combined with 1 or 3
 
13. Effect of diverse mix of Trasactions in CICS/IMS regions
 
If there are too many service classes for CICS or IMS with response time goals, the management of these transactions can become a little unpredictable, because WLM manages the regions based on the mix of transactions that runs in these regions.
 
If this mix is too diverse or even if there are just a few service classes with response time goals but some of them with low activity, the mix can end in unpredictable results from a management point of view.
 
This is one of the reasons why you might want to consider whether the response time goals for CICS and IMS are the best choice for your installation. Execution velocity goals might have their downsides, but they are much easier to correlate to what is running on the system
 

Running a job at a specific time every day without using a job scheduler

This post explains how to automate the repeated submission of a job using JCL, SORT, and a dataset/member where the job is stored.

Sample Job

/MYUSERRR JOB ,'REPEAT',MSGCLASS=F,COND=(4,LT),

//         CLASS=A,REGION=0M,NOTIFY=&SYSUID

//*

// SCHEDULE HOLDUNTL=('05:00','2026/141')

//*

//NEXTJOB  EXEC PGM=SORT

//SYSOUT   DD SYSOUT=*

//SORTIN   DD DISP=SHR,DSN=MYUSER.JCL(REPEAT)

//SORTOUT  DD SYSOUT=(,INTRDR)

//SYSIN    DD *

    OPTION COPY

    OUTFIL IFTHEN=(WHEN=(1,21,CH,EQ,C'// SCHEDULE HOLDUNTL='),

           BUILD=(1,23,C'05',26,6,DATE3(/)+1,40,41)),

           IFTHEN=(WHEN=NONE,BUILD=(1,80))

/*

//* PUT REST OF JOB AFTER THIS COMMENT

In the above job you have to change the job card to make it work at your installation. Whatever you want the job to do every hour or day or week or month or ... you will have to append in additional steps. The above job will run every day at 5am except for the first time.   

• If the scheduled time has already passed at submission, the job starts immediately.
• If the scheduled time is in the future, the job remains in HELD status until the specified time.

Please remember to save the JCL in MYUSER.JCL(REPEAT) before you submit it the first time.

 

So what is actually going on? SCHEDULE makes the job start at the specified time on the specified day. SORT reads the JCL from SORTIN and copies it to SORTOUT which submits it again. During the copy SORT edits the contents of the SCHEDULE card and adds one to the current date (DATE3(/)+1) which delays the execution of the job until next day at 5am. You can choose to add 7 instead if the job is supposed to run once a week or add some other value. The amazing thing is the ability to control the time of day, too. I have just chosen to let the job start at 5am. You can use some of the functionality in the BUILD function in SORT to make the job run every hour or every second hour or whatever you need.

 

Please be aware that when you make changes to the JCL in MYUSER.JCL(REPEAT) it will not take effect until after the next time the job is executed as the job waiting to be executed next time is sitting in the input queue in JES. If you want your change to have immediate effect you must cancel the job in JES and then submit your changed job with a SCHEDULE card holding the time and date for the next execution. The job will survive an IPL so you do not have to worry about that.

 

 

DB2 SQL to find tables used by a program

Below SQL to returns the list of tables used by a latest version of a program 

WITH TEMP(COLLID, NAME, CONTOKEN) AS(                    

     SELECT COLLID, NAME, CONTOKEN                       

     FROM SYSIBM.SYSPACKAGE                              

     WHERE (LOCATION,COLLID,NAME,BINDTIME) IN (          

           SELECT LOCATION,COLLID,NAME,MAX(BINDTIME)     

           FROM SYSIBM.SYSPACKAGE                        

           WHERE NAME = 'program_name'                       

          GROUP BY LOCATION,COLLID,NAME                  

       )                                                 

)                                                        

SELECT SUBSTR(T.NAME,1,8) AS PROGRAM,                    

SUBSTR(BQUALIFIER,1,8) AS QUALIFIER,                     

 SUBSTR(BNAME,1,30) AS TBL_NAME,                         

 BTYPE                                                   

 FROM SYSIBM.SYSPACKDEP,TEMP T                           

WHERE DCOLLID = T.COLLID                                 

 AND  DNAME   =  T.NAME                                  

 AND  DCONTOKEN = T.CONTOKEN                             

 AND BTYPE = 'T'                                         

WITH UR;                                                 

Defining GDGs with more than 255 generations

Generation Data Groups (GDGs) can be defined with more than the traditional 255 generations by using the LIMIT parameter in conjunction with the EXTENDED attribute. These parameters control the maximum number of Generation Data Sets (GDSs) that can be associated with a GDG.

Source : https://www.ibm.com/docs/en/zos/3.1.0?topic=dgp-required-parameters
LIMIT(limit)
Specifies the maximum number, from 1 to 255, of GDSs that can be associated with the GDG being defined. If EXTENDED is specified, 1 to 999 GDSs can be associated with the GDG being defined.

Source: https://www.ibm.com/docs/en/zos/3.1.0?topic=dgp-optional-parameters
EXTENDED|NOEXTENDED
Specifies whether the GDG is to be an extended GDGr or not.
     EXTENDED
        allow up to 999 generation data sets (GDSs) to be associated with the GDG.
        Abbreviation: EXT
 
     NOEXTENDED
        allow up to 255 generation data sets (GDSs) to be associated with the GDG. This is the default value.
        Abbreviation: NEXT
 
Sample JCL to define a GDG with 999 Generations
 
//STEP1    EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE GDG(NAME(USERID.GDG.LIMIT999) -
             EXTENDED                  -
                   LIMIT(999)                -
                   NOEMPTY                   -
                   SCRATCH)
/*
 
Converting a NOEXTENDED GDG to a EXTENDED GDG
 
Source:  https://www.ibm.com/docs/en/zos/3.1.0?topic=generationdatagroup-converting-noextended-extended
 
You can use the following procedure to convert a generation data group defined as NOEXTENDED to one that is EXTENDED. IBM advises that the original user catalog should be backed up before starting the procedure.

1. Define a temporary user catalog.
2. REPRO MERGECAT the GDG from the original user catalog to the temporary user catalog. This moves the GDG and all GDSes to the temporary user catalog and removes them from the original user catalog.
3. DEFINE a new GDG with the same name as the original GDG specifying the EXTENDED parameter and a new LIMIT parameter as desired.
4. REPRO MERGECAT only the GDSes using wild card notation from the GDG in the temporary user catalog into the new GDG now in the original user catalog.
5. Use DELETE RECOVERY to delete the temporary user catalog.

The process is complete. You can use LISTCAT to prove that the new GDG has the EXTENDED attribute and that a new LIMIT has been set.

Example JCL and IDCAMS statements:
 
//* GDG NOEXTENDED TO GDG EXTENDED CONVERSION
//*
//CONVERT EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
/* 1. DEFINE A TEMPORARY CATALOG */
 
DEFINE -
UCAT -
(NAME (TEMP.UCAT) STORCLAS(SMSSTORC) -
CYL (1 1))
 
/* 2. REPRO GDG AND GDSES TO THE TEMPORARY CATALOG */
 
REPRO -
INDATASET(ORIG.CAT) -
OUTDATASET(TEMP.UCAT) -
ENTRIES(SMSA.GDG) -
MERGECAT
 
/* 3. DEFINE GDG EXTENDED IN THE ORIGINAL CATALOG */
 
DEFINE GDG (NAME(SMSA.GDG) -
EXTENDED LIMIT(999) SCRATCH PURGE)
 
/* 4. REPRO GDSES BACK TO THE ORIGINAL CATALOG */
 
REPRO -
INDATASET(TEMP.UCAT) -
OUTDATASET(ORIG.CAT) -
ENTRIES(SMSA.GDG.*) -
MERGECAT
 
/* 5. DELETE TEMPORARY CATALOG */
 
DELETE TEMP.UCAT USERCATALOG RECOVERY
/* LISTCAT TO SHOW EVERYTHING BUILT CORRECTLY */
 
LISTCAT ENTRY(SMSA.GDG) ALL
/*
 
 

Limiting Storage use above the bar in z/Architecture

 The below article was copied from https://www.ibm.com/support/pages/limiting-storage-use-above-bar-zarchitecture

As in the 31-bit address space, a virtual "line" marks the 16-megabyte address. The 64-bit address space also includes the virtual line at the 16-megabyte address; additionally, it includes a second virtual line called the bar that marks the 2-gigabyte address. The bar separates storage below the 2-gigabyte address, called below the bar, from storage above the 2-gigabyte address, called above the bar. The area above the bar is intended for data; no programs run above the bar. There is no area above the bar that is common to all address spaces, and no system control blocks exist above the bar. You can set a limit on how much virtual storage above the bar each address space can use. This limit is called the MEMLIMIT . If you do not set MEMLIMIT, the system default is 0, meaning no address space can use virtual storage above the bar (Use of real storage above the 2GB is not controlled by this parameter). If you want to use virtual storage above the bar, you need to set the MEMLIMIT explicitly. You can set an installation default MEMLIMIT through SMFPRMxx in PARMLIB. You can also set MEMLIMIT for a specific address space in the JCL that creates the address space or by using SMF exit IEFUSI.

To use virtual storage above the bar, a program must request storage above the bar, be in AMODE 64 and use the new z/Architecture assembler instructions.

SMF MEMLIMIT Parameter 

An installation can set the default MEMLIMIT through SMFPRMxx in PARMLIB.

MEMLIMIT(NOLIMIT)

nnnnnM

nnnnnG

nnnnnT

nnnnnP

This specifies the default MEMLIMIT to be used by jobs not establishing a MEMLIMIT in their JCL. For reference see z/OS MVS JCL User's Guide . NOLIMIT means that there is no limit on the use of virtual storage above 2 gigabytes.

MEMLIMIT values are defined with nnnnnM for megabytes, nnnnnG for gigabytes, nnnnnT for terabytes, or nnnnnP for petabytes. For example, to request 1200 gigabytes, you can specify MEMLIMIT(1200G). D SMF,O operator command displays the current MEMLIMIT, as shown in example below:

RESPONSE=SYSA

IEE967I 15.39.05 SMF PARAMETERS 795

MEMBER = SMFPRMZ3

MULCFUNC -- DEFAULT

MEMLIMIT(00000M) -- DEFAULT

DDCONS(YES) -- DEFAULT

LASTDS(MSG) -- DEFAULT

NOBUFFS(MSG) -- DEFAULT

DUMPABND(RETRY) -- DEFAULT

SUBSYS(OMVS,NODETAIL) -- SYS

SUBSYS(OMVS,TYPE(0,30,70:79,88:90,103,245)) -- PARMLIB

SUBSYS(OMVS,INTERVAL(SMF,SYNC)) -- PARMLIB

SUBSYS(OMVS,NOEXITS) -- PARMLIB

SUBSYS(STC,NODETAIL) -- SYS

Note: If MEMLIMIT is not specified in SMFPRMxx, the default value is 0M.

MEMLIMIT on JOB and EXEC Statement 

MEMLIMIT is a new keyword on the JOB and EXEC statements. MEMLIMIT specifies the limit on the total number of usable virtual storage above the bar for a single address space.

While there is no practical limit to the virtual storage above the bar, there are practical limits to the real storage frames and auxiliary storage slots backing the virtual storage area. To control the amount of real and auxiliary storage an address space can use for memory objects at one time, your installation should establish an installation default MEMLIMIT to set the total amount of usable virtual pages above the bar for a single address space. You set this default on the MEMLIMIT parameter in the SMFPRMxx parmlib member, or through the SET SMF or SETSMF commands. This default takes effect if a job does not specify MEMLIMIT on the JOB or an EXEC statement or REGION=0M in the JCL; the MEMLIMIT specified in an IEFUSI exit routine overrides all other MEMLIMIT settings.

The system enforces the MEMLIMIT when you issue the IARV64 GETSTOR and CHANGEGUARD services. When your unconditional request for new storage (either for a new memory object or for more usable storage in an existing memory object) causes the MEMLIMIT to be exceeded, the system abends the program. IBM recommends programs use the COND parameter to make a conditional request and check the return code to make sure the storage is available.

What happens to the MEMLIMIT for an already-created address space if a SET SMF or SETSMF command changes the default MEMLIMIT (either the system default or the installation default)?

If the command raises the current default MEMLIMIT, all address spaces whose MEMLIMIT was set through SMF run with the higher default.

If the command lowers the current default MEMLIMIT, all address spaces whose MEMLIMIT was set through SMF keep their original system default.

A SET SMF or SETSMF command cannot change the MEMLIMIT value set through JCL or by an IEFUSI installation exit.

MEMLIMIT Enforcement Through IEFUSI 

The SMF IEFUSI exit can change the MEMLIMIT value by updating the value in the third double word. But the publication failed to mention the value used is in the unit of MB (for example, 00000000 00008400 is 33 GB).

The z/OS 1.2 MVS Installation Exits manual does not describe the meaning of the flags in the first double word. The z/OS 1.2 book contains a NOLIMIT value of FFFFFFFF FFFFF000, which is incorrect. Both of these errors have been corrected in the z/OS 1.3 publication. The z/OS 1.2 and z/OS 1.3 books do not mention the unit of MB in the third double word

When IEFUSI Exit receives control, Register 1 points to a list of addresses. Word 9 contains the address of an area, as described in the z /OS 1.3 MVS Installation Exits :

 Word 9 

 The address of an area consisting of three 64-bit fields: 

 | A 64-bit flagword. The first 8 bits indicate whether the 

 | source of the MEMLIMIT is from JCL or the SMF-supplied 

 | system default. The remaining 56 bits are not used. Possible 

 | values for the first 8 bits, and their meanings are as 

 | follows: 

 | 01 -- indicates MEMLIMIT is from SMF 

 | 02 -- indicates MEMLIMIT is from JCL 

 | 03 -- indicates MEMLIMIT was set to NOLIMIT because JCL 

 | specified REGION=0 

 | FF -- indicates MEMLIMIT is from SMF (indicative of 

 | internal processing errors) 

 | Note: Other values are possible when initializing a child 

 | address space in the UNIX System Services 

 | environment. See UNIX System Services publications 

 | for more information. 

 | The 64-bit MEMLIMIT originally requested by the source that 

 | is specified in the flagword. 

 | The 64-bit MEMLIMIT requested by the IEFUSI exit. The 

 | initial value is X'FFFFFFFFFFFFFFFF' to indicate that no 

 | value was set by the exit. If not changed, SMF uses the 

 | MEMLIMIT that was originally requested. 

 Note: A MEMLIMIT of NOLIMIT is equivalent to X'00000FFFFFFFF000'. 

The REGION JCL Parameter

The below article was written by by Jim Moore NASPA website which is no longer available

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?

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.

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


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

Below is a sample COBOL program that displays current/maximum REGION values below and above the line.

       ID DIVISION.

       PROGRAM-ID.  REGION.

       ENVIRONMENT DIVISION.

       DATA DIVISION.

       LINKAGE SECTION.

      * --- MAP PSA  --------------------------------------

       01  PSA.

           02   FILLER                 PIC X(548).

           02   PSAAOLD                POINTER.

      * --- MAP ASCB  -------------------------------------

      * MACRO IHAASCB

       01  ASCB.

           02   FILLER                 PIC X(48).

           02   ASCBLDA                POINTER.

           02   FILLER                 PIC X(120).

           02   ASCBJBNI               POINTER.

           02   ASCBJBNS               POINTER.

      * MACRO IHALDA

       01  LDA.

           02   FILLER                 PIC X(204).

      * REGION SIZE REQUESTED IF LDAREGNX = 1, ADJUSTED SUM OF BOTH

      * REGIONX PARAMETERS

      * THE REGION VALUE FROM EITHER A LOGON SCREEN (POSSIBLY DEFAULTED)

      * OR AN EXIT

           02   LDAREGRQ               PIC 9(09) COMP-5.

      * < 16M V=V REGION LIMIT VALUE

      * MAXIMUM AMOUNT OF 24-BIT STORAGE ALLOWED

           02   LDALIMIT               PIC 9(09) COMP-5.

           02   FILLER                 PIC X(04).

      * > 16M V=V REGION LIMIT VALUE

      * MAXIMUM AMOUNT OF 31-BIT STORAGE ALLOWED

           02   LDAELIM                PIC 9(09) COMP-5.

           02   FILLER                 PIC X(12).

      * < 16M USER REGION ALLOC VALUE

      * CURRENT AMOUNT OF USED 24-BIT STORAGE

           02   LDALOAL                PIC 9(09) COMP-5.

           02   FILLER                 PIC X(04).

      * > 16M USER REGION ALLOC VALUE

      * CURRENT AMOUNT OF USED 31-BIT STORAGE

           02   LDAELOAL               PIC 9(09) COMP-5.

       01  STCNAME                     PIC X(8).

       01  JOBNAME                     PIC X(8).

       PROCEDURE DIVISION.

           SET ADDRESS OF PSA TO NULL.

           SET ADDRESS OF ASCB TO PSAAOLD.

           SET ADDRESS OF JOBNAME TO ASCBJBNI.

           SET ADDRESS OF STCNAME TO ASCBJBNS.

           DISPLAY "(DZSCOB1) " STCNAME ", " JOBNAME.

           DISPLAY "ASCB: " ASCB(1:4)

           SET ADDRESS OF LDA     TO ASCBLDA

           DISPLAY 'THE REGION VALUE FROM EITHER A LOGON SCREEN OR'

                   ' AN EXIT : ' LDAREGRQ

           DISPLAY 'MAXIMUM AMOUNT OF 24-BIT STORAGE ALLOWED : '

                LDALIMIT

           DISPLAY 'MAXIMUM AMOUNT OF 31-BIT STORAGE ALLOWED : '

                LDAELIM

           DISPLAY 'CURRENT AMOUNT OF USED 24-BIT STORAGE : '

                LDALOAL

           DISPLAY 'CURRENT AMOUNT OF USED 31-BIT STORAGE : '

                LDAELOAL

           GOBACK.