S P Ms Notes

GA L I LEO
IN T ERN AT I O N A L
TECHNICAL TRAINING DEPARTMENT
INTRODUCTION TO
STRUCTURED PROGRAMMING
MACROS (SPMs)
Structured Programming Macros Galileo Technical Training Department
Table of Contents
Introduction To SPM's
.................................................................................................. ...........
1
Some Basic Conventions
.................................................................................................. ...........
2
The #IF Macro
.................................................................................................. ...........
3
Instruction Set for the #IF Macro
..................................................................................................... .................
3
Rules for the #IF Macro
..................................................................................................... .................
3
The #IF MACRO - Basic Structures
..................................................................................................... .................
4
The Conditional Expression
.................................................................................................. ...........
8
Instructions that must have a Conditional Expression:
..................................................................................................... .................
8
Instructions that can have a Conditional Expression:
..................................................................................................... .................
8
Rules for the Conditional Expression:
..................................................................................................... .................
8
Valid Condition Code Mnemonics
..................................................................................................... .................
9
Examples Of Conditional Expressions
..................................................................................................... .................
10
Special Conditional Instructions
..................................................................................................... .................
13
Continuation and Boolean Connectors
.................................................................................................. ...........
16
Instruction Set for Boolean Connectors
..................................................................................................... .................
16
Rules for Boolean Connectors
..................................................................................................... .................
16
Rules for Continuation
..................................................................................................... .................
17
The #DO Macro
.................................................................................................. ...........
20
22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page i

Instruction Set for the #DO Macro

..................................................................................................... .................
20
Rules for the #DO Macro
..................................................................................................... .................
20
Simple Loop Control Mechanisms
..................................................................................................... .................
21
#DO WHILE=( )
..................................................................................................... .................
22
#DO UNTIL=( )
..................................................................................................... .................
22
#DO INF
..................................................................................................... .................
22
#DO TIMES=REG or #DO TIMES=(REG,n)
..................................................................................................... .................
23
#EDO
..................................................................................................... .................
23
#ELOP
..................................................................................................... .................
24
#DOEX
..................................................................................................... .................
25
#EXIF
..................................................................................................... .................
26
The #DO Macro - Basic Structures
..................................................................................................... .................
28
Combination of #DO Loops
..................................................................................................... .................
29
Complex Conditional Expressions with #DO Loops
..................................................................................................... .................
29
The #DO Macro - CODING GUIDELINES
..................................................................................................... .................
30
The #PERF Macro
.................................................................................................. ...........
33
Instruction Set for the #PERF Macro
..................................................................................................... .................
33
Rules for the #PERF Macro
..................................................................................................... .................
33
#SUBR
..................................................................................................... .................
34
#ESUB
22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page ii

..................................................................................................... .................
34
The #PERF Macro - Basic Structures
..................................................................................................... .................
35
The #PERF Macro - CODING GUIDELINES
..................................................................................................... .................
36
Subroutines....................................................................................... ........................36
The #GOTO Macro
.................................................................................................. ...........
37
Instruction Set for the #GOTO Macro
..................................................................................................... .................
37
Rules for the #GOTO Macro
..................................................................................................... .................
37
#LOCA label
..................................................................................................... .................
37
The #EXEC Macro
.................................................................................................. ...........
38
Instruction Set for the #EXEC Macro
..................................................................................................... .................
38
Rules for the #EXEC Macro
..................................................................................................... .................
38
The #UEXEC Macro
.................................................................................................. ...........
39
Instruction Set for the #UEXEC Macro
..................................................................................................... .................
39
Rules for the #UEXEC Macro
..................................................................................................... .................
39
The #CASE Macro
.................................................................................................. ...........
40
The 'CASE' Set
..................................................................................................... .................
40
Instruction Set for the #CASE Macro
..................................................................................................... .................
40
#CAST reg or #CAST reg,POWER=n or #CAST reg,POWER=n,MAX=M
..................................................................................................... .................
41
Rules for the #CASE Macro
..................................................................................................... .................
42
#CASE Nx or #CASE Nx,Ny or #CASE ERROR
..................................................................................................... .................
42
#ECAS
22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page iii
..................................................................................................... .................
42
The #CASE Macro - CODING GUIDELINES
..................................................................................................... .................
45
The Condensed Form
.................................................................................................. ...........
47
Rules for the Condensed Form
..................................................................................................... .................
47
The Condensed TEST UNDER MASK
..................................................................................................... .................
47
The Condensed "COMPARE" Command
..................................................................................................... .................
48
The Condensed Form - CODING GUIDELINES
..................................................................................................... .................
49
22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page iv

Introduction To SPM's
A large portion of TPF programming consists of modifying existing code. The way a program
is written effects how easy it is to understand and therefore, modify.
If code is split up into discrete routines it becomes easier to test and maintain. However, it is
often more convenient to 'straight line' code in Assembler.
There are three basic logical components to programming:
• Sequence
• Iteration
• Selection
SPM's (Structured Programming Macros) provide the control of Iteration (looping) and
Selection (branching). The use of SPM's forces the programmer to consider the logical
flow and structure of the program. This results in code where the routines are logically
separate from each other, and produces 'Structured' coding.
The users of SPM's have determined that the time required to write new code with SPM's is
about the same as to write it without. However, there is a considerable saving during
testing and later development as it is easier to find and modify the required code in a
structured program.
SPM's (Structured Programming Macros) originated from IBM. However, they have been
considerably enhanced by British Airways, KLM, and Swiss Air to ensure compatibility with
an ACP/TPF environment, and to provide special facilities for easier programming under
ACP/TPF.
The SPM's presented in this course are the enhanced version of the macros developed by
British Airways, KLM, and Swiss Air.
SPM's are now used by more than 30 ACP/TPF installations.
IBM has stated that all future TPF development work will be done with the aid of SPM's.
To an increasing extent, this is already true.
22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page 1

