Where does IMS fit into the z/OS world

IBM Corporation 2016

Jeff Maddix

Silicon Valley lab

[email protected] / 408-463-4956

Where Does IMS Fit into the z/OS World?

Where Does Your Application Fit into the IMS World?

This presentation brings you inside inside a zEnterprise server world to familiarize you with the way IMS fits into z/OS and where your application exists within the IMS

subsystem.

The information within can be used as reference material to understand where your application is running when a software error is encountered.

This reference material outlines the following information:

IMS address space relationships

IMS MVS task structure (TCBs) within those address spaces

MVS storage layout within address spaces

Major IMS control block relationships between the MVS Tasks and IMS ITASK structure

IMS control block linkage between control blocks with information about your running applications

IMS savearea set utilization

Agenda

2

ONLINE IMS ASID STRUCTUREONLINE IMS ASID STRUCTURE

Possible Xmemory access from and between IMS address spaces

DB2 APPC IRLM Others

DL/I

SASCTL

...

DRA

CCTL MPP BMP IFP

Multiple application threads per address space for each CCTL and ODBA region

Your application programs run in the green address spaces in this bottom row

JMP JBP

MQSeries RRS

Appl Region

ODBA

WLMWLM

SPOC SPOC

TCPIP

VTAM Console

WEBSPHERE

IXGLOGR

IMS Connect (BPE)IMS Connect (BPE)

...

Tools Tools

...

DBRC(BPE Optional)

CQS(BPE)

OMCSL(BPE)

RMCSL(BPE)

SCICSL(BPE)

ODBMCSL(BPE)

3

NOTESNOTES

The MVS address space (AS) relationship is important to you because it provides a framework which you can later use to isolate IMS problems to the source of failures.

This diagram represents the address spaces associated with an IMS online region.

The DRA (Database Resource Adapter) allows a non-IMS transaction management subsystem to access full function databases and Fast Path DEDBs through the DRA. The DRA and the transaction management subsystem (referred to as CCTL) exist in the same AS.

The CCTL (Coordinator Controller Address Space) region connects to the IMS control region via multiple DRA threads. The total combination of dependent region connections and DRA threads cannot exceed 999 (IMS V12), or 4095 (V13 and above).

