S P Ms Notes

OG A L I L EI N 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.........................................................................1Some Basic Conventions......................................................................2The #IF Macro....................................................................................3

Instruction Set for the #IF Macro...................................................................3Rules for the #IF Macro..................................................................................3The #IF MACRO - Basic Structures................................................................4

The Conditional Expression.................................................................8Instructions that must have a Conditional Expression:................................8Instructions that can have a Conditional Expression:...................................8Rules for the Conditional Expression:...........................................................8Valid Condition Code Mnemonics..................................................................9Examples Of Conditional Expressions.........................................................10Special Conditional Instructions..................................................................13

Continuation and Boolean Connectors................................................16Instruction Set for Boolean Connectors.......................................................16Rules for Boolean Connectors.....................................................................16Rules for Continuation.................................................................................17

The #DO Macro.................................................................................20Instruction Set for the #DO Macro..............................................................20Rules for the #DO Macro.............................................................................20Simple 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............................................................................................................26The #DO Macro - Basic Structures..............................................................28Combination of #DO Loops.........................................................................29Complex Conditional Expressions with #DO Loops....................................29The #DO Macro - CODING GUIDELINES.......................................................30

The #PERF Macro..............................................................................33Instruction Set for the #PERF Macro...........................................................33Rules for the #PERF Macro..........................................................................33#SUBR..........................................................................................................34#ESUB..........................................................................................................34The #PERF Macro - Basic Structures...........................................................35The #PERF Macro - CODING GUIDELINES....................................................36

Subroutines.......................................................................................................................36The #GOTO Macro.............................................................................37

Instruction Set for the #GOTO Macro..........................................................37Rules for the #GOTO Macro.........................................................................37#LOCA label...............................................................................................37

The #EXEC Macro..............................................................................38Instruction Set for the #EXEC Macro...........................................................38Rules for the #EXEC Macro..........................................................................38

The #UEXEC Macro............................................................................39Instruction Set for the #UEXEC Macro........................................................39Rules for the #UEXEC Macro.......................................................................39

The #CASE Macro..............................................................................40The 'CASE' Set..............................................................................................40Instruction Set for the #CASE Macro...........................................................40

document.doc 1997 Galileo International Partnership. All Rights Reserved. Page i


#CAST reg or #CAST reg,POWER=n or #CAST reg,POWER=n,MAX=M 41Rules for the #CASE Macro..........................................................................42#CASE Nx or #CASE Nx,Ny or #CASE ERROR................................42#ECAS..........................................................................................................42The #CASE Macro - CODING GUIDELINES...................................................45

The Condensed Form.........................................................................47Rules for the Condensed Form....................................................................47The Condensed TEST UNDER MASK............................................................47The Condensed "COMPARE" Command......................................................48The Condensed Form - CODING GUIDELINES..............................................49

document.doc 1997 Galileo International Partnership. All Rights Reserved. Page ii


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.

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

#EIF

FALSE

TRUE

#EIF

PROCESS

#IF#IF true.................................

#ELSE

FALSE

TRUE

#EIF

...........

...........

...........#EIF

PROCESSPROCESS

#ELSE

#IF true.................................

#ELIF true.................................

#EIF

#IFFALSE

TRUE

#EIF

PROCESSPROCESS

#ELIF

TRUE

FALSE



The #IF Macro - Basic Structures

TRUEPROCESS#IF true

#ELIF true

#EIF

#ELIF true

#ELSE

#IF

FALSE

#ELIF

FALSE

FALSE

#ELSE

TRUEPROCESS

TRUEPROCESS#ELIF

...........

...........

......................

...........

...........

...........

......................

...........

...........

...........

......................

...........

...........

...........

...........

...........

...........

#EIF

PROCESS




TRUEPROCESS#IF true

#ELIF true

#EIF

#IF true

#ELSE

#IF

FALSE

FALSE

PROCESS

#ELIF

...........

...........

......................

...........

...........

...........

......................

...........

...........

...........

......................

...........

#EIF

#EIF

TRUE#IF

TRUE

FALSE

#ELSE

#EIF

PROCESS




TRUEPROCESS#IF true

#ELSE

#EIF

#IF true

#ELSE

#IF

FALSE

PROCESS

#ELSE

...........

...........

......................

...........

...........

...........

......................

...........

...........

...........

......................

...........

#EIF

#EIF

#IFTRUE

FALSE

#ELSE

#EIF

PROCESS



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

WAITC

FIWHC

FINWC

#IF LEVTA,D4,NOTUSED#IF LEVTA,D4,INUSE

#IF WAITC,NOK

#IF FIWHC,D1,OK #IF FIWHC,D1,NOK

#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 ZERO STC R2,FIELD_A#EIF

#IF CLI,FIELD_A,EQ,X'80' MVC FIELD_B(2),=C'OK'#ELIF LT 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 LABEL1ST R6,FIELD_B B LABEL2

LABEL1 EQU * ST R6,FIELD_C