Some Basic Conventions
Labels are no longer necessary in front of instructions: i.e. LABEL EQU * is no longer
required. Therefore, to allow more space for comment statements,
start to code in Column 4.
SPM's allow up to 32 characters for its labels. It is no longer necessary to try to squeeze
a descriptive label (eg. for a routine or function) into 8 characters by eliminating all of the
vowels!
Coding inside SPM macros should be indented: the body of the coding (which is usually
normal BAL) should be indented by three columns. This makes the code much easier to
read.
Although the compiler can handle many nesting levels, it is recommended that no more
than 4 nesting levels be used in any given routine. Any more than that, and it becomes
confusing to the eye.
When practicable, insure that the #IF macro and its corresponding #EIF are on the same
page of the listing. One should be able to see the entire structure at a glance.
The same applies to a #DO and #EDO structure.

The #IF Macro
The #IF macro is used to handle the Selective element of logic based on conditional
expressions.
Instruction Set for the #IF Macro
#IF
#ELIF
#ELSE
#EIF
Rules for the #IF Macro
• Each #IF must have one (and only one) #EIF.
• Each #IF may have multiple #ELIF's.
• Each #IF and #ELIF must have have at least one Conditional Expression.
• Each #IF may have one (and only one) #ELSE.
• There are no parameters for the #ELSE and #EIF macros.

The #IF MACRO - Basic Structures
#IF
#IF true TRUE
...........
........... FALSE
........... PROCESS
#EIF
#EIF
FALSE
#IF true #IF #ELSE
...........
........... TRUE
...........
#ELSE PROCESS PROCESS
...........
...........
...........
#EIF #EIF
FALSE FALSE
#IF true #IF #ELIF
...........
...........
........... TRUE TRUE
#ELIF true
........... PROCESS PROCESS
...........
...........
#EIF
#EIF

The #IF Macro - Basic Structures
TRUE
#IF true #IF PROCESS
...........
...........
........... FALSE
...........
...........
TRUE
#ELIF true #ELIF PROCESS
...........
...........
........... FALSE
...........
........... TRUE
#ELIF true #ELIF PROCESS
...........
...........
........... FALSE
...........
...........
#ELSE #ELSE
...........
...........
...........
........... PROCESS
...........
#EIF
#EIF

TRUE
...........
...........
........... FALSE
...........
...........
TRUE TRUE
#ELIF true #ELIF #IF
#IF true
...........
........... FALSE
FALSE PROCESS
...........
...........
........... #ELSE
#ELSE
...........
...........
...........
........... PROCESS
...........
#EIF
#EIF #EIF
#EIF

TRUE
...........
...........
........... FALSE
...........
...........
TRUE
#ELSE #ELSE #IF
#IF true
...........
........... FALSE
PROCESS
...........
...........
........... #ELSE
#ELSE
...........
...........
...........
........... PROCESS
...........
#EIF
#EIF #EIF
#EIF

The Conditional Expression
The Conditional Expression enables a choice to be made between two or more different
processes to be executed based on a condition.
Instructions that must have a Conditional Expression:
#IF
#ELIF
#EXIF
#DOEX
Instructions that can have a Conditional Expression:
#DO
#GOTO
Rules for the Conditional Expression:
• The Conditional Expression can have two forms:
1) A Symbolic Representation of a standard BAL instruction which results in a

Condition Code Setting and/or branch.
2) A Symbolic Representation of certain ACP/TPF Macro calls (i.e. LEVTA &

WAITC)
• The entire Conditional Expression can be considered a set of parameters for the macro
with which it has been coded. All portions of the Conditional Expression are separated
by a comma.
• The Conditional Expression for the #IF macro can be coded within parenthesis, however
the parentheses are not necessary. In all examples of the #IF macro presented in this
course, the parentheses will not be used.

Valid Condition Code Mnemonics
COMPARE EQ, GE, GT, H, L, LE, LT, NE, NH, NL
ARITHMETIC M, NM, NO, NP, NZ, O, P, Z, NEGATIVE,

POSITIVE, ZERO, NOTNEGATIVE, NOTPOSITIVE
TEST UNDER MASK M, NM, NO, NZ, O, Z, ZERO, MIXED, NOTMIXED,

NONZERO, OFF, ON
PLEASE NOTE:
• In the COMPARE INSTRUCTION, the Conditional Code Mnemonic is placed

between the 1st and 2nd operand.
• In the ARITHMETIC and TM INSTRUCTIONS, the Condition Code Mnemonic is

placed after the 1st and 2nd operands.

Examples Of Conditional Expressions
COMPARE Instructions
Instruction Conditional Expression
CLC #IF CLC,FIELD_A(3),EQ,=C'ABC'

#IF CLC,FIELD_A,NE,FIELD_B
#IF CLC,FIELD_A,H,=F'100'
#IF CLC,FIELD_A,GE,FIELD_B
CLI #IF CLI,FIELD_A,GT,4

#IF CLI,FIELD_A,LE,5
#IF CLI,FIELD_A,NE,#CAR
#IF CLI,FIELD_A,EQ,C'X'
CLCL #IF CLCL,R2,NE,R4
CLM #IF CLM,R1,B'1100',NE,FIELD_B

#IF CLM,R2,B'0100',EQ,=X'70'
C #IF C,R4,EQ,=F'5000'
#IF C,R5,NE,FIELD_B
CR #IF CR,R2,EQ,R3
#IF CR,R5,GT,R6
CH #IF CH,R3,LE,=H'10'
#IF CH,R1,EQ,FIELD_B

Examples Of Conditional Expressions (continued)
ARITHMETIC Instructions
AR #IF AR,R2,R3,ZERO
LTR #IF LTR,R1,R1,NOTNEGATIVE