ODBA (Open Database Access) interface code resides in the application region (Websphere, WLM established DB2 Stored Procedures, or other application region all of which use the RRS sync-point manager.

BPE (Base Primitive Environment) - Base code for control program like functions (Dispatching, Storage management, tracing, etc.)

4

NOTESNOTESNOTATION KEY:

APPC Advanced Program-to-Program Communication

BMP Batch Message Processing Dependent Region APPL Region

BPE Base Primitive Environment

CSL Common Service Layer

CCTL Coordinator Controller Address Space APPL Region

CTRL IMS Control Region

CQS Common Queue Server

DBRC Data Base Recovery Control Region

DL/I SAS DL/I Subordinate Address Space

DRA Database Resource Adapter APPL Region

IFP IMS Fast Path Dependent Region

IRLM IBM Resource Lock Manager

IXGLOGR MVS Logger Address Space

JBP Java Batch Processing Dependent Region APPL Region

JMP Java Message Processing Dependent Region APPL Region

MPP Message Processing Program Dependent Region APPL Region

ODBA Open Database Access APPL Region

ODBM Open Database Manager

OM Operations Manager

RM Resource Manager

RRS Resource Rec0very Services

SCI Structured Call Interface

SPOC Single Point of Control

WLM Workload Manager 5

RLM

*

CONTROL REGION TCB STRUCTURECONTROL REGION TCB STRUCTURE

STM

*

DLI

*

LOG

*

CTL

*

ESS

*

RST

*

RDS

*

DYA

*

CTX

*

XFP

*

DCC

*

MODSTC

LSD

*

LOGT ESI

* DYD

*

TRA

*

LUM

*

ALM

*

ALC

* TMC

*

LRM

*

DTT

*

SL0

*

RCF

*

LRD

*

ONLY IF

LSO=Y

* See Note 1 on the next page

... ..10..

...

XCF

*

RRS

*

SL1

*

ODM

*

ODS

* ......

RWM

*

RWD

* ......

OIC

*

OIM

* ...

OII

*

WTR

*

...

In addition, in every address space there are 3 to 4 additional MVS

TCBs (not shown here)

6

NOTESNOTES

This TCB list provides a framework from which to approach failures in IMS.

This diagram represents the IMS Control region TCB (Task Control Block) structure and includes many of the possible TCB combinations. Depending upon the run-time and SYSGEN options specified, not all TCBs depicted will necessarily exist in an IMS Control Region. In addition, some IMS related tools might add their own functional TCBs to the IMS Control Region.

Not shown are the three (if the region is a started task) to four (if the region is started via an initiator - Job) MVS TCBs that precede the job step in each address space. MVS TCBs include the region control task, dump task and the single started task TCB or two initiator TCBs.

MVS dispatches independently executable tasks known as DUs (Dispatchable Unit). These DUs can be either TCBs (Task Control Block) or SRBs (Service Request Block).

It is important to note that most IMS code runs as MVS tasks and is mapped by the TCBs. TCBs contain data areas with footprint information that can be used to determine code paths and error conditions. We will explore he use of TCBs for debugging purposes later.

IMS has created these TCB structures to perform various functions. The table on the next page can be used to understand what type of processing is intended to be performed under a given TCB. If a failure occurs in an IMS subsystem, we can usually associate it with a given TCB and thereby get an idea about which process is failing.

Note 1: TCBs represented with an * are mapped by the IMS Dispatcher Work Area control blocks, which we will examine later.

7

TCB Acronym DefinitionsTCB Acronym Definitions

NOTATION KEY:

* = Mapped by an IMS Dispatch Work Area

Control Block

ALC Allocate LUM (Logical Unit Manager)

ALM ALUM (Asynchronous Logical Unit Mgr)

CTL Control TCB

CTX Control Region Auxiliary TCB

DCC Data Communications Control TCB

DLI Data Language I Master TCB

DTT DB Tracking TCB

DYA Dynamic Allocation Control Services

CTRL Region TCB

DYD Dynamic Allocation Daughter TCB

ESI External Subsystem Interface TCB

ESS External Subsystem Master TCB

LOG Physical Logger TCB

LOGT Log Timer TCB

LRD Log Router Daughter TCB

LRM Log Router TCB

LSD Local Storage Option Dependent TCB

LUM LUM (Logical Unit Mgr.) Master TCB

MOD Modify Command TCB

ODM ODBA(Open Database Access) Syncpoint

Mother TCB

ODS ODBA(Open Database Access)

Syncpoint Daughter TCB

OIC OTMA (Open Transaction Mgr

Access)IMS CTL TCB

OII OTMA (Open Transaction Mgr

Access)IMS INIT TCB

OIM OTMA(Open Transaction Mgr

Access)IMS Member TCB

RCF Allocate RACF TCB

RDS Restart Dataset TCB

RLM Receive LUM(Logical Unit Mgr)

RRS RRS Commit/Backout TCB

RST Restart TCB

RWM Online Recovery Main TCB

RWD Online Recovery Daughter TCB

SL0 Common Service layer TCB 0

SL1 Common Service layer TCB 1

STC Storage Compression TCB

STM Storage Management TCB

TMC Transaction Manager TCB

TRA External Trace TCB

WTR Console WTOR(Write to Operator

)

XCF LUM Cross-System Coupling

Facility Daughter TCB

XFP Fast Path Control TCB 8

MVS Storage SummaryMVS Storage SummaryView of MVS address space storage.

IPCS VERBX VSMDATA 'SUMMARY ASID(ddd)'

TCB Storage Area

APPL Storage

APPL Storage

9

MVS Storage SummaryMVS Storage Summary

Each address space in an z/OS system has direct addressability to X'FFFFFF' (24 bit mode), X'7FFFFFFF' (31 bit mode), or X'FFFFFFFF_FFFFFFFE' (64 bit mode) bytes of data.

Some of that data is commonly shared between all address spaces (such as CSA/ECSA, SQA/ESQA, ELPA/LPA, NUC/ENUC, etc.) and is known as global storage.

Some storage is unique to each Address Space. This unique area is known as private storage. Application program and data storage exists in the user region portion of private storage.

MVS TCBs (Task Control Block) exist in private storage (LSQA), which is unique to each address space. TCB storage will not exist in a dump dataset unless the TCB home address space private storage (LSQA or RGN) was included in the dump options.

10

DYD

TCB

*

DYD

TCB

*

DYD

TCB

*

DL/I SAS TCB STRUCTUREDL/I SAS TCB STRUCTURE

DLI

TCB

*

DYS

TCB

*

STC

TCB

DYD

TCB

* ...10...

DYD

TCB

*

In every address space there

are 3 to 4 additional MVS TCBs

(not shown here)

11

NOTESNOTES

This is the DL/I SAS (Subordinate Address Space) TCB structure. This region exists if LSO=S is included on the startup JCL.

Not shown are the three (if the region is a started task) to four (if the region is started via an initiator) MVS TCBs that precede the job step in each address

space.

NOTATION KEY:

* Mapped by an IMS Dispatch Work Area

... Multiple TCBs of this type are possible

DLI DL/I Master TCB

DYD Dynamic Allocation Daughter

DYS Dynamic Allocation Control Services

DL/I SAS Region TCB

STC Storage Compression TCB 12

DBT

TCB

*

DBT

TCB

*

DBT

TCB

*

CCTL or ODBA DRA TCB STRUCTURECCTL or ODBA DRA TCB STRUCTURE

DRA

TCB

*

...

Up to 999 (V12),

4095 (V13) total

threads possible.

Limited by DRA

MAXTHRD or IMS

MAXREGN

There will be many CICS

TCBs sharing this ASID, as well as the

standard 3 to 4 MVS TCBs, all

not shown here.

...

DBT

TCB

*

DBT

TCB

* DLI Calls are handled by the DBT TCBs. Connection from the application is made to the DBTs by schedule PSB (Program Specification Block) requests.

13

NOTESNOTES

These are the IMS CCTL DRA or ODBA TCBs. Keep in mind that the transaction

management subsystem also exists in this region. Therefore, you will see many more TCBs than the DRA TCBs shown.

If the problem occurs elsewhere, such as in the 3 to 4 z/OS TCBs or in the

transaction management subsystem, then diagnostic approaches used by those products would need to be used.

Not shown are the three (if the region is a started task) to four (if the region is

started via an initiator) MVS TCBs that precede the job step in each address space. The various TCBs utilized by CICS (of other CCTL applications) are also

not shown and may vary.

NOTATION KEY:



DBT Database Thread TCB

DRA DRA Master TCB

14

IMS DEPENDENT REGION TCB STRUCTUREIMS DEPENDENT REGION TCB STRUCTURE

RC

TCB

BMP

TCB

*

RC

TCB

MPP

TCB

*

IFP

TCB

*

MPP ASID BMP ASID IFP ASID

Application program runs under the last TCB of each dependent region

In every address space there are 3 to 4 additional MVS TCBs (not

shown here)

15

IMS DEPENDENT REGION TCB STRUCTUREIMS DEPENDENT REGION TCB STRUCTURE

JBP

TCB

*

RC

TCB

JMP

TCB

*

JMP ASID JBP ASID

In every address space there are 3 to 4 additional MVS TCBs (not

shown here)

Application program runs under the last TCB of each dependent region

16

NOTESNOTES

These are the IMS dependent region TCB structures for the MPP, BMP and

IFP regions respectively. Notice that the MPP and IFP regions both contain

two IMS defined TCBs of which only one is mapped by the IMS Dispatch Work

areas. The RC TCB can be located by using the TCBOTC field from the

mapped TCB. It points to the TCB that created it.

Not shown are the three (if the region is a started task) to four (if the region is

started via an initiator) MVS TCBs that precede the job step in each address

space.

NOTATION KEY:


Where nn = Hexadecimal Dispatch Type


RC Region Control TCB

BMP BMP Region / Program Control TCB

IFP IFP Program Control TCB

MPP MPP Program Control TCB

JMP JMP Program Control TCB

JBP JBP Region / Program Control TCB 17

IMS ITASK CONTROL IMS ITASK CONTROL

BLOCKSBLOCKS

18

IMS TASKS (ITASKs)IMS TASKS (ITASKs)

An IMS ITASK is a set of IMS control blocks that represent an IMS An IMS ITASK is a set of IMS control blocks that represent an IMS

dispatchable unit (DU).dispatchable unit (DU).

IMS ITASKs are set up to process various functions that IMS needs to IMS ITASKs are set up to process various functions that IMS needs to

perform in support of activity generated by the application systems, perform in support of activity generated by the application systems,

terminal networks, operator requests, region init/term, etc. terminal networks, operator requests, region init/term, etc. Your Your

application enters the IMS ITASK world when you issue your DLI callsapplication enters the IMS ITASK world when you issue your DLI calls

When the IMS Dispatcher determines that an ITASK is ready to run, it When the IMS Dispatcher determines that an ITASK is ready to run, it

will dispatch it under a specific MVS TCB.will dispatch it under a specific MVS TCB.

The specific relationships between the ITASK and MVS control blocks The specific relationships between the ITASK and MVS control blocks

can be followed to determine in which address space and TCB the can be followed to determine in which address space and TCB the

DU is currently associated.DU is currently associated.

19

IMS ITASK CTLBLK RELATIONSHIPS, ContinuedIMS ITASK CTLBLK RELATIONSHIPS, Continued

Think of each TCB as a server

Think of each ITASK as a client

Each TCB can service many

clients, but only 1 at a time.

Each ITASK has affinity to a given

TCB, but ISWITCH can be used to change

affinity to another TCB.

ITASK

STMTCB

*

...

...

ITASK

ITASK

* ITASK

ITASK

CTLTCB

*

...

...

ITASK

ITASK

* ITASK

DBTTCB

*

ITASK

ITASK

DLITCB

*

...

...

ITASK

ITASK

* ITASK

MPPTCB

*

ITASK

IFPTCB

*

ITASK

20

Tool TCB7Tool

TCB7Tool TCB7

MVS Dispaching TCBs Example MVS Dispaching TCBs Example

CPU 0

ITASK

IMSCTL TCB*

......

ITASK

ITASK

* ITASK

DB2 TCB3

CPU 1 CPU 2CPU 3

CTASK

CICSQRTCB*

......

CTASK

ITASK

* CTASK

ITASK

IMSDLI TCB*

......

ITASK

ITASK

* ITASK

CICS TCB2

CICS TCB5

DB2 TCB5

Resumed TCBs waiting for an available CPU on the MVS Work Unit Queue

ITASK

IMSDCC

TCB*

......

ITASK

ITASK

* ITASK

IMS Dep TCB*

DB2 TCB1

TSO TCB

Tool TCB7

.........

IMS dispaching code

holds the CPU until all ITASKs for the TCB are

completed. New ITASKs

can be added to the chain while processing

the others... :-)