LABEL2 EQU *SR R6,R6

LTR R2,R2 BZ LABEL3SR R1,R4 BZ LABEL1MVC 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',ZEROSR 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,# 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

#IF CLI,EBW000,GE,C'A',AND,# CLI,EBW000,LE,C'I',ORIF,# CLI,EBW000,GE,C'J',AND, # CLI,EBW000,LE,C'R',ORIF,# CLI,EBW000,GE,C'S',AND, # CLI,EBW000,LE,C'Z'

LA R1,1(R1) #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 LABEL1CLI FIELD_A,C'Q'BE LABEL1CLI 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 performedif the condition is not met

The process will always be performed atleast once.

PROCESS

FALSE

TRUE

#EDO

#DOWHILE

CONDITION

TRUE

#EDO

INITIALISEIF TIMES

#DOUNTIL/TIMES

PROCESS

FALSECONDITION



#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

TRUE

#EDO

#DO

PROCESS

#ELOP

#DO................................................................

................

................

................

................

#ELOP

#EDO

PROCESS



#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

FALSE

TRUE

#DOEX

#EDO

TRUE

CONDITION

PROCESS

WHILE#DO WHILE................................................................

................

................

................

................

#DOEX

#EDO

PROCESS

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

FALSE

TRUE

#DO

#EXIF

#EDO

#EXIF FALSE

CONDITION

PROCESS

WHILE

#EXIF TRUE

PROCESS

#DO WHILE................................................................

................

................

................

................

#EXIF

#EDO

................

................

................

................

#OREL

#OREL

PROCESS



#EXIF/#OREL Example 2

FALSE

TRUE

#DO

#EXIF TRUE

CONDITION

PROCESS

WHILE

#EXIF FALSE

#ELOP

PROCESS

#OREL

#DO WHILE................................................................

................

................

................

................

#EXIF

#EDO

................

................

................

................

#OREL

................

................

................

................

#ELOP

PROCESS

#EXIF

#EDO

PROCESS

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 conditionin 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,CE1CR1L R2,CE1CR2SR R4,R4LA R3,15

LABEL1 EQU *CLC 0(5,R1),0(R2)BE LABEL2LA 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_SAVE1BAS 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_SAVE1BR R3



The #PERF Macro - Basic Structures

#PERF REG,SUBROUTINE_1 ................................

#PERF REG,SUBROUTINE_1 ................................

#SUBR SUBROUTINE_1,REG ................................................

#ESUB

#PERF REG,SUBROUTINE_1,REG_SAVE ................................................

#SUBR SUBROUTINE_1,REG ................ ................................

#ESUB

#PERF REG,SUBROUTINE_1................................................

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

#IF #EXEC,R1,CLC,FIELD_A(0),EQ,FIELD_BCLC FIELD_A(0),FIELD_BEX 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 .......... .......... (code) .......... #LOCA ERRLBL1 ............ (error code)

LTR R3,R3 BNP ERRLBL1INSTR MVC FLDA(0),FLDB .... BCTR R3,0 EX R3,INSTR LA R3,1(R3)



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

#CAST #ECAS

#CASE 4

PROCESS CASE 3

#CASE 2

#CASE 1

#CASE ERROR

PROCESS CASE 2

PROCESS CASE 1

PROCESS CASE 4

PROCESS ERRORS

#CASE 3

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 1,3,5,7 #CASE 4,8 #CASE ERROR #ECAS

Case numbers are multiples of 1Maximum case number is 10 Processing is performed if.R1 contains a 1, 3, 5, or 7

Processing is performed if R1 contains a 4 or an 8

Processing is performed if R1 contains a negative value or a value greater than 10

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

#CAST R1,POWER=3 #CASE 32,8 #CASE 16 #ECAS

Case numbers are multiples of 8 Processing is performed if R1 contains a 32 or an 8

Processing is performed if R1 contains a 16 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,R1BZ LABEL5BM LABEL4CH R1,=H'1'BE LABEL1CH R1,=H'3'BE LABEL2CH R1,=H'4'BE LABEL2CH R1,=H'6'BE LABEL3BH LABEL4B LABEL5

LABEL1 EQU *MVC EBW000(5),=C'NBR 1'B LABEL5

LABEL2 EQU *MVC EBW000(7),=C'NBR 3/4B 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 LABEL1ST R6,FIELD_BB LABEL2

LABEL1 EQU *ST R6,FIELD_C

LABEL2 EQU *SR R6,R6

LTR R2,R2BZ LABEL3 SR R1,R4BZ LABEL1MVC 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 LABEL1OI FIELD_A,X'80'B LABEL3

LABEL1 EQU *C R1,FIELD_BBL LABEL2OI FIELD_A,X'70'B LABEL3

LABEL2 EQU *OI FIELD_A,X'60'

LABLE3 EQU *ENTNC ABCD


S P Ms Notes

Documents

Transcript of S P Ms Notes