#IF LTR,R2,R3,POSITIVE
#IF LTR,R3,R3,ZERO
OC #IF OC,FIELD_A,FIELD_A,NONZERO
PLEASE NOTE: BAL Instructions not listed above which can also be used: O, OI, OR,
NC, N, NI, NR, XC, X, XI, A, AP, AH, ALR, AL, SR, S, SP, SH, SLR,
SL, CS, CDS, ICM, LCR, LNR, LPR, MVCL, SRP, SLDA, SLA,
SRDA, SRA, TRT, ED, EDMK, ZAP
TEST UNDER MASK Instruction
TM #IF TM,FIELD_A,X'01',OFF
#IF TM,FIELD_A,X'80',ON
#IF TM,FIELD_A,#CAR,NONZERO
#IF TM,FIELD_A,BIT0,OFF
#IF TM,FIELD_A,BITS2-4/6,ZERO
#IF TM,FIELD_A,BITS4-7,MIXED

Examples Of Conditional Expressions (continued)
ACP/TPF MACROS
Macro Conditional Expression
LEVTA #IF LEVTA,D4,NOTUSED

#IF LEVTA,D4,INUSE
WAITC #IF WAITC,NOK
FIWHC #IF FIWHC,D1,OK

#IF FIWHC,D1,NOK
FINWC #IF FINWC,D2,NOK
PLEASE NOTE: These macros can be handled by SPM's. Other ACP/TPF macros
with labels might not be recognised by SPM's.

Special Conditional Instructions
If a condition code has been set by another instruction or another Conditional Expression, it
is possible to code SPM's in a manner that more closely resembles traditional BAL code.
Here are some examples of this more "abbreviated" type of Conditional Expression.
Conditional Expression
#IF 8
#IF EQ
#IF ZERO
#ELIF GT
#ELIF ZERO
Two examples using Special Conditional Expressions, are as follows:
LTR R1,R1 #IF CLI,FIELD_A,EQ,X'80'

#IF ZERO MVC FIELD_B(2),=C'OK'
STC R2,FIELD_A #ELIF LT
#EIF MVC FIELD_B(3),=C'ERR'
#EIF

THE #IF MACRO - EXERCISE 1
Please code the following routines using SPM's
TM FIELD_A,X'80'
BO LABEL1
BCTR R5,0
LABEL1 EQU *
LA R6,1(R6)
CLI FIELD_A,C'G'
BE LABEL1
ST R6,FIELD_B
B LABEL2
LABEL1 EQU *
ST R6,FIELD_C
LABEL2 EQU *
SR R6,R6
LTR R2,R2
BZ LABEL3
SR R1,R4
BZ LABEL1
MVC FIELD_A(2),=C'AA'
B LABEL2
LABEL1 EQU *
MVC FIELD_A(2),=C'BB'
LABEL2 EQU *
OC FIELD_B,FIELD_C
LABEL3 EQU *
BACKC
TM FIELD_A,X'40'
BO LABEL1
OI FIELD_A,X'80'
B LABEL3
LABEL1 EQU *
C R1,FIELD_B
BL LABEL2
OI FIELD_A,X'70'
B LABEL3
LABEL2 EQU *
MVI FIELD_A,X'60'
LABEL3 EQU *
ENTNC ABCD

THE #IF MACRO - EXERCISE 2
If FIELD_A is equal to FIELD_B
Increment R1 by 10
Decrement R2 by 20
If R2 is greater than 0
Set EBW000 = 'B'
Otherwise
Set EBW000 = 'A'
Set R2 to Zero
If bit 2 of EBW000 = 0
Increment R2 by 1
If bit 2 of EBW000 = 1
Increment R2 by 10
If FIELD_A is equal to 'P', 'Q'or an 'R'
Set EBSW01 = X'FF'

Continuation and Boolean Connectors
An SPM statement that has been compounded to combine more than one Conditional
Expression is called a Complex Conditional Expression.
Complex Conditional Expressions are linked and/or separated with Boolean Connectors.
Instruction Set for Boolean Connectors
AND
OR
ANDIF
ORIF
Rules for Boolean Connectors
Complex Conditional Expressions can be expressed a couple of ways in SPMs.
• Individual Conditional Expressions are linked and separated by the Boolean

Connectors: AND and OR.
• Groups of Conditional Expressions are linked and separated by the Boolean

Connectors: ANDIF and ORIF.
If space permits, the entire Compound Conditional Expression can be placed on a single
line, as in Example 1 on the next page.

