close

Вход

Забыли?

вход по аккаунту

?

Assembler Language How To Guide: Linkage Conventions - EGS

код для вставки
EGS Innovations, Inc.
How To Guide
Assembler Language
Linkage Conventions
EGS Innovations, Inc.
207 Meadow Wood Drive
Joliet, Illinois 60431-4809
Phone:
Fax:
(815) 744-2401
(815) 744-2401
Support@EGSInnovations.com
http://www.EGSInnovations.com
Assembler Language How To Guide: Linkage Conventions
Overview
The operating system control program provides services that your programs need while
assuring that the system resources are being efficiently. Well designed programs use system
resources efficiently. Knowing how the operating system control program works, its
expectations, and how to interact with it will help you design more efficient programs.
This guide describes the linkage conventions that a program should use when it calls another
program.
Linkage Conventions
Linkage conventions are the register and save area usage rules a program must follow when it
calls a program or is called by another program. All programs must follow the linkage
conventions described in this guide to ensure that programs can pass control back and forth
successfully. Without linkage conventions there would be chaos.
When a program executes it may need the services provided by another program. The program
that invokes another program is known as the calling program, and the invoked program is
known as the called program. For example, when the operating system control program passes
control to program PGMA, program PGMA is the called program. If program PGMA calls
program PGMB, program PGMA becomes a calling program, and program PGMB is a called
program. The operating system control program still considers program PGMA a called
program.
The linkage conventions presented in this guide assume one calling and one called program.
These conventions apply to all called and calling programs executing in the system. If the
linkage conventions outlined in this guide are followed by all programs, execution of called
programs will not be affected by the method used to invoke the programs or the identity of the
calling program.
Linkage Registers
Registers 0, 1, 13, 14, and 15 are known as linkage registers. These registers are used in fixed
ways by the operating system control program. Your programs should be using these registers
in the same way that the operating system control program does. The linkages registers may be
modified by the control program or by system macros used in your programs. Registers 2 – 12
are not changed by the control program.
Register 0 and 1 are used to pass parameters to a program. The expansion of some system
macros result in instructions that load a value into registers 0 or 1 or both. In general register 1
is used to pass parameters to a program you call.
EGS Innovations, Inc.
www.EGSInnovations.com
Page 1
Assembler Language How To Guide: Linkage Conventions
Register 13 contains the address of the save area provided by the calling program.
Register 14 contains the return address of the calling program or an address within the
operating system control program to which your program will return control when it completes.
Register 15 contains the entry address when control is passed to a program. When your
program passes control to another routine or program the entry address of the called routine
should be in register 15. Some system macros use register 15 to pass a parameter list. These
exceptions are documented in system macro usage guide. Register 15 is used by the called
program to pass a value (return code) to the calling program.
Parameter list format
When a program is invoked using the JCL EXEC statement is a good example of how a
parameter list is used to pass information. When control is passed to your program, register 1
contains the address of a fullword (4 bytes aligned on a fullword boundary) in a storage area
your program can access. The high-order bit (bit 0) of this fullword is set to 1. Setting the highorder bit to 1 indicates that the fullword is the last fullword in a variable size parameter list.
This is the convention used by the operating system control program. Bits 1-31 of the fullword
contain the address of the parameter data. The parameter data passed by the JCL EXEC
statement is the data contained in the JCL EXEC PARM parameter. The format of the parameter
data is a two byte (halfword) PARM data byte count followed by the PARM data value. If no
PARM data is passed then the 2 byte count is zeros (x’0000’).
The JCL EXEC statement parameter list access and format is listed below:
JCL Statement:
STEP01
EXEC PGM=MYPGMA,PARM='JEFF'
On entry to MYPGMA:
Register 1 => A(parameter_data + X’80000000’)
Parameter data area provided by control program:
PARM
DS
DS
EGS Innovations, Inc.
H'4'
CL4'JEFF'
www.EGSInnovations.com
Page 2
Assembler Language How To Guide: Linkage Conventions
The format of a multi-parameter list follows:
Calling program CALL Statement:
CALL
MYPGMA,(PARM1,PARM2),VL
On entry to MYPGMA:
Register 1 => A(PARM1)
A(PARM2 + x'80000000')
Saving the Calling Program’s Registers
When a program receives control the action it should do is save the contents of the calling
programs registers. Saving the content of all of the calling programs registers is easy to do.
Some high-performance programs and system services do not save the callers registers or only
save a subset of the callers registers. For general purpose application programs saving all
registers helps avoid errors in the calling program.
The registers are saved in a 18-word (72 byte) save area provided by the calling program and
pointed to on entry by register 13. The format of the save area is:
Word
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Contents
Used by PL/I language program
Address of previous save area. Set (stored) by calling program.
Address of next save area. Set (stored) by called (current) program.
Register 14 – Return address
Register 15 – Entry address
Register 0
Register 1
Register 2
Register 3
Register 4
Register 5
Register 6
Register 7
Register 8
Register 9
Register 10
Register 11
Register 12
As indicated in the table above, the contents of each register are saved in a specific location
within the save area. Registers can be saved using either the store-multiple (STM) instruction or
with the SAVE macro. The store-multiple instruction, STM 14,12,12(13), places the contents of
EGS Innovations, Inc.
www.EGSInnovations.com
Page 3
Assembler Language How To Guide: Linkage Conventions
all registers except register 13 in the proper locations (words) of the save area. Saving register
13 is detailed in the “Using the Save Area” section of this document.
The SAVE macro generates instructions that store a designated group of registers in a save area.
The registers to be saved are coded in the sane order as in the STM instruction. The following
SAVE example will save all registers:
SAVE
(14,12)
The following SAVE example will save registers 3 – 7 and the “T” parameter specifies that the
contents of registers 14 and 15 are to be saved:
SAVE
(3,7),T
The SAVE macro or equivalent instructions are placed at the program entry point or at a
location in the program prior to the modification of any registers.
Program Base Registers
In MVS and z/OS, addresses are resolved by adding a displacement to a base address. You must
establish the base register using one of the registers from 2-12 or register 15. Because register
15 is modified by system service calls and application program calls the use of register 15 as a
base register should be avoided.
Displacements in assembler instructions can have values of 0 (zero) through 4096. If your
program size is less than 4096 bytes you only need 1 base register. If your program size is
greater than 4096 bytes you will need a base register for each 4096 byte section. There are
many methods that can be used to manage base registers. In this guide only simple standard
base register setup is illustrated.
Base registers should be chosen carefully. You don’t want to choose a register that is modified
during program execution. You should avoid using registers 0, 1, 2, 13, 14, and 15 as base
registers. Base registers are generally setup immediately following the callers register save. The
following sample is an example of how a base register is established in a program:
MYPGMA
CSECT
STM
14,12,12(13)
LR
12,15
USING MYPGMA,12
EGS Innovations, Inc.
Start of MYPGMA
Save callers registers
Set register 12 as base
Map fields in MYPGMA
www.EGSInnovations.com
Page 4
Assembler Language How To Guide: Linkage Conventions
Using the Save Area
If your program passes control to another program your program must provide its own save
area. You must provide a save area when passing control to some system services. It is possible
to avoid using save areas. Not using a save area is not a good programming practice.
When using a save area you must save the address of the calling programs save area. You will
need the calling programs save area address to restore the calling program registers before
control is returned. To chain the calling program save area to the called program save area the
called program uses the following procedure:
•
Store the address of the calling program save area (the address passed on entry in
register 13) in the second word of the called program save area.
•
Store the address of the called program save area in the third word of calling program
save area.
This save area chaining method enables you to find the save area when you need to restore
registers. You can use the save area chaining pointers to trace save areas if required when
interpreting a dump.
Save area chaining examples
Two methods of obtaining save areas and of saving the registers, including save area chaining,
are shown below.
Nonreentrant program save area example
In this example (example 1) the calling program registers are saved in a save area encoded in
the called program (via DC statement).
MYPGMA
CSECT
STM
LR
USING
ST
LR
LA
ST
.
.
.
SAVEAREA DC
14,12,12(13)
12,15
MYPGMA,R12
13,SAVEAREA+4
2,13
13,SAVEAREA
13,8(2)
Program start
Save registers via STM
Reg 12 -> MYPGMA
Map fields in MYPGMA
Chain caller save area to new
Save caller save area address
Reg 13 -> new save area
Chain new save area to old
18F'0'
New save area
EGS Innovations, Inc.
www.EGSInnovations.com
Page 5
Assembler Language How To Guide: Linkage Conventions
Reentrant program save area example
In this example the calling program registers are saved (using SAVE macro) in a save area
located in a block of virtual storage. This example applies to reentrant and reusable programs.
MYPGMA
CSECT
SAVE (14,12)
LR
12,15
USING MYPGMA,R12
GETMAIN R,LV=WSA_SIZE
ST
13,4(1)
ST
1,8(13)
LR
13,1
.
.
.
Program start
Save registers via SAVE macro
Reg 12 -> MYPGMA
Map fields in MYPGMA
Get working storage area
Chain caller save area to new
Chain new save area to caller
Reg 13 -> new save area
*
*--------------------------------------------------------------* Working Storage Area (WSA) block map
*--------------------------------------------------------------WSA
DSECT
New save area
WSA_START DS OF
Start of WSA block
SAVEAREA DS 18F
Save area
WSA_END
DS 0D
End of WSA block
WSA_SIZE EQU *-WSA_START
WSA block size
There is no reason to write nonreusable code, as illustrated in example 1. Writing reentrant
programs requires a little bit more effort, but has measurable benefits. Reentrant programs
benefit from reduced program load overhead and module serialization delays. Reentrant
modules tend to be smaller in size. A program to be executed in a batch job step benefits from
being reentrant. When a module is reentrant it is much easier to use the module as callable
subprogram that can be invoked in any environment.
Summary of conventions to be followed when passing and
receiving control
The following is a list of conventions to be followed when passing and receiving control.
Conventions used by a program before passing control to another program that will return
control to the calling program:
•
Place the address of calling save area in register 13.
EGS Innovations, Inc.
www.EGSInnovations.com
Page 6
Assembler Language How To Guide: Linkage Conventions
•
•
•
Place the point of return address in register 14.
Place the entry address of the program being called in register 15.
Place the address of the parameter list in register 1 and register 0 (if multiple lists).
Conventions used by a program before passing control to another program that will NOT return
control to the calling program:
•
•
•
•
Restore registers 2 – 12 and 14. Register values should be the values passed by the
program that called this program.
Place the address of the save area provided by the program that called this program in
register 13.
Place the entry address of the program being called in register 15.
Place the address of the parameter list in register 1 and register 0 (if multiple lists).
Conventions used by a called program after receiving control:
•
•
•
•
Save the contents of registers 0 – 12, 14 and 15 in the save area provided by the calling
program.
Set a base register.
Allocate storage for a save area if the save area is not included in the program using a
DC statement.
Chain the save areas together.
Conventions used by a called program before returning control:
•
•
•
Restore registers 0 – 12 and 14.
Unchain current save area from calling program save area. Address of calling program
save area is placed in register 13.
Place a return code in register 15. Register 15 can be restored to its original value if a
return code is not being returned.
EGS Innovations, Inc.
www.EGSInnovations.com
Page 7
Assembler Language How To Guide: Linkage Conventions
About the author
Jeffrey Celander has had over 30 years experience as a software developer and almost an
equal time working in Business. He is the principal of EGS Innovations, Inc. EGS Innovations is a
software development consulting and training organization based in Joliet Illinois USA.
About EGS Innovations, Inc.
Founded in 2009, EGS Innovations is a privately owned company. We specialize in the creation
and deployment of Mainframe business applications software and commercial product
software using new or existing technologies. We provide training in a variety of Mainframe
disciplines. All EGS Innovations services are available at very affordable rates. Visit our website
and see what we have to offer http://www.EGSInnovations.com.
Software Agreement and Disclaimer
Permission to use, copy, modify and distribute this software, documentation or training
material is granted for personal use. Any other use requires written permission from the
publisher EGS Innovations, Inc. The EGS Innovations name or Logo may not be used in any
advertising or publicity pertaining to the use of the software without the written permission of
EGS Innovations, Inc.
EGS Innovations, Inc. makes no warranty or representations about the suitability of the
software, documentation or learning material for any purpose. It is provided "AS IS" without
any express or implied warranty, including the implied warranties of merchantability, fitness for
a particular purpose and non-infringement. EGS Innovations, Inc. shall not be liable for any
direct, indirect, special or consequential damages resulting from the loss of use, data or
projects, whether in an action of contract or tort, arising out of or in connection with the use or
performance of this software, documentation or training material.
If you have any questions, suggestions or comments please call or send an e-mail to:
Services@EGSInnovations.com
EGS Innovations, Inc.
www.EGSInnovations.com
Page 8
Assembler Language How To Guide: Linkage Conventions
Assembler Language How To Guide: Linkage Conventions
Second Edition (April 2010)
Reader comments on this document are welcomed and encouraged. Comments may be sent to:
EGS Innovations, Inc.
Technical Publications Group
207 Meadow Wood Drive
Joliet, Illinois 60431-4809
В© Copyright EGS Innovations, Inc. 2010. All rights reserved.
Printed in the United States of America. This publication may be reproduced for personal use or for use as an educational aid. Any
other use requires the prior written permission of the publisher, EGS Innovations, Inc
Trademarks
IBM, MVS, OS/390 and z/OS are trademarks of IBM Corporation.
EGS Innovations, Inc.
www.EGSInnovations.com
Page 9
Документ
Категория
Без категории
Просмотров
11
Размер файла
174 Кб
Теги
1/--страниц
Пожаловаться на содержимое документа