Assembler Language Macro "Boot Camp" Part 2

Assembler Language 

Macro "Boot Camp" 

Part 2 

SHARE in Austin 

March 1 - 6, 2009 

Session 8159 

Who am I? 

Michael Stack, K Cats Consulting 

Instructor in Computer Science at Northern 

Illinois University from 1982 - 2007, including 

assembler language, data structures (in 

assembler), and applied systems programming 

Available Materials 

Materials described in these two sessions, 

as well as the Assembler Boot Camp, can be 

found at http://www.kcats.org/share 

Yesterday's Agenda (Brief Review) 

Our First Macro Instruction 

The Second Version of Our ADD Macro 

The Macro Programming Language 

1-4

Today's Agenda 

Variable Symbols We Can Change 

A Bit More on Variable Symbols 

Finally, the Add Macro Instruction 

Wrap Up 

Variable Symbols 

We Can Change 

(So that's why they're called 

Set Symbols) 

Set Symbols 

Now that we have AIf and AGo to control 

the path of code generation, it will be very 

useful to have a way to keep assembly-time 

data 

Assembler variables which can hold this 

data are called set symbols, of which there 

are three data types 

Arithmetic 

Binary (logical) 

Character 

Set Symbol Scope 

As with high level languages, set symbol 

variables have the scope characteristic 

The value assigned to a local set symbol is 

known only within one macro expansion, 

and each expansion of that - or any other - 

macro has its own copy of that local variable 

The value assigned to a global set symbol is 

known throughout the assembly 

5-8

Set Symbol Declaration 

Modern assemblers do not require that local 

Set Symbols be declared before use (older 

assemblers do, though) 

But it's a good idea to declare (and globals 

require it), as it's a great place to document 

the purpose of the variable 

Declaration describes the variable as 

Local or Global 

Arithmetic, Binary, or Character 

Set Symbol Declaration 

To declare a local set symbol of type x 

(where x is A, B, or C): 

seq_sym Lclx var_sym 1 ,var_sym 2 ,... 

where seq_sym may be a sequence symbol 

and each var_sym n is a variable symbol 

To declare a global set symbol of type x: 

seq_sym Gblx var_sym 1 ,var_sym 2 ,... 

Although more than one set symbol can be 

declared in one statement, limiting to one 

leaves room for a descriptive comment 

Arithmetic Set Symbol Assignment 

The SetA instruction is used to assign a 

value to an arithmetic set symbol (from now 

on called a SetA symbol) 

var_sym SetA arithmetic_expression 

var_sym is a variable symbol and 

arithmetic_expression (as described earlier) 

is evaluated as a signed, 32-bit number 

The default (initial) value of a SetA symbol 

is zero 


Example 

Here is some sample code: 

LclA &S Counter 

LclA &Con Assigned "constant" 

&S SetA 3 Initial value 

&S SetA &S+1 Increment by 1 

&Con SetA 2*(1-&S) Set &Con to -6 

And here's a real oddity: when &Con 

(whose value now is -6) is used in a model 

statement, its absolute value is used: 

DC F'&Con' Generates 00000006 