Rules for Continuation
If there is not room for the entire Compound Conditional Expression on one line, or if it is
more "readable" to have the separate Conditional Expressions each on its own line, then the
Conditional Expressions can be continued onto the next line/s by placing a hash sign (#)
followed by a blank, in any column (except column 1). Please see Example 2 below.
* No continuation character has to be specified in column 72 (as with normal BAL). Make
sure that the line ends with a comma.
Examples 1 and 2 below, illustrate how individual Conditonal Expressions are linked and
separated by the AND and OR Boolean Connectors.
Example 1
#IF TM,EBW000,X'80',ZERO,AND,TM,EBW100,X'80',ZERO
SR R1,R1
#EIF
Example 2
#IF TM,EBW000,X'80',ZERO,OR,
# TM,EBW100,X'80',ZERO
SR R1,R1
#EIF

Examples 3 and 4 below, illustrate how groups of Conditional Expressions are linked and
separated by the ANDIF and ORIF Boolean Connectors.
Example 3 Example 4
#IF CLI,EBW000,EQ,C'A',OR, #IF CLI,EBW000,GE,C'A',AND,

# CLI,EBW000,EQ,C'B',OR, # CLI,EBW000,LE,C'I',ORIF,
# CLI,EBW000,EQ,C'C',ANDIF, # CLI,EBW000,GE,C'J',AND,
# CLI,EBW100,EQ,C'1',OR, # CLI,EBW000,LE,C'R',ORIF,
# CLI,EBW100,EQ,C'2',OR, # CLI,EBW000,GE,C'S',AND,
# CLI,EBW100,EQ,C'3' # CLI,EBW000,LE,C'Z'
SR R1,R1 LA R1,1(R1)
#EIF #EIF
Example 5 below, illustrates the same example as seen above in Example 3. In this
illustration however, please note that the ANDIF has been placed on a line by itself. This is
also an acceptable manner to code, using the Boolean Connector.
Example 5
#IF CLI,EBW000,EQ,C'A',OR,
# CLI,EBW000,EQ,C'B',OR,
# CLI,EBW000,EQ,C'C',
# ANDIF,
# CLI,EBW100,EQ,C'1',OR,
# CLI,EBW100,EQ,C'2',OR,
# CLI,EBW100,EQ,C'3'
SR R1,R1
#EIF

BOOLEAN CONNECTORS - EXERCISE 1
Please code the following routines using SPM's with Boolean Connectors:
CLI FIELD_A,C'X'
BE LABEL1
CLI FIELD_A,C'Y'
BNE LABEL2
LABEL1 EQU *
SR R6,R6
LABEL2 EQU *
LA R5,1(R5)
CLI EBW000,X'80'
BH LABEL1
CLI EBW000,X'08'
BL LABEL1
ST R5,FIELD_A
LABEL1 EQU *
BACKC
CLI FIELD_A,C'P'
BE LABEL1
CLI FIELD_A,C'Q'
BE LABEL1
CLI FIELD_A,C'R'
BNE LABEL2
LABEL1 EQU *
CLI FIELD_B,X'FO'
BE LABEL3
CLI FIELD_B,X'F1'
BE LABEL3
CLI FIELD_B,X'F2'
BE LABEL3
LABEL2 EQU *
MVC FIELD_C(3),=C'ERR'
B LABEL4
LABEL3 EQU *
MVC FIELD_C(2),=C'OK'
LABEL4 EQU *
ENTRC ABCD

The #DO Macro
The #DO Macro is used to handle the Iteration element of Logic, (i.e. Looping).
Instruction Set for the #DO Macro
#DO
#DOEX
#EXIF
#OREL
#ELOP
#EDO
Rules for the #DO Macro
• Perform the code between #DO and #EDO (or #ELOP) as long as the Conditional
Expression(s) is/are true.
• Parentheses are necessary for the Conditional Expression.
• Complex Conditional Expressions can be used (linking with AND/ANDIF and

separating with OR/ORIF).

Simple Loop Control Mechanisms
DO WHILE DO UNTIL or DO TIMES
Control is at the start of the loop. Control is at the end of the loop.
The process will not be performed The process will always be performed at
if the condition is not met least once.
#DO #DO
UNTIL/
WHILE TIMES
FALSE
CONDITION
INITIALISE
TRUE IF TIMES
PROCESS PROCESS
#EDO CONDITION
FALSE
TRUE
#EDO

#DO WHILE=( )
The Condition is being checked at the top of the loop. (Loop could be executed 0 times).
Examples
#DO WHILE=(TM,FIELDA,BIT1,ON,AND,TM,FIELDB,BIT2,OFF)
#DO WHILE=(LTR,R1,R1,NONZERO)
#DO WHILE=(CH,R1,EQ=H'500',OR,CH,R2,EQ,=H'650')
#DO UNTIL=( )
The Condition is being checked at the bottom of the loop. (Loop will be executed at least
once.)
Examples
#DO UNTIL=(TM,FIELDA,BIT1,OFF)
#DO UNTIL=(TM,FIELDA,BIT1,OFF,AND,TM,FIELDB,BIT2,ON)
#DO UNTIL=(CH,R1,LT=H'500',OR,CH,R2,GT,=H'650')
#DO INF
Creates an infinite loop. Needs at least one #DOEX or #EXIF in order to terminate the loop.
Example
#DO INF

#DO TIMES=REG or #DO TIMES=(REG,n)
Perform the code between #DO and #EDO (or #ELOP) until the specified register is 0.
The generated BCT is being performed at the bottom of the loop.
The specified register can be loaded before the loop or by specifying an intialization value
(n) as the second paratmeter.
Examples
First Generated Instruction
#DO TIMES=(R1,RCDCOUNT) L R1,RCDCOUNT
#DO TIMES=(R1,H/RCDCOUNT) LH R1,RCDCOUNT
#DO TIMES=(R1,R2) LR R1,R2
#DO TIMES=(R1,20) LA R1,20
#DO TIMES=(R2,8000) LH R2,=H'8000'
#DO TIMES=(R4,90000) L R4,=F'90000'
Note:-
If the DO TIMES count is in the range 1 - 4095 then a LA will be generated:

If the DO TIMES count is in the range 4096 - 32767 then a LH will be generated:
If the DO TIMES count is in the range 32767 - 2147483647 then a L will be generated:
#EDO
End of Loop.
End of Loop-end processing is invoked when #ELOP is specified

#ELOP
• End of iteration
• Start of loop-end processing
• Will be automatically generated by #EDO, if not specified
• Only one #ELOP is allowed in a #DO loop
• The code between #ELOP and #EDO will be executed once.
• At loop end time, control is given to #ELOP:
• If Conditional Expression in "WHILE=" becomes untrue
• If Conditional Expression in "UNTIL=" becomes true
• If "REG" in the "TIMES=" becomes zero
• If Conditional Expression in a #DOEX is true
#ELOP Example
FALSE
#DO
#DO
................
................ TRUE
................
................ PROCESS
#ELOP
................
................
................ #ELOP
................
#EDO
PROCESS
#EDO

#DOEX
• Exit the loop based on Conditional Expression
• If Conditional Expression is true, control is given to #ELOP
• If no #ELOP is given, control is given to #EDO
• More than one #DOEX can be specified within a loop
• #DOEX can only be coded in conjunction with a #DO loop. It can never be used in
conjunction with an #IF macro.
#DOEX/#ELOP Example
#DO
#DO WHILE WHILE
................
................ FALSE
................ CONDITION
................
#DOEX TRUE
................
................ PROCESS
................
................
TRUE
#EDO #DOEX
PROCESS
#EDO
Example: #DOEX CLI,EBW000,EQ,C'A'

#EXIF
• Exit from the loop based on Conditional Expression.
• The code between #EXIF and #OREL is performed once, if the Conditional Expression is
true, and after that, control is given to #EDO (never to #ELOP).
• Each #EXIF must have one (and only one) #OREL.
• More than one #EXIF can be specified within a loop.
• #EXIF can only be coded in conjuction with a #DO macro.
• #EXIF can never be coded in conjunction with an #IF macro.
#EXIF/#OREL Example 1
#DO
WHILE
#DO WHILE
................ FALSE
CONDITION
................
................
................ TRUE
#EXIF
PROCESS
................
................
................
................ #EXIF FALSE
#EXIF
#OREL
................
#EXIF TRUE
................
................
................ PROCESS
#EDO
#OREL
PROCESS
#EDO

#EXIF/#OREL Example 2
#DO
WHILE
#DO WHILE
................
................ FALSE
CONDITION
................
................
TRUE
#EXIF PROCESS
................
PROCESS
................
................
................
#EXIF FALSE
#OREL #EXIF #OREL
................
................
................ #EXIF TRUE
................
#ELOP
................ PROCESS
#ELOP
................
................
................
#EDO
PROCESS
#EDO
Example: #EXIF CLI,EBW000,EQ,C'A'
#OREL
Continuation of the main inline code of the #DO loop, in case the Conditional Expression in
the previous #EXIF was not true.
Will be generated automatically (after a previous #EXIF) when a #DOEX, #ELOP, #EDO,
or a next #EXIF is coded.

The #DO Macro - Basic Structures
#DO true
.................
.................
#EDO
#DO true
.................
#DO true
.................
.................
#EDO
.................
.................
#EDO
#DO true
.................
.................
.................
#ELOP
.................
.................
#EDO
#DO true
.................
#DOEX true
.................
#DOEX true
.................
#ELOP
.................
.................
#EDO

Combination of #DO Loops
All combinations of a #DO WHILE, a #DO UNTIL, and a #DO TIMES are valid in a #DO
macro (only one of each).
If a "DO UNTIL" is combined with a "DO TIMES" (both tests will be performed at the
bottom of the loop), the "BCT" of the "#DO TIMES" will be the last generated instruction.
Example
#DO TIMES=(R1,10),
# WHILE=(OC,FIELD_A,FIELD_A,ZERO),
# UNTIL=(LTR,R4,R4,NOTNEGATIVE)
.............................
.............................
.............................
#EDO
Complex Conditional Expressions with #DO Loops
The Complex Conditional Expression must be specified within one set of parentheses, and
continuation must be done through column 72, starting the next line in column 16. Any
character can be used for continuation, but in keeping with the standard continuation
character, it is advised that an asterisk (*) be used.
Example
COL 16 COL 72
↓ ↓
#DO WHILE=(CLC,FIELD_A,EQ,FIELD_B,AND, *
TM,EBSW01,X'80',OFF,AND, *
CLI,EBW100,EQ,C'Y')
.............................
.............................
#EDO

The #DO Macro - CODING GUIDELINES
All forms of the #DO macro are taught on this course, as students may have to maintain
code which contains these forms: however, Galileo Guidelines (TPF Assembler/Program
Design/Structured Programming/SPMs and Subroutines) discourages the use of certain
parameters.
You should NOT use
#EXIF
#DOEX
#ELOP
#OREL
except where completely unavoidable, as these unstructure the code: there should only be
one exit point from a loop. Instead of using #DOEX or #EXIF, use #DO UNTIL or #DO
WHILE to test for exit conditions, and/or #DO TIMES to limit the loop count.
You should also avoid the use of #DO INF - if you have set a #DOEX or #EXIF condition
in your loop to use as an exit point, and the condition or conditions are not met, then the
program will loop until the time limit allowed is reached and a dump is produced.

The DO MACRO - EXERCISE 1
L R1,CE1CR1
L R2,CE1CR2
SR R4,R4
LA R3,15
LABEL1 EQU *
CLC 0(5,R1),0(R2)
BE LABEL2
LA R4,1(R4)
LABEL2 EQU *
LA R1,5(R1)
BCT R3,LABEL1
L R1,CE1CR0
SR R3,R3
SR R4,R4
LABEL1 EQU *
CLI 0(R1),#EOM
BE LABEL3
CLI 0(R1),C'A'
BNE LABEL2
LA R3,1(R3)
LA R1,1(R1)
B LABEL1
LABEL2 EQU *
LA R4,1(R4)
LA R1,1(R1)
B LABEL1
LABEL3 EQU *
BACKC
L R1,CE1CR0
LA R2,100
LABEL1 EQU *
CLI 0(R1),X'4E'
BE LABEL3
CLI 0(R1),X'F0'
BL LABEL2
CLI 0(R1),X'F9'
BH LABEL2
LA R1,1(R1)
BCT R2,LABEL1
B LABEL3
LABEL2 EQU *
MVC EBW000(3),=C'ERR'
LABEL3 EQU *
BACKC

THE #DO MACRO - EXERCISE 2
1) Edit the 20 characters that can be found in EBW000 through EBW019. If either an
#EOM or a #CAR character are found:
a) stop the edit,