ITASK

*

ITASK

IMSSTMTCB*

......

ITASK

ITASK

* ITASK

21

NOTESNOTESIMS ITASKs utilize ECBs (Event Control Blocks) to give control to the IMS dispatcher.

An ITASK ECB is awakened by a MVS POST or IMS IPOST macro

An ITASK ECB is put into an IMS wait state by an IMS IWAIT or ISERWAIT macro

TCB is removed form the CPU only if another ITASK is not ready to run in that TCB

An ITASK ECB is put into an MVS wait state by an MVS WAIT macro

TCB is removed from the CPU

ECB (MVS Event Control Block) 1 Word of storage

------------------------------------------------ W = Wait = x'80' bit on in high order byte

| WP (addr of post exit block) 11 | P = Post = x'40' bit on in high order byte

----------------------------------------------- 11 = MVS Post Exit indicator x'11' in low order nibble

When work is available for an MVS TCB, a MVS RESUME macro is used to signal to MVS that the TCB is available to be placed in a CPU to process that work request

An MVS TCB is put into a SUSPEND state by the MVS SUSPEND macro when no further work is available for that TCB

22

NOTESNOTES

Using IPOST/POST and post exit ECBs/ECBs, the IMS dispatcher gains control from the MVS dispatcher. It examines its own internal control blocks looking for dispatchable units of work. The IMS dispatcher will choose which ITASK to run on a combination of FIFO and ITASK priority levels.