(Don't ask) 

9-12


Example 

Here is some more sample code, this one to 

generate all of the register equates: 

Macro 

EQURegs 

GblA &EQURegs Recall if already done 

LclA &Reg Counter (initially 0) 

AIf (&EQURegs NE 0).Done 

&EQURegs SetA 1 Don't generate again 

.Loop ANOP 

R&Reg EQU &Reg 

&Reg SetA &Reg+1 Increment reg number 

AIf (&Reg LE 15).Loop 

.Done MEnd 


Example 

Here is the output (assembler source) from 

EQURegs (first time only!) 

EQURegs 

+R0 EQU 0 

+R1 EQU 1 

+R2 EQU 2 

+R3 EQU 3 

+R4 EQU 4 

... 

+R12 EQU 12 

+R13 EQU 13 

+R14 EQU 14 

+R15 EQU 15 


Example 

Here is a slightly different version of the 

same macro (loop test at top): 


EQURegs 

GblA &EQURegs Recall if already done 

LclA &Reg Counter (initially 0) 

AIf (&EQURegs NE 0).Done 

&EQURegs SetA 1 Don't generate again 

.Loop AIf (&Reg GT 15).Done 

R&Reg EQU &Reg 

&Reg SetA &Reg+1 Increment reg number 

AGo .Loop 

.Done MEnd 

Binary (Logical) Set Symbol 

Assignment 

The SetB instruction is used to assign a 

value to a binary set symbol (from now on 

called a SetB symbol) 

var_sym SetB binary_value 

var_sym is a variable symbol and 

binary_value (described in the next slide) is 

evaluated as a 0 or 1 

The default (initial) value of a SetB symbol is 

zero 

13-16


Assignment 

A full description of the binary_value 

operand of SetB is beyond the scope of 

these sessions; simplified, it can be one of 

A binary digit (0 or 1) 

A binary value enclosed in parentheses 

An arithmetic value enclosed in parentheses 

If the value is 0, the assembler assigns a 

value of 0 to the symbol in the name field; if 

the value is not 0, the assembler assigns a 

value of 1 

A logical expression enclosed in parentheses 


Assignment Examples 

Each &X starts with initial &A, &B, & &C 

&A SetA 4 

&B SetB 1 (Note no parentheses) 

&C SetC 'XYZ' (This is a preview of SetC!) 

* 

&X SetB (&B) &X = ? 

&X SetB (NOT &B) &X = ? 

&X SetB (&A LE 15) &X = ? 

&X SetB ('&C' EQ 'XYZ') &X = ? 

&X SetB ((NOT &B) AND (&A LT 15)) &X = ? 

&X SetB ((&A GT 0) AND (&A LT 15)) &X = ? 

&X SetB (&B OR ('&C' EQ 'YES')) &X = ? 

&X SetB (&B AND NOT (&A GT 5)) &X = ? 

Character Set Symbol 

Assignment 

The SetC instruction is used to assign a 

value to a character set symbol (from now 

on called a SetC symbol) 

var_sym SetC 'character_string' note quotes! 

character_string is a sequence of characters 

and variable symbols (followed by '.' for 

concatenation) interpreted as characters 

The initial value of a SetC symbol is the null 

string 

Character Set Symbol 

Assignment Examples 

Here is a SetC example: 

&A SetA 4 

&B SetB 1 

&C SetC 'XYZ' 

* 

&X SetC 'A&A.B&B.C&C.' &X = ? 

&X evaluates to the string A4B1CXYZ 

Note that the arithmetic and binary values 

have been converted to character values 

(See Concatenation in the next section) 

17-20

Substrings of SetC Symbols 

Definition 

SetC operands can also be substrings by 

placing two arithmetic expressions, 

separated by commas and enclosed in 

parentheses, immediately following the 

character expression 

The first arithmetic expression identifies the 

first character of the substring 

The second arithmetic expression gives the 

length of the substring 

Substrings of SetC Symbols 

Examples 

'ABCDEF'(3,2) evaluates to 'CD' 

If &VAR evaluates to 2 and &STR evaluates 

to 'ABCD' then '&STR.%'(2,&VAR*2) 

evaluates to 'BCD%' 

'AB'.'CD'.'EFG'(1,2).'H' evaluates 

to 'ABCDEFH' 

(For . see concatenation in the next section) 

Meeting 

in 

Progress 

A Bit More on 

Variable Symbols 

Then we can really go to work! 

Concatenation 

Concatenation can sometimes be without 

ambiguity 

&this&that (variable.variable) 

this&that (ordinary.variable) 

Others are a problem 

&thisthat (variable.ordinary intended) 

We use the concatenation operator '.' to 

avoid the ambiguity 

&this.that 

21-24

Symbolic Parameter Sublists 

A single macro operand can be a list of 

elements, called a sublist, with one or more 

items enclosed in parentheses and 

separated by commas 

(X,2,Y) 

An individual sublist item can be referred to 

by a subscripted symbolic parameter, so if 

&ABC has the value (W,15) 

&ABC(1) has the value W 

&ABC(2) has the value 15 

But &ABC.(1) has the value (W,15)(1) 

Keyword Symbolic Parameters 

Macro prototype statements may have 

keyword operands as well as positional 

These are coded on the prototype as 

&Keyword=[default] 

The default value is optional 

The advantages of keyword parameters are 

They can have a default value 

They can be coded in any order when invoked 

But positionals look more like operands 

System Variable Symbols 

The third kind of variable symbol after 

symbolic parameters and set symbols is the 

set of system variable symbols 

These all begin with &SYS so this prefix 

should be avoided in programmer-created 

variable symbols 

Some popular examples 

&SYSTIME - time of the assembly 

&SYSDATC - Y2K-compliant date of assembly 

&SYSNDX - (see the following slides) 

System Variable Symbol &SYSNDX 

Here is a macro - what's its problem? 


&name AddVal &num,&val 

.* 

.* Macro to add &val to &num 

.* 

L 0,&num 

A 0,FWrd 

ST 0,&num 

B FWrd+4 

FWrd DC F'&val' 

MEnd 

25-28


The way it's written, it can be used only 

once in an assembly (because of FWrd) 

We can fix this by concatenating &SYSNDX 

&SYSNDX has a new value assigned by the 

assembler each time a macro is called 

For the first macro, &SYSNDX is 0001 

It increases by 1 for any macro invocation 

Until it goes past 9999, it is four characters 

This can provide unique labels for macros 


Here is the macro rewritten using &SYSNDX 


&name Add1 &num,&val 

.* 

.* Macro to add &val to &num 

.* 

L 0,&num 

A 0,FWrd&SYSNDX 

ST 0,&num 

B FWrd&SYSNDX+4 

FWrd&SYSNDX DC F'&val' 

MEnd 

Attributes of Symbols 

As should be expected in a HLL (!) like 

assembler, symbols have attributes 

We will be concerned with only three 

Type, which distinguishes one form of named 

object from another, such as character data 

from binary data 

Count, which gives the number of characters 

required to represent the data as a character 

string 

Number, which gives the number of sublist 

entries in a macro instruction operand 

Attributes of Symbols 

We can refer to these attributes inside 

macro instructions by using a single letter 

followed by a single quote: T' K' and N' 

For example in the Add1 macro 

T'FWrd&SYSNDX is F 

And if we invoke as Add1 F4,18 then 

K'&num is 2 

N'&num is 1 

We will see more in the next slides 

29-32

Finally, The Add 

Macro Instruction 

In which we analyze and 

demonstrate an overloaded Add 

Add Macro Definition: 

Prototype and Doc Box 1 


&Name Add &List,&Sum,&R=1,&WKR=0 

.******************************************************************** 

.* 

.* Function: 

.* This macro generates assembler instructions to add multiple 

.* values held in storage as fullword, halfword, and packed data. 

.* The first operand is a sublist of the labels on the numbers 

.* to be added. The sum will be returned in register R= as a 

.* binary value. Optionally, the sum may be returned in storage 

.* at the location given by the second operand, which must be of 

.* the fullword, halfword, or packed data type. Instructions 

.* will be generated appropriate to the data types. 

.* 

.* Prototype Statement: 

.* &Name Add &List,&Sum,&R=1,&WKR=0 

.* 



.* 

.* Symbolic Parameters: 

.* &List is a sublist of the values to be added, consisting of 

.* labels of storage areas of types F, H, and P (required) 

.* &Sum is a label of type F, H or P and is the calculated sum 

.* (optional) 

.* &R= is the sum accumulation register; it is required and 

.* must be different from &WKR=; &R always has the result 

.* &WKR= is a scratch register for CVB and CVD instructions in 

.* case the sum or any summand is type P (required if any 

.* binarydecimal conversion is necessary) 

.* 

.* Error Conditions: 

.* Missing summand sublist (8) 

.* Incorrect sum or summand type (4) 

.* 



.* 

.* Notes: 

.* Two registers are altered and not saved. By default these 

.* are R0 and R1. 

.* 

.* This exercise and solution are patterned after the ADD macro 

.* in _Assembler Language Programming for the IBM 370, ASSIST 

.* Edition_, by Frank M. Carrano, p. 18.34 

.* 

.******************************************************************** 

.* 

33-36


Set Symbol Declaration & Init 

.* 

.* Define and initialize local set symbols 

.* 

LclA &J &List loop counter 

LclB &P 1 if decimal summand seen, else 0 

LclC &A Current binary operation (L or A) 

LclC &DEC Current decimal op (ZAP or AP) 

LclC &H 'H' if LH or AH, '' if L or A 

LclC &D Unique label for work area 

LclC &NM &Name for flexibility in use 

.* 

&J SetA 1 Start with first summand 

&P SetB 0 No decimal summands yet 

&A SetC 'L' First time use L, then A 

&DEC SetC 'ZAP' First time use ZAP, then AP 

&H SetC '' Set to 'H' if binary is halfword 

&D SetC 'DWrd&SYSNDX' Unique label for D work area 

&NM SetC '&Name' &NM can be cleared, &Name cannot 

.* 


Initial Check, Main Loop 

.* 

.* Sublist &List is required - quit if not present, CC=8 

.* 

AIf (K'&List NE 0).Loop 

MNote 8,'** Error: Required list of summands missing ***' 

MExit , 

.* 

.* Begin loop to process summands 

.* 

.Loop AIf (T'&List(&J) EQ 'P').Decimal 

AIf (T'&List(&J) EQ 'F').FullBin 

AIf (T'&List(&J) EQ 'H').HalfBin 

MNote 4,'** Warning: Invalid summand type - &List(&J) **' 

&J SetA &J+1 Increment loop counter 

AIf (&J LE N'&List).Loop Continue if more summands 

AGo .EndList Else done with list 

.* 


Process Binary and Decimal 

.* 

.* Process binary load or add, either halfword or fullword 

.* 

.HalfBin ANOP , 

&H SetC 'H' 

.FullBin ANOP , 

&NM &A&H &R,&List(&J) Increment binary part of sum 

&A SetC 'A' Use A after first L 

&H SetC '' and set fullword default 

AGO .LoopEnd Continue 

.* 

.* Process decimal zero and add, or add 

.* 

.Decimal ANOP , 

&NM &DEC &D,&List(&J) Increment decimal part of sum 

&DEC SetC 'AP' Use AP after first ZAP 

&P SetB 1 We have seen a decimal summand 

.* 

.LoopEnd ANOP , 


Add Dec Summand, Dec Result 

.* 

.* Bottom of loop - check if any more summands 

.* 

&J SetA &J+1 Increment loop counter 

&NM SetC '' Clear &NAME holder after first use 

AIf (&J LE N'&List).Loop Continue if more summands 

.* 

.* All summands processed - if any were dec, get binary of their sum 

.* 

.EndList AIf (NOT &P).NoDSum Skip if no decimal summand 

CVB &WKR,&D Get binary sum of decimal summands 

&A.R &R,&WKR Add to sum of binary summands 

.* 

.* If the result is to be decimal, convert result to dec, then save 

.* 

.NoDSum AIf (T'&Sum EQ 'O').CKD If omitted, don't save result 

AIf (T'&Sum NE 'P').NoDRes Skip if no decimal result 

CVD &R,&D Get decimal sum of summands 

ZAP &Sum,&D Copy to target 

AGO .CKD Go generate DWORD 

37-40


Store Result, Gen Temp Storage 

.* 

.* If the result is to be binary, save as halfword or fullword 

.* 

.NoDRes AIf (T'&Sum EQ 'F').SaveSum 

AIf (T'&Sum EQ 'H').HalfSum 

MNOTE 4,'** Warning: Invalid sum type - &Sum **' 

AGO .CKD Bad type, don't save sum 

.HalfSum ANOP , 

&H SetC 'H' 

.SaveSum ST&H &R,&Sum Save result 

.* 

.* If any decimal summands or result, generate scratch doubleword 

.* 

.CKD AIf (T'&Sum NE 'P' AND NOT &P).MEnd 

B &D+8 Branch around doubleword 

&D DS D Scratch area 

.* 

.MEnd MEnd 

Add Macro Output: 

Example 1 

This is similar to the code in ADD2, except 

that this uses the RX add instead of RR (A 

instead of AR) 

* 

Add (Word1,Word2),Word3 

+ L 1,Word1 Increment binary part of sum 

+ A 1,Word2 Increment binary part of sum 

+ ST 1,Word3 Save result 

... 

* 

Word1 DC F'4' 

Word2 DC F'6' 

Word3 DS F 

* 

Add Macro Output: 

Example 2 

AddDemo Add (One,Two,Three,Two,Three,One),Three 

+AddDemo L 1,One Increment binary part of sum 

+ AH 1,Two Increment binary part of sum 

+ ZAP DWrd0009,Three Increment decimal part of sum 

+ AH 1,Two Increment binary part of sum 

+ AP DWrd0009,Three Increment decimal part of sum 

+ A 1,One Increment binary part of sum 

+ CVB 0,DWrd0009 Get binary sum of dec summands 

+ AR 1,0 Add to sum of binary summands 

+ CVD 1,DWrd0009 Get decimal sum of summands 

+ ZAP Three,DWrd0009 Copy to target 

+ B DWrd0009+8 Branch around doubleword 

+DWrd0009 DS D Scratch area 

... 

* 

One DC F'1' 

Two DC H'2' 

Three DC PL2'3' 

Wrap Up 

In Which We Learn That Only 

a Small Fraction of the Macro 

Language Has Been Covered 

41-44

Summary 

Two hours is just a start, but a good one 

For further information, John Ehrman often 

gives sessions at SHARE on advanced 

macro techniques: 'Assembler as a Higher 

Level Language' 

Basic Conditional Assembly and Macro 

Concepts 

Applied macro techniques 

Some of What Wasn't Covered 

Set symbols 

Subscripted set symbols and extended Set 

statements 

SetAF and SetCF 

Created set symbols 

Many data attributes (length, scaling, 

integer, etc.) 

Many system variable symbols 

&SYSLIST in particular 

Some of What Wasn't Covered 

Controlling macro expansion listing using 

PRINT GEN / NOGEN 

Defining macros within macros (!) 

Using macros to create job streams 

(SYSGEN) - important to understand SMP/E 

Using conditional assembly in open code 

(outside macros) 

Nevertheless... 

You now have a basic understanding of 

S/390 and z/OS assembler macro language 

You have seen what comprises a macro 

written in assembler language 

And you are ready, if you wish, to begin 

writing macros (the best way to learn) and 

go on to the next step 

So, ... 

45-48

Congratulations! 

49-52

Assembler Language Macro "Boot Camp" Part 2

Create successful ePaper yourself

Delete template?

Save as template?