b) move the character found into EBW100,
c) move the characters "ERR" into EBX000 - EBX002.
If all 20 characters are edited successfully, (with-out encountering either the #EOM or #CAR
characters), then move the characters "OK" into EBX000 - EBX001.
In either case, at the end of the routine, return to caller.
2) Edit the 14 hex numbers to be found in EBW000 through EBW013. For each number
over 5, increment R1 by one. For each number equal to or less than 5, decrement R1 by one.

The #PERF Macro
The #PERF Macro is used to access a subroutine from a mainline.
Instruction Set for the #PERF Macro
#PERF
#SUBR
#ESUB
Rules for the #PERF Macro
• The #PERF macro will generate a "BAS" to the specified subroutine.
• The #PERF macro can can be specified at any nesting level.
• A "BAS" register must be specified as part of the #PERF macro parameters.
• A register save area may be added to the #PERF macro as an optional parameter. The
register save area must be defined as a Fullword of storage. If the #PERF macro has a
register save area specified, the generated BAL instructions are as follows:
#PERF R3,SUB_1,REG_SAVE1 ST R3,REG_SAVE1

BAS R3,SUB_1
L R3,REG_SAVE1
N.B:- The Register Save Area cannot be defined in the program; if defined in the program
it will give a Re-entrant Check Failure upon assembly: it must either be an area in
the ECB or a core block DSECT.