The IMS dispatcher will pass control to the ITASK's processing routine.

The ITASK will eventually return to the IMS dispatcher when ready to relinquish control via IWAIT/ISERWAIT. The IMS dispatcher will then select the next ITASK and pass control to it. This continues until no ITASKs are available to run at which time the IMS dispatcher requests MVS to SUSPEND the TCB.

When an ITASK associated with a suspended TCB becomes ready to run after receiving an ECB IPOST/POST, the IMS Dispatcher will resume the

IMS TCB. MVS will then schedule the IMS TCB into a CPU when available. The IMS dispatch process repeats itselfs by dispatching the newly available ready ITASKs one at a time until all IMS work associated with that TCB has been completed and the TCB is SUSPENDed.

23

CHAIN

DSP

PTR

0

14

1C

4

4

4

A

A

A

EPF

DWA

SAP

LABEL OFST LEN T BLK NAME NT

IMS ITASK CTLBLK RELATIONSHIPSIMS ITASK CTLBLK RELATIONSHIPS

DECB

SMB

IPARM

PSB

NJOB

TPPCB

DBPCB

PSTNR

EPST

FUNCH

SAV1

SAV20

0

C4

E8

114

128

1C8

1CC

2F4

55C

1C0

5B8

B10

4

4

4

4

8

