PC Routines for Dummies

R.P. Shannon
Programart Corporation
124 Mt. Auburn Street
Cambridge, MA 02138
(617)498-2948
shannon@programart.com

MVS Expo 98
Session I05
October 26-30, 1998
Atlanta, GA
1

PC Routines for Dummies

Trademarks
IBM
MVS/ESA
OS/390
RACF
S/390
System/390
IBM

PC Routines for Dummies

Invoking Other Routines

Call :
Attach:

Called module inherits state and key of caller

New Task inherits state and key of the mother
task
Synch:
New task is assigned a state and key by
attaching program
XCTL:
Module inherits state and key from
transferring module
SVC:
Executes in supervisor state key zero
PC Routines: Assigned state and key by creating routine

PC Routines for Dummies

PC Types
Stacking PC: Uses the Linkage Stack
Basic PC: Does not use the linkage stack
Non-Space Switching PC:
l
l
l

Executes in invokers address space:

Routine may reside in private area
Home = Primary = Secondary

Space Switching PC:

l
l
l

Executes in another address space:

Routine may reside in private area of target address space
Primary not equal to Secondary

Non-Space Switching Global:

l
l
l
l
l

My terminology not IBMs

Most IBM service routines are this type
Called by multiple address spaces
Routines reside in Common
Home = Primary = Secondary
4

PC Routines for Dummies

Linkage Stack
A system-managed savearea
Populated by Stacking PCs and by BAKR instruction
PR to restore environment from stack and return to caller
Separate stack for each dispatchable unit
l 96 entries (default)
l

LSEXPAND macro to increase number of stack entries

Contains:
l
l
l

Content of GPRs 0 -15 (64 bytes)

Content of ARs 0 -15 (64 bytes)
Environmental Data
u PSW
u PSW key Mask from CR1
u Extended Authorization Index from CR8
u Primary and Secondary ASNs

PC Routines for Dummies

Linkage Stack

CR 15
STCBLSDP

General Purpose Registers

General Purpose Registers
General Purpose Registers
General Purpose Registers
General Purpose Registers
AccessRregisters
General Purpose Registers
AccessRregisters
General Purpose Registers
AccessRregisters
AccessRregisters
AccessRregisters
AccessRregisters
Environmental Data
AccessRregisters
Environmental Data
Environmental Data
Environmental Data
Environmental Data
Environmental Data
Environmental Data

PC Routines for Dummies

Linkage Stack Manipulation

BAKR: Branch and Stack Registers
l
l

Can be used in lieu of BALR, BASR

Creates a new Linkage Stack Entry

PR: Program Return

l
l
l

Restores registers 2-14

Returns to address following the BAKR that populated the Linkage
Stack

EREG: Extract Stacked Registers

l
l
l
l

Loads a set of registers and access registers from the

Linkage Stack
Allows easy retrieval of callers registers
Allows callers registers 0-1,15 to be restored (if needed)
before return to caller

PC Routines for Dummies

Linkage Stack Manipulation

MSTA: Modify Stacked State
l
l
l
l

Store even/odd register pair at bits 152-159 in Linkage Stack

Non-privileged instruction
Free 8 byte workarea
Be careful nothing else has used it

ESTA: Extract Stack State

l
l
l

Extract information from the Linkage Stack

Loads 8 bytes of data into even/odd register pair
Function depends upon value in odd register
u 1 - bits 128-135: PKM | SASN | EAX | PASN
u 2 - bits 136-143: PSW
u 3 - bits 144-151: branch address or pc number
u 4 - bits 152-159: modifiable area

PC Routines for Dummies

Jaberwocky - The Entry Table

Twas brillig, and the slithy toves
Did gyre and gimble in the wabe - Lewis Carrol
Terminology for defining PC Routines is very confusing
Translation:
l
l
l

Entry Table:
An array of PC Routine definitions
Entry Table Entry:
Individual PC Routine definition
Entry Table Descriptor: Describes the array of PC Routines

PC Routines for Dummies