#SUBR
• The #SUBR macro is the beginning of the Subroutine.
• Each #SUBR macro must have one (and only one) #ESUB.
• The linkage register specified in the #SUBR macro must be the same register as
specified in the corresponding #PERF macro(s).
• A register save area may be added to the #SUBR macro as an optional parameter. The
register save area must be defined as a Fullword of storage. If the #SUBR macro has a
register save area specified, the generated BAL instructions are as follows:
#SUBR SUB1,R3,REG_SAVE1 ST R3,REG_SAVE1
N.B:- The Register Save Area cannot be defined in the program; if defined in the program
it will give a Re-entrant Check Failure upon assembly: it must either be an area in
the ECB or a core block DSECT.
#ESUB
• The #ESUB is the end of a subroutine.
• The #ESUB will generate an unconditional "BR" using the linkage register specified in
the corresponding #SUBR macro(s).
• If the #SUBR macro had a register save area specified, the following BAL code will be
generated:
#ESUB L R3,REG_SAVE1
BR R3

The #PERF Macro - Basic Structures
#PERF REG,SUBROUTINE_1
................
................
................
................
#SUBR SUBROUTINE_1,REG
................
................
................
#ESUB
#PERF REG,SUBROUTINE_1,REG_SAVE
................
................
................
#SUBR SUBROUTINE_1,REG
................
................
................
#ESUB
................
................
................
#SUBR SUBROUTINE_1,REG,REG_SAVE
................
................
................
#ESUB

The #PERF Macro - CODING GUIDELINES
Use of #PERF, #SUBR, BAS.
Subroutines
• Use Subroutines to avoid duplication of code.

• Use Subroutines for specific functions (e.g. retrieve information from a database, request
information from an external package, business processes that require complex comments.)
• Subroutines may be nested where a high level function is achieved by a series of low level
functions.
• Use Subroutines to separate the code into discrete functions.
• Give subroutines clear descriptive names.
Example:
#PERF R15,"ENTER FARES FOR FILED FARE DATA"

.........................
.........................
.........................
.........................
#SUBR "ENTER FARES FOR FILED FARE DATA",R15
.........................
.........................
#ESUB

The #GOTO Macro
The #GOTO macro handles the processing of unusual exit conditions from the normal
structure flow. It is a "hard branch", and should only be used for Error processing, and/or
to move "down" the code to Error label(s).
Instruction Set for the #GOTO Macro
#GOTO
#LOCA
Rules for the #GOTO Macro
• The #GOTO macro generates a branch to the appropriate #LOCA processing.
• In conjunction with the #GOTO macro, a Conditional Expression may be specified in an

"IF" format. (See Example below.)
• The #GOTO macro may be coded at any nesting level.
• Each #GOTO must have one (and only one) #LOCA.
#LOCA label
The #LOCA macro generates an internal SPM label (i.e. #@LB87).
The following examples illustrate how the #GOTO macro is coded with a Conditional
Expression and without a Conditional Expression:
Examples:
#GOTO LABEL1,IF,LTR,R1,R1,ZERO
#GOTO LABEL1
#LOCA LABEL1

The #EXEC Macro
The #EXEC macro gives the same capability as the BAL "EX" instruction.
Instruction Set for the #EXEC Macro
#EXEC
Rules for the #EXEC Macro
• The #EXEC macro will execute against the SPM symbolic representation of a BAL
instruction by altering (in execution) the 2nd byte of that generated instruction. The
value of the low order byte of the specified general register is "OR'd" with the value in
the 2nd byte of the generated instruction.
• Unlike the "EX" instruction in BAL, the #EXEC macro does not require a label.
• The #EXEC macro may be coded to include a Conditional Expression or it may be

coded with its only parameters being the general register and fields specified.
• The #EXEC macro will generate the assembler instruction to be executed and then will
"EX" (using REG) the previous instruction.
• The #EXEC macro requires the same action as the BAL instruction, i.e. subtract one
from the register before the EXEC instruction, then add one after execution to allow for
the Excess One Principle.
The following examples illustrate how the #EXEC macro is coded as a statement.
#EXEC R1,MVC,FIELD_A(0),FIELD_B MVC FIELD_A(0),FIELD_B

EX R1,*-6
#EXEC R3,MVI,FIELD_A,X'00' MVI FIELD_A,X'00'

EX R3,*-4
The following illustrates how the #EXEC macro is coded as a Conditional Expression.
CLC FIELD_A(0),FIELD_B
#IF #EXEC,R1,CLC,FIELD_A(0),EQ,FIELD_B EX R1,*-6
BNE .....

The #UEXEC Macro
The #UEXEC macro is a Galileo macro, written in-house, and performs the same function as the
#EXEC macro, except that it will decrement the register by one before executing the EX instruction
and add one again afterwards, thereby removing the need to remember the Excess One Principle
from the programmer.
Instruction Set for the #UEXEC Macro
#UEXEC Rx,instruction,ERROR=label
Rules for the #UEXEC Macro
The rules for the #UEXEC Macro are the same as for the #EXEC macro, with the following
exceptions:
• Unlike the #EXEC macro, the #UEXEC macro decrements one from REG before the EX
instruction is executed and adds one afterwards, to allow for the Excess 1 Principle.
• The #UEXEC macro cannot be coded to include a Conditional Expression. As it is a Galileo