4

4

2

4

4

48

48

*

A

A

A

X

A

A

X

A

ECB

SMB

DLI Call Parm

PDIR

JOBNAME

TPPCB

DBPCB

SAP

EPST

CALL FUNCT

1ST SASET

20TH SASET

1

2

3

4

5

6

7

8

9

10

11

12


DATA AREAS DESCR

RBP

JSTCB

OTC

CMP

GRS

0

7C

84

10

30

4

4

4

4

48

A

A

A

RB

TCB

TCB

COMP CODE

GPRS 0-15

1

2

3

4

5


DATA AREAS DESCR

1

2

3

QPOST

CECB

HASID

CASID

CTRL1

PRB

TCB

RPSTN

RPST

DIAG

STCK

1C

28

30

32

3B

3C

40

54

58

110

D8

4

4

2

2

1

4

4

2

4

30

8

A

A

X

X

X

A

A

X

A

EPF

ECB

ASCB

ASCB

SAP

RB

TCB

PST

DPST

DIAG AREA

Susp/Res Time

1

2

3

4

5

6

7

8

9

10

11


DATA AREAS DESCR

FLAG1

SA1

IWAIT

ECB

IDNUM

CDSP

HDSP

FLAG1

1

10

14

18

20

24

28

0

1

4

4

4

2

4

4

0

X

A

A

A

X

A

A

DWA

SAVEAREA