Understanding the Program Status Word (PSW)

I E
0 R 0 0 0 T O X
0

Key
8

1 M W P A S C C
12

16

18

Prog
Mask

20

0 0 0 0 0 0 0 0
24

31

Instruction Address
63

Fields that pertain to PC Routines:

l
l
l
l
l

PSW Key (8-11)

Problem State Bit (15)
Address Space Control (16-17)
Addressing Mode (32)
Instruction Address (33-63)

10

PC Routines for Dummies

ETDEF - Type = Entry

ETDEF macro is used to define Entry Tables, Entry Table
Entries, and the Entry Table Descriptor
Key Parameters for Entry Table Entries:
l
l
l
l
l
l

ARR:
ASCMODE:
EK:
PARM1/2:
Routine
STATE:

Address of name of Associated Recovery Routine

PRIMARY or AR mode
Entry Key - he key the routine will execute in; (default
is callers key)
Addresses passed to PC Routine
Address of PC Routine
PROBLEM | SUPERVISOR

Do any of these remind you of a PSW?

Note: There are many more ETDEF parameters

11

PC Routines for Dummies

Passing Latent Parmameters

Parm1
ETDEF

ETE

Parm2

At entry to PC Routine:
R4

Parm1
Parm2

Parameter values are static; set when ETE is defined

12

PC Routines for Dummies

Linkage Index (LX)

Used to locate an entry in the Linkage Table
2048 Linkage Indexes available (5.1 - OW22516):
l

NSYSLX = 10-512 (default 165)