written macro, and as the SPMs we use are a Swissair (and latterly IBM) product, the #IF does
not recognise #UEXEC as a valid keyword parameter, and gives an assembly error.
• If the ERROR= parameter is specified, a #LOCA must be specified for the error label (see
example below). If the register holds a non-positive value, the EX instruction will NOT be
executed: instead, a branch will be generated to the error label specified on the ERROR
parameter.
• If the ERROR parameter is omitted, an MNOTE will be generated (RC=04) on assembly: if the
register contains a non-positive value, the EX instruction will NOT be executed, but processing
will continue as if the EX instruction WAS executed, (i.e. processing will branch around the EX
instruction) and no error return code will be set on at execution time, therefore it is strongly
recommended that the register is tested for a non-positive value before executing both the
#EXEC and #UEXEC macros. Obviously, no #LOCA is required if the error parameter is
omitted.
The following example illustrates how the #UEXEC macro is coded as a statement, plus a precis of
the generated BAL instructions.
#UEXEC R3,MVC,FLDA(0),FLDB,ERROR=ERRLBL1 LTR R3,R3

BNP ERRLBL1
.......... INSTR MVC FLDA(0),FLDB
.......... (code) ....
BCTR R3,0
.......... EX R3,INSTR
#LOCA ERRLBL1 LA R3,1(R3)
............ (error code)

The #CASE Macro
The #CASE macro handles the multiple selection element of logic.
The process to be executed is selected according to a positive integer value in a General

register. The first case value is a power of two (including 0) and the subsequent case
numbers must be multiples of the first.
The 'CASE' Set
#CASE 1 PROCESS CASE 1
#CAST #CASE 3 PROCESS CASE 3 #ECAS
#CASE ERROR PROCESS ERRORS
Instruction Set for the #CASE Macro
#CAST Start of selection
#CASE Start of a selected case
#ECAS End of selection

#CAST reg or #CAST reg,POWER=n or #CAST reg,POWER=n,MAX=M
The #CAST macro is the start of selection.
Each #CAST macro must have one (and only one) #ECAS macro.
Each #CAST macro must have at least one #CASE macro.
The general register specified (which must not be register 0), contains the case number,
which is adjusted to index into the branch table generated by the #ECAS macro.
The POWER=n parameter indicates to what power the case numbers are multiples. Case
numbers must always be in powers of 2 (including the power of 0). The default value of
POWER= is 0 in which case, all case numbers will be multiples of 1.
The MAX=n parameter specifies the maximum case number possible. If not specified, all
case numbers are treated as valid and no checking is performed upon execution. If specified,
then a #CASE ERROR must also be included.
WARNING!! If no MAX=n is specified, a case number in the register which is greater than
the largest specified in a #CASE macro will cause a wild branch into the program!

Rules for the #CASE Macro
#CASE Nx or #CASE Nx,Ny or #CASE ERROR
• The #CASE macro is the start of selected case(s) for specified case numbers.
• The #CASE macro handles multiple selections based on a numeric value contained in a
general register.
• The numeric value of the first case must be a power of 2 (the default is 0), and the other
case numbers within the same set must be multiples of the first.
• Upon request, invalid case numbers will be checked for during execution with the
MAX=n parameter on #CAST combined with #CASE ERROR. Invalid case numbers
are:
1. Values exceeding the largest case number specified
2. Values which are not multiples of the first case number
3. Negative values
• All valid, but unspecified case numbers (including zero) simply drop through the
structure.
• If a specified number conflicts with the power parameter, an error (MNOTE) is

generated and the number is ignored.
#ECAS
• End of selection.
• The #ECAS macro generates a branch table entry for all case numbers specified.
• For all valid case numbers lower than the highest specified, which do not appear in a
#CASE macro statement, a dummy table entry is generated to bypass the case set.
PLEASE NOTE: During execution, the value in "reg" is modified...unless POWER=2

#CAST Macro - Examples
#CAST R1 Case numbers are multiples of 1 (Default POWER=0)
#CAST R1,POWER=0 Case numbers are multiples of 1

#CASE macro - Example 1
#CAST R1,MAX=10 Case numbers are multiples of 1

Maximum case number is 10
#CASE 1,3,5,7 Processing is performed if.R1 contains a 1, 3, 5, or 7
#CASE 4,8 Processing is performed if R1 contains a 4 or an 8
#CASE ERROR Processing is performed if R1 contains a negative

value or a value greater than 10
#ECAS A 10 word branch table is generated. Dummy

case numbers 2, 6, 9, and 10 drop through to the
end without processing.
#CASE macro - Example 2
#CASE 32,8 Processing is performed if R1 contains a 32 or an 8
#CASE 16 Processing is performed if R1 contains a 16
#ECAS Generates a four word branch table with entries for

case numbers 8, 16, 24, and 32 (24 is a dummy
entry)

The #CASE Macro - CODING GUIDELINES
• Avoid the use of #CASE if a simple #IF / #ELIF structure will do the job.
• Use #CASE only where there is a clear relationship between the value in the register and
the logical paths to be taken.

THE #CASE MACRO - EXERCISE 1
Please code the following routine using SPM's
LTR R1,R1
BZ LABEL5
BM LABEL4
CH R1,=H'1'
BE LABEL1
CH R1,=H'3'
BE LABEL2
CH R1,=H'4'
BE LABEL2
CH R1,=H'6'
BE LABEL3
BH LABEL4
B LABEL5
LABEL1 EQU *
MVC EBW000(5),=C'NBR 1'
B LABEL5
LABEL2 EQU *
MVC EBW000(7),=C'NBR 3/4
B LABEL5
LABEL3 EQU *
MVC EBW000(5),=C'NBR 6'
B LABEL5
LABEL4 EQU *
MVC EBW000(3),=C'ERR'
LABEL5 EQU *
BACKC

The Condensed Form
In order to make the coding of Conditional Expressions less verbose, a wide variety of
Condensed Forms have been introduced.
Rules for the Condensed Form
The usage of these condensed forms is dependent on a number of conventions, some of