SAVEAREA

ECB/PST/CLB PST

DWA

DWA

ITASK STAT

1

2

3

4

5

6

7

8


DATA AREAS DESCR

MVS TCB IMS DWA

IMS EPF (ECB Prefix)

IMS PSTHoldsApplicationDLI Calland DB info

IMS SAP

TCB Related - One per TCB

ITASK Related - One per ITASK

IMS EPST

DMHR 60 4 A DMAC


1

IMS PST

24

NOTESNOTESThe IMS and MVS control blocks listed on this page provide access to some of the most relevant error information sources involving ITASKs. With key information provided in these control blocks and in related

control blocks found through various dump formatting options, most software defects can be diagnosed.

Control Block Column Headings:

LABEL Label as seen in the MVS or IMS dump formatter

OFST Hex offset within the control block

LEN Hex length of the field

T Data type where: A = Address of block in "BLK NAME" column

X = Cross reference data to the "BLK NAME"

block

* = Indicates that the "BLK NAME" block

exists in this block at the current

offset

BLK NAME Name of the control block referenced by this field

NT Note reference number. See Note Reference Tables below

DATA AREAS Data areas of interest within this control block

25

NOTESNOTESMVS TCB (Task Control Block) Note Reference Table:

1. Points to the last RB (PRB, SVRB, IRB) for this TCB.

2. Points to the job step TCB for this address space.

3. Points to this TCB's mother TCB.

4. This contains the last abend completion code for this TCB.

5. General purpose registers for the last RB (See TCBRBP field) at the time of the dump.

IMS DWA (Dispatch Work Area) Note Reference Table:

1. Points to the posted ECB queue via EPF. Complemented pointer to this DWA if empty.

2. Points to the current ECB last dispatched to this DWA. This cross references uniquely to the related

ITASK SAPECB field. If a DWA for a dependent region, this points to the DPST.

3. ASID associated with this DWA. This is the home ASID for the TCB. The TCB exists in LSQA for this ASID.

4. ASID of the IMS Control Region. The IMS Control ASID is identified here regardless of the home TCB ASID.

5. Dispatcher type of this DWA. This cross references to the SAPFLAG1 field at offset X'01' but is not

always an one to one correspondence. 6. Pointer to the PRB that was last given control or that will gain control.

7. Pointer to the TCB with which this DWA is associated. Be sure to look for the TCB in the ASID from

note 3.

8. PST number. This is the hex version of the decimal output from the IMS DISPLAY ACTIVE or CCTL commands. It uniquely cross references the PSTNR field. It is only valid for dependent regions or

DBT threads.

9. Pointer to the dependent region PST associated with this DWA. Valid only for dependent region

threads

10. X'30' byte diagnostic area describing last abend. Valid for dependent and DBT DWAs only.

11. Time that this dispatcher work area ITASK was last suspended or resumed. Used for comparison

with dump time. This field is in IDSPWRK SECTION 2.

26

NOTESNOTESIMS EPF (ECB Prefix) Note Reference Table:

Note - The EPF precedes the IMS POST-EXIT ECBs. These ECBs are used with System PSTs, DPSTs, and CLBs.

1. Points to the next ECB on the DWA queue, or contains X'0FC4E2D7' (DSP) if not enqueued to the DWA.

2. Points to the current DWA.

3. Points to the current SAP associated with this ECB Prefix.

IMS SAP (Save Area Prefix) Note Reference Table:

1. Dispatcher type of this DWA. This cross references to the DWA CTRL1 field at offset X'3B' but is

not always a 1 to 1 correspondence.

2. Points to the 1st save area for this SAP.

3. In 'WAITING SAPs' points to the save area to be restored after IWAIT in 'ACTIVE non-WAITING

SAPs'

field is residual.

4. Points to the ECB associated with this SAP. The ECB is the first word of the PST for dependent

regions or system ITASKs and CLB for communication ITASKs.