l Number Non-Nystem LXs = (2048 - # System LXs)

Linkage Tables reside in LSQA in the PCAUTH address

space:
l
l

1 Linkage Table for System LXs

Each address space has a Linkage Table for Non-System LXs
u ASCBLTOV contains LT address (in PCAUTH)
u LT entries modified by ETCON/ETDIS
u Freed at A/S termination

A Linkage Table must be connected to an Entry Table in

order to call a PC Routine:
l
l
l

System LXs are automatically connected

Must connect/disconnect Non-System LXs by issuing
ETCON/ETDIS
ETCON/ETDIS require supervisor state or PKM 0-7

13

PC Routines for Dummies

Linkage Table Entries

ET Real Addr
Flag
ET Real Addr
Flag
ET Real Addr
Flag
ET Real Addr
Flag
ET Real Addr
Flag
ET Real Addr
Flag
ET Real Addr
Flag
ET Real Addr
Flag
ET Real Addr
Flag
ET Real Addr
Flag

ET
ET
LENET
LENET
LENET
LENET
LENET
LENET
LENET
LENET
LEN
LEN

14

PC Routines for Dummies

PCAUTH Address Space - Home of Linkage Tables

System Linkage Table

Address Space
Linkage Tables

Entry Tables

PCAUTH Address Space

15

PC Routines for Dummies

IBM Reserved LXs

X00
X01
X02
X03
X04
X05
X06
X07
X08
X09
X0A
X0B
X0C
X0D
X0E
X0F
X10
X13
X14

AASF
GRS
Display allocations table manager
Miscellaneous MVS Services
WTO services
System trace services
Virtual fetch
SMF buffering
LLA
Data space PC services
VLF
Reserved
Reserved for DFP
Reserved
LLA Copy
SDOM Services
MVS Message Services
OE Services
WLM

16

PC Routines for Dummies

Address Space Related Fields

ASCBASTE:
ASCBLTOV:
ASCBATOV
ASCBETC:
ASCBETCN:
ASCBLXR:
ASCBAXR:

virtual address of a/s second table entry (aste)

virtual address of linkage table origin (in pcauth a/s
virtual address of authorization table (in pcauth a/s)
# entry tables owned by this a/s
# connections to entry tables in this a/s containing any space
switch entries
# LXs reserved by this a/s
# authorization indexes reserved by this a/s

17

PC Routines for Dummies

Associated Recovery Routine (ARR)

A recovery routine for PCs
l

Defined when PC routine is defined:

u ARR parameter on ETDEF
u Similar to ESTAEX
u TERM=YES is the default
l SDWAPARM field will contain contents of modifiable stack area
l Can be a common routine that serves multiple PC Routines
l Can do as little as return control to the PC Routine iso an
appropriate return code can be set
l SDWA is always in the PRIMARY address space
l Diagnostic information would be quite helpful

We strongly recommend an ARR be defined for every PC

Routine:
18

PC Routines for Dummies

PCSAMP
Sample program to illustrate the functions required to use
PC Routines:
l
l
l
l
l
l
l

Enter supervisor state via MODESET macro

Reserve non-system LX
Define Entry Table
Define Entry Table Entries
Connect LX to ET
Back to problem state via MODESET macro
Two PC Routines defined within the same module for simplicity
u Invoke the first PC Routine (TPROT)
u Invoke second PC Routine (FRELX) to disconnect from and free
LX

PCSAMP is a teaching aid - it is not intended for the real

world!

19

PC Routines for Dummies

Sample PC Routine - Reserve LX and Define Entry Table

MODESET MODE=SUP

into supervisor state

*
*
*

+---------------------------------------------+
+ Reserve a non-system linkage index
+
+---------------------------------------------+
MVC
#_LX_ENTRIES,=F1
request a single lx
LXRES LXLIST=LX_PARMLIST,SYSTEM=NO,MF=(E,LXRES_LF)
LTR
R15,R15
work ok?
BNZ
ERRRTN_LXRES
bif no

*
*
*

+---------------------------------------------+
+ Define an Entry Table
+
+---------------------------------------------+
MVC
ETDEF
LTR
BNZ

ENTRY_TABLE(ETD_PARMLEN),ETDBASE copy base to workarea

TYPE=SET,HEADER=ETD_HEADER,NUMETE=2
R15,R15
work ok?
ERRRTN_ETD
bif no

20

PC Routines for Dummies

10

Sample PC Routine - Define Entry Table Entries

*
*
*

+---------------------------------------------+
+ Define the Entry Table Entries
+
+---------------------------------------------+
L
R2,TPRT_ADDR
get addr of tprot routine
ETDEF TYPE=SET,ETEADR=ETD_TPROT,ROUTINE=(2),
PC=STACKING,ASCMODE=PRIMARY,SSWITCH=NO,SASN=OLD,
STATE=SUPERVISOR,RAMODE=31,AKM=(0:15),EK=(0)
LTR
R15,R15
work ok?
BNZ
ERRRTN_ETD
bif no
L
R2,FRLX_ADDR
get addr of freelx routine
ETDEF TYPE=SET,ETEADR=ETD_FRLX,ROUTINE=(2),
PC=STACKING,ASCMODE=PRIMARY,SSWITCH=NO,SASN=OLD,
STATE=SUPERVISOR,RAMODE=31,AKM=(0:15)
LTR
R15,R15
work ok?
BNZ
ERRRTN_ETD
bif

*
*
*

X
X

X
X

+---------------------------------------------+
+ Build Entry Table Discriptor
+
+---------------------------------------------+
ETCRE ENTRIES=ENTRY_TABLE
define entry table
LTR
R15,R15
work ok?
BNZ
ERRRTN_ETCRE
bif no
ST
R0,ET_TOKEN
else save the token

21

PC Routines for Dummies

Sample PC Routine - Connect LX to Entry Table

*
+---------------------------------------------+
*
+ Connect LX to Entry Table
+
*
+---------------------------------------------+
CONNECT_TO_ENTRY_TABLE DS 0H
MVC
#_ET_TOKENS,=F1
1 entry table; 1 token
ETCON LXLIST=LX_PARMLIST,
TKLIST=ET_TOKEN_LIST,
MF=(E,ETCON_LF)
LTR
R15,R15
work ok?
BNZ
ERRRTN_ETCON
bif no

x
x

22

PC Routines for Dummies

11

Sample PC Routine - Call PC Routines

MODESET MODE=PROB
LR
L
PC

R1,R2
R14,LX_NUMBER
TPROT_PC(14)

assume storge addr in reg 1

lox no no into reg 14
invoke tprot pc routine

C
BH
CLEANUP

back to problem state

R15,=F4
NO_REFERENCE

can we reference storage?

bif no

FRLX_PC(14)

invoke free lx pc routine

DS
PC

0H

23

PC Routines for Dummies

Sample PC Routine - TPROT PC Routine

TPROTRTN DS 0D
BASR
USING
IPK
TPROT
BC
BC
BC
BC
TPROT_0

DS
LA
B
TPROT_4 DS
LA
B
TPROT_8 DS
LA
B
TPROT_16 DS
LA
B

R11,0
*,R11
R2
0(R3),0(R2)

set r11 to where we are

establish reh 11 as base
get psw key (R2)
test access

8,TPROT_0
4,TPROT_4
2,TPROT_8
1,TPROT_16

fetch & store ok

fetch only
neither fetch nor store
translation not available

0H
R15,0
TPROTXIT
0H
R15,0
TPROTXIT
0H
R15,0
TPROTXIT
0H
R15,0
TPROTXIT

TPROTXIT DS
0H
EREG R1,R1
PR

set rc to zero
out out
set rc to zero
out out
set rc to zero
out out
set rc to zero
out out

restore callers R1
boogie

24

PC Routines for Dummies

12

Sample PC Routine - PC Routine to Free LX

FREELX
*
*
*
*
*

DS 0D
FREELX
inline pc routine
+----------------------------------------------+
+ PC Routine to Free Linkage Index
+
+ R13 ---> workarea
+
+----------------------------------------------+
BASR R11,0
determine where we are
USING *,R11
establish base register
LR
R10,R13
copy workarea addr into reg 10
USING WORKAREA,R10
map workarea
ETDIS TKLIST=ET_TOKEN_LIST

disconnect the entry table

XC
LXFRE_LF(LXFRE_LEN),LXFRE_LF
clear workarea
LXFRE LXLIST=LX_PARMLIST,MF=(E,LXFRE_LF) free lx
XC

LX_NUMBER,LX_NUMBER

clear lx number

EREG
PR

R1,R1

restore callers reg 1

boogie

25

PC Routines for Dummies

Sample PC Routine - Data Constants

*
*
*
*
ETDBASE

Title Base Entry Table Entries

+---------------------------------------------+
+ Skeleton ETD Entries. These entries are
+
+ copied to a workarea and modified
+
+---------------------------------------------+
ETDEF TYPE=INITIAL
ETDEF TYPE=ENTRY,ROUTINE=0,AKM=(0:15)
TPROT
ETDEF TYPE=ENTRY,ROUTINE=0,AKM=(0:15)
FREE LX
ETDEF TYPE=FINAL

TPRT_ADDR DC AL4(TPROTRTN)
FRLX_ADDR DC AL4(FREELX)

addr of tptot pc rtn

addr of freelx pc rtn

26

PC Routines for Dummies

13

Sample PC Routine - Workarea

WORKAREA
TPROT_PC
FRLX_PC
SAVEAREA

DSECT
EQU
EQU
DS

0
1
18F

pc routine 0
pc routine 1
savearea

ENTRY_TABLE
ETD_HEADER
ETD_TPROT
ETD_FRLX
ETD_PARMLEN

DS
DS
DS
DS
EQU

0D
XL(ETDLEN)
XL(ETDELEN)
XL(ETDELEN)
*-ENTRY_TABLE

entry table
header
1st entry
2nd entry
length

LX_PARMLIST
#_LX_ENTRIES
LX_NUMBER

DS
DS
DS

0F
F
F

lx parmlist
# of lxs
lx number (returned)

ET_TOKEN_LIST DS
#_ET_TOKENS
DS
ET_TOKEN
DS

0F
F
F

entry table parmlist

# et tokens
the et token

LXRES_LF
LXFRE_LF
LXFRE_LEN
ETCON_LF

LXRES
LXRES
EQU
ETCON

MF=L
MF=L
*-LXFRE_LF
MF=L

listform of lxres macro

listform of lxres macro
lxfre length
listform of etcon macro

WALEN

EQU *-WORKAREA
IHAETD FORMAT=1

27

PC Routines for Dummies

Passing the LX Number

CVTUSER:
l
l

1 per system
Unreliable - Do Not Use!

SSCT:
l
l

Two user fields, SSCTSUSE and SSCTSUS1

Fine if youre a subsystem

Customer Anchor Table:

l

Anchor words assigned to vendors by IBM

Pointed to by ECVTCTBL
l Good choice for vendors
l

Name Token Services:

l
l
l

Probably the best choice for customers

Create a persistent Name/Token pair
Callers must know the name

28

PC Routines for Dummies

14

Connecting to an Entry Table

ETCON requires supervisor state
Catch 22: How can a problem state caller get authorized to
connect to an Entry Table to be able to call authorized PC
Routines?
Answer: use a PC Routine!
Create a PC Routine connected to a System Linkage Index:
l Check callers authority for:
u Supervisor state caller
u Or PKM 0-7
u Or PSW Key 0-7
u Or update authority to user-defined resource in
RACF Facility Class
l Issue ETCON if caller is authorized
l Define another PC Routine to issue ETDIS
29

PC Routines for Dummies

Considerations for PC Routines

Always run with the minimum authority required
Dont branch outside outside of routine:
l
l

OK to invoke other PC Routines

Probably OK to call other IBM code

Upon entry:
l
l

Register 15 does not contain EPA (code a BASR)

Register 4 points to latent parms (if specified)

If possible check authority during connect, not in each PC

Routine
Rather than using STORAGE OBTAIN, require caller to
pass a workarea (if needed)
l

Use TPROT to test access

Insure storage is in a protected key if integrity is a concern
l Tip: first word of storage should contain length
l Macros/SVCs require R13 to point to a savearea
l

30

PC Routines for Dummies

15

Considerations for PC Routines

The target of a space switching PC Routine must be swapped
in
Key Design Decision: System Linkage Index or non-System
Linkage Index
When an address space that owns a System LX terminates
the address space becomes unusable:
l

Reusing address space can cause an integrity exposure by allowing

space switch into the wrong address space
l Under certain conditions may become usable, but dont count on it
l Loss of many address spaces can force IPL
l Always test on a development or sysprog system

Cross memory Considerations:

l

Cross Memory service providers must reserve an Authorization

Index (AX) or Extended Authorization Index (EAX) to allow access
to address space
Generally the only SVC available is ABEND (SVC 13)
31

PC Routines for Dummies

Bibliography
OS/390 V2R6.0 MVS Auth Assm Services Reference
ENF-IXG, GC28-1765, IBM Corporation
OS/390 V2R6.0 MVS Auth Assm Services Reference
LLA-SDU, GC28-1766, IBM Corporation
OS/390 V2R6.0 MVS Extended Addressability Guide, GC28-1769, IBM
Corporation
A Detailed Look at ESA/370; Brian Moore; IBM Corporation
Concepts of Enterprise Systems Architecture/370; K.E. Plambeck; IBM
Systems Journal Volume 28, Number 1, 1988
Developing an MVS/ESA Cross Memory Application USing ESA/370
Advanced Address Space Facilities; Keefe Hayes; SAS Institute; SHARE
76, Session O320; 27 February, 1991
Enterprise Systems Architecture/390; Jeff Frye; IBM Corporation;
ESA/390 Principles of Operation, Doug Smucker, Amdahl Corporation,
Session O355, SHARE 77
MVS/ESA Linkage Stack Save Program Status, Edward Williams,
Candle Report Volume 13, Number 5, May 1991
Bit Bucket X0D, Bob Shannon and Carl Youngren, SHARE 88
32

PC Routines for Dummies

16