which are common in the TPF world, but may not be in other assember programming
environments.
• Any two or three character operand starting with the character "R", is assumed to be a
general purpose register.
• Any operand starting with the character "#",is assumed to be a system equate value.
• Any operand starting with the characters "BIT", is assumed to refer to a specific bit
pattern for a TM type of operation.
The Condensed TEST UNDER MASK
Where a "TM" is desired, the operation code can be omitted if the second operand begins
with the characters "BIT".
PLEASE NOTE: If more than one "BIT" is to be tested, then the second operand begins
with the characters "BITS".
Condensed Test Under Mask - Examples
Condensed Form Generated BAL
#IF EBW000,BIT3,OFF TM EBW000,X'10'
#IF EBW000,BITS4-6,MIXED TM EBW000,X'0E'
#IF EBW000,BITS1/3/5/7,ON TM EBW000,X'55'
#IF EBW000,BITS0-3/5-7,ON TM EBW000,X'F7'

The Condensed "COMPARE" Command
Where it is obvious from the operand what type of compare instruction should be generated,
the operation code (CR,C, CH, CLC, or CLI) can be omitted.
PLEASE NOTE: Once in a while, the assembly generates something other than the BAL
instruction that was expected, i.e. CLC vs. CLI. This can cause some confusion when
testing! Be sure of the type of compare instruction that will be generated! If you're not
sure...check!
Condensed Compare - Examples
#IF R1,EQ,R3 CR R1,R3
#IF R1,GE,EBW000 C R1,EBW000
#IF R2,LT,10(R3) C R2,10(R3)
#IF R2,LE,=H'123' CH R2,=H'123'
#IF R3,GT,H/24(R5) CH R3,24(R5)
#IF EBW000(3),NE,FIELD_A CLC EBW000(3),FIELD_A
#IF EBW000,LT,5 CLI EBW000,5
#IF EBW000,GT,X'F0' CLI EBW000,X'F0'
#IF EBW000,NH,I/VALUE CLI EBW000,VALUE
#IF EBW000,EQ,#CAR CLI EBW000,#CAR
THE CONDENSED "LTR" AND "OC"
If the first and second operands of a "LTR" or "OC" are the same, then the operation code
and the second operand can be omitted.
#IF R1,NONZERO LTR R1,R1
#IF EBW000(4),ZERO OC EBW000(4),EBW000

The Condensed Form - CODING GUIDELINES
Even though the mnemonic for the Op Code in Conditional Expressions is not mandatory, it
should still be included for clarity, i.e.
Instead of coding #IF FIELD_A,EQ,FIELD_B
You should code #IF CLC,FIELD_A,EQ,FIELD_B

THE CONDENSED FORM - EXERCISE 1
Code the following routines using SPM's and the Condensed form whenever possible.
CLI FIELD_A,C'G'
BE LABEL1
ST R6,FIELD_B
B LABEL2
LABEL1 EQU *
ST R6,FIELD_C
LABEL2 EQU *
SR R6,R6
LTR R2,R2
BZ LABEL3
SR R1,R4
BZ LABEL1
MVC FIELD_A(2),=C'AA'
B LABEL2
LABEL1 EQU *
MVC FIELD_A(2),=C'BB'
LABEL2 EQU *
OC FIELD_B,FIELD_C
LABEL3 EQU *
BACKC
TM FIELD_A,X'40'
BO LABEL1
OI FIELD_A,X'80'
B LABEL3
LABEL1 EQU *
C R1,FIELD_B
BL LABEL2
OI FIELD_A,X'70'
B LABEL3
LABEL2 EQU *
OI FIELD_A,X'60'
LABLE3 EQU *
ENTNC ABCD

S P Ms Notes

Uploaded by

Copyright:

Available Formats

S P Ms Notes

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

S P Ms Notes

Uploaded by

Copyright:

Available Formats

GA L I LEO

TECHNICAL TRAINING DEPARTMENT

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page i

Instruction Set for the #DO Macro

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page ii

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page iv

There are three basic logical components to programming:

SPM's are now used by more than 30 ACP/TPF installations.

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page 1

Some Basic Conventions

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page 2

The #IF Macro

Instruction Set for the #IF Macro

Rules for the #IF Macro

• Each #IF must have one (and only one) #EIF.

• Each #IF may have multiple #ELIF's.

• Each #IF may have one (and only one) #ELSE.

• There are no parameters for the #ELSE and #EIF macros.

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page 3

The #IF MACRO - Basic Structures

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page 4

The #IF Macro - Basic Structures

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page 5

The #IF Macro - Basic Structures

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page 6

The #IF Macro - Basic Structures

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page 7

The Conditional Expression

Instructions that must have a Conditional Expression:

Instructions that can have a Conditional Expression:

Rules for the Conditional Expression:

• The Conditional Expression can have two forms:

1) A Symbolic Representation of a standard BAL instruction which results in a

2) A Symbolic Representation of certain ACP/TPF Macro calls (i.e. LEVTA &

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page 8

Valid Condition Code Mnemonics

COMPARE EQ, GE, GT, H, L, LE, LT, NE, NH, NL

ARITHMETIC M, NM, NO, NP, NZ, O, P, Z, NEGATIVE,

TEST UNDER MASK M, NM, NO, NZ, O, Z, ZERO, MIXED, NOTMIXED,

• In the COMPARE INSTRUCTION, the Conditional Code Mnemonic is placed

• In the ARITHMETIC and TM INSTRUCTIONS, the Condition Code Mnemonic is

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page 9

Examples Of Conditional Expressions

Instruction Conditional Expression

CLC #IF CLC,FIELD_A(3),EQ,=C'ABC'

CLI #IF CLI,FIELD_A,GT,4

CLCL #IF CLCL,R2,NE,R4

CLM #IF CLM,R1,B'1100',NE,FIELD_B

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page 10

Examples Of Conditional Expressions (continued)

Instruction Conditional Expression

LTR #IF LTR,R1,R1,NOTNEGATIVE

TEST UNDER MASK Instruction

Instruction Conditional Expression

22561379.doc 1997 Galileo International Partnership. All Rights Reserved. Page 11

Examples Of Conditional Expressions (continued)

Macro Conditional Expression

LEVTA #IF LEVTA,D4,NOTUSED

WAITC #IF WAITC,NOK

FIWHC #IF FIWHC,D1,OK