5. PST number. This is the hex version of the decimal output from IMS DISPLAY ACTIVE or CCTL

commands. It uniquely cross references the PSTNR field but is only valid for dependent regions or

DBT threads.

6. Address of the current DWA. This value is different than HDSP if ISWITCHed to a TCB in an

address space other than its original address space.

7. Address of this ITASK's home address space DWA.

8. X'80' bit switched on means this ITASK is ACTIVE. X'40' bit switched on indicates that this ITASK is WAITING.

27

NOTESNOTESIMS PST (Partition Specification Table) Note Reference Table:

* If the ECB is not part of a dependent region thread (DPST), then the DB and TM related

fields will not be used.

* If the ITASK is data communications related, the ECB may be part of a CLB (Communication

Line Block) instead of a PST.

1 Note the EPF (ECB Prefix) precedes this ECB.

This ECB (Event Control Block) is the MVS Post Exit variety.

----------------------------------------------- W = Wait = x'80' bit on in high order byte

| WP (addr of post exit block) 11 | P = Post = x'40' bit on in high order byte

----------------------------------------------- 11 = MVS Post Exit indicator x'0011' in low order byte

2 Points to the assigned SMB if an IMS transaction is scheduled.

3 Points to the user DLI call parameter list relocated from user private to CSA.

Parameter list: DLI Call, PCB, I/O area, SSA (Structured Search Argument) if used.

4 Points to the PDIR which holds information about the PSB scheduled into the dependent region.

5 This is the jobname of the IMS dependent region or associated CCTL region.

6 TPPCB address used in last TP DLI call

7 DBPCB address used in last DB DLI call.

8 PST number. This is the hex version of the decimal output from the IMS DISPLAY ACTIVE or

CCTL commands. It uniquely cross references the SAP IDNUM and DWA RPSTN field. It is

only valid for dependent regions or DBT threads.

9. Points to the EPST - Extended PST for fastpath information related to this PST.

10 DL/I call function code (GU, GN, ISRT. etc)

11 First save area in the pre-chained save area set.

12 Last save area in the pre-chained save area set.

28

NOTESNOTESIMS EPST (Extended Partition Specification Table) Note Reference Table:

1 Points to the DMHR - FP DEDB Buffer Header Block.

DMHR+x'20' points to the DMAC

DMAC = FP DEDB Area control list

DMAC + x'4' = DEDB Name

+ x'C' = Area Name

29

IMS DB Control Block RelationshipsIMS DB Control Block Relationships

30

ITASK SAP / SAVE SET ITASK SAP / SAVE SET

00000000 A(SAn-1) 00000000 R14 R15 R0 R1 R2 R3 R4 R5 R6 R7 R8 R9 R10 R11 R12

00000000 A(SA3) A(SA5) R14 R15 R0 R1 R2 R3 R4 R5 R6 R7 R8 R9 R10 R11 R12



x'80' A(SAP) 80000000 A(SA2) R14 R15 R0 R1 R2 R3 R4 R5 R6 R7 R8 R9 R10 R11 R12

//

//

//

//

FLAG1 A(SA1) A(WAIT)

-- IMS SAVE AREA SET --

X'00' X'10' X'14'

SAP

SA1

SA2

SA3

SA4

SAn

WD1 X'00'

HSA X'04'

LSA

X'08'

WD1 X'00'

HSA

X'04'

LSA

X'08'

EP=DFSIWAIT

Last SA

1st SA

31

NOTESNOTES

Each save area set has a SAP used by the dispatcher and other services to control

execution of the ITASK. The SAP contains pointers to its associated save area set as follows:

SAP X'10' Pointer to the first save area in the set.

SAP X'14' Pointer to the WAIT save area if the ITASK is in an

IWAIT / ISERWAIT as determined by the SAPFLAG1 field at

offset X'00' having the X'40' bit set on. This field is otherwise residual.

Note: This save set will contain the registers that were stored when the ITASK

IWAITED / ISERWAITed. The registers from that save area will be reloaded and control will be returned at the R14 address "return point" when the IWAIT ECB is posted and the ITASK is re-dispatched.

Each save area set contains pointers to the prior (HSA) and next (LSA) save area in

the save area set.

The first save area of the save area set will have the following attributes:

WD1 High order bit set on. Remaining bit setting will be the address of the SAP.

HSA will contain X'80000000' to indicate no higher save area in this set.

The last save area of the save area set will have the following unique attributes:

LSA Will contain X'00000000' to indicate no lower save area in this save area set.

32

NOTESNOTES

IMS save area sets are pre-formatted with backward and forward chain pointers (i.e. HSA, LSA fields, respectively). Most pre-formatted save sets consist of 20 save areas. Each save area in the save area set is X'48' bytes in length.

The save area sets are used to save the calling module's registers. The registers are stored in the following order beginning at offset X'0C' in the save area: Reg14, Reg15, Reg0 through Reg12.

Reg13 is not saved and is actually the address of the save area itself.

Reg14 contains the return address back to the calling module. When a return to a caller has been performed, the save area becomes residual; that is, it has already been used to restore the actual CPU registers. A returned / residual save area is marked with low order bit of Reg14 set to one (At least one non-IBM software product still indicates residual save area with x'FFnnnnnn' in the high order byte of

the RET area).

33

SAVE AREA SET STRUCTURESSAVE AREA SET STRUCTURES

WD1

X'00'

LSA X'08'

SAVE AREA 1 SAVE AREAS 2, 3, 4...

X'48'

ADDRESS OF SAP. HIGH BIT X'80'X'80000000' TO INDICATE FIRST SAVE AREA IN SAVE SET

CONTENTS OF REG14. RESIDUAL IF ODD OR X'FFnnnnnn'CONTENTS OF REG15. MODULE OR CSECT EPA

HSA

X'04'

RET X'0C'

EPA X'10'

R0 X'14'

R1 X'18'

R2 X'1C'

R3 X'20'

R4 X'24'

R5 X'28'

R7 X'30'

R6 X'2C'

R8 X'34'

R9 X'38'

R10 X'3C'

R11 X'40'

R12 X'44' R12 Usually Caller Base

REG11 Usually SCD

REG10 at Entry to EPA




REG06 Sometime base







REG15 at Entry- Module/Csect EPA

REG14 at Entry to EPA Ret addr. Residual if oddor x'FFnnnnnn'

ADDRESS OF SAVE AREA to be used next( NEXT LOWER SA)

Caller's Save Area(Prior Save Area)

Should contain 0's if not the first Save Area in the Set - Not always true...

WD1

X'00'

HSA X'04'

LSA

X'08'

RET

X'0C'

EPA X'10'

R0 X'14'

R1 X'18'

R2 X'1C'

R3 X'20'

R4 X'24'

R5 X'28'

R6 X'2C'

R7 X'30'

R8 X'34'

R9 X'38'

R10 X'3C'

R11 X'40'

R12 X'44'

X'48'














ADDRESS OF SAVEAREA to be used next (NEXT LOWER SA)

34

NOTESNOTES

The Reg15 area contains the address to the entry point of the module / CSECT that has been invoked.

The Reg6 area sometimes contains the base address of the calling routine (prior save area). Most IMS modules use Reg12 as the base.

The Reg11 area often is used as the base to the SCD (Systems Contents Directory) in many IMS modules.

The Reg12 area usually contains the base address of the calling routine.

Save areas from save area pools are sometimes used to temporarily expand an existing save set (i.e. add additional save areas for increased module chaining capability).

Occasionally, save areas are used as work areas to contain data other than the standard registers. The EPA (Reg15 area) will not contain a pointer to a valid module / CSECT in those cases.

35

Technology

Where does IMS fit into the z/OS world