Macro Instructions 25

tional operands that are written as fields of a character string. The character string itself, enclosed in apostrophes, or the address of the string in storage, may be written in the operand field. The manner in which the address may be specified may depend upon the macro form.

If the operand is presented as a character string, the macro expan-sion places i t in the assembled prcgram followed by an end-of-message code, and loads a pointer to the string in register 1. If the operand field specifies the address of the character string, the expansion places that address in register 1. In the latter case, the user ~ust

define the operands elsewhere in the program and provide an end-of-message code.

If the user wishes tc refer to and manipulate the operands in an operand string in coding, the address option of the operand is used, permitting the operand character string to be set up as a series of adjacent fields, each with its own label.

1be string must end with X"27', which serves as an end-of-message code. Any unused space in each of the adjacent fields in the string must be filled with blanks to the rr.aximum size of that field. Unlike other operand forms, all commas in an oplist operand must be coded, even if parameters are defaulted. EX! and EX2 show how each of the string and address options for the operand field are used; the two examples have the same effect.

EXl EX2

STRING OP2

MACRO MACRO

DC DC DC

'first operand,second operand' STRING

C'first operand' C·second operand' X'27'

Macro Description Notational Symbols: Notational symbols in the operand field of macro instruction descriptions assist the user in showing how, when, and where an operand should be written; these symbols are them-selves never written in the operand field. The notational symbols are:

vertical stroke,

I;

hyphen, -: braces, { }; brackets, [

J;

ellipSiS,

•••• and underscore,

1. Vertical stroke means "exclusive or." For example, AlE means that either the character A or the character B, but not both, may be written. Alternatives are also indicated by operands being aligned vertically, as sh01Nll in the next paragraph.

2. Braces denote grouping. They are used most often to group alterna-tive operands or alternaalterna-tive operand forms. For instance, the

fol-lowing two operand descriptions are equivalent:

{INPUTIOUTPUT}

{ INPUT} OUTPUT

3. Brackets denote options. Information enclosed in brackets may ei-ther be omitted or written in the macro instruction, depending on the servioe to be performed. In the following case, the operand of the EXAMPLE macro instruction is optional and need not be supplied.

26

Page of GC28-2004-6 Revised 9 May 1979 By TNL GN20-3941

" - - - ,

INane IOperationIO~~ranJ I

1 - - - + - - - + - - - -- - - 1 I [syrcbol ] I EXA::PLE I [mode

1

_ _ _ _ _ _ _ _ _ _ _ _ ---1 I

~. An ellipsis denote~ that the preceiina Ey~tactical unit can be repeated one or more ti~e3 in s~ccessi0n. If the syntactical unit consists of one terB, i t is follo .... e,1 by a comma dId. an ellifOsis;

for: example.

dcb addre:o.s, .••

ir~icates that the ter3 lcb aljress can be reoeated, with a con~a

separating each tprru from the succee~inq term, but with no COILa

after the last ter~.

If the syntactical unit to be repeate~ consists of ~ora t~3n one ter., i t is encloEai i~ braces to indicate the terms that iliay tA repeated, and the COIDma anl e1iosis are placed outside t~p braces;

for exalbPle;

(dct aidress ,optior>} , •••

inlicates that ~cb ad~ress,option Cdn be repeatal with con~dS

f'epardtina ~ii..:::h taLm. ~o ':Olll;l-.a is place:!. after the la~t ten].

5. UD\.--,"rca2e (cari tal) le-r:te"':"s 5_n1icate the oortion of the operanil that Jiust be writt2n e;::act1.y as shown.

6. Lowercase letterF in~icate the po=tion of the ouerand that is to ~e

replaced by a permissitle value. The zacro ~0scription will sneci-fy tile permissible values. Forexa~ole:

spacing

SpecifieJ a:o.: 1 or 2 length

Specified as: A relocatable expression, or register nota-tion (2 through 12).

In the first example, eitber 1 or 2 may be coded as the complAtA operand. In the seconi operand, 'length' could Le replaced by

~SGLE~ (a relocatable expression). or by (3) as the complete operand.

7. Co~mas and parentheses ~ust be written as shown in an operand field. They are deliffiiters, not notational sy&bols.

'the macro descriptions soecify the for:n in Which each operand may be written.

For the macro instruction descriptions in this publication, each positional operand is soecifiej by a meaning:ul name or phrase, as illustrated:

Part 2: r.acro Instructions 27

'[sy~bol)I~X~~DLP Idcb address

L - -_______ ^~ ____ __ - L - - - - -_ _ _ _ _ _ _

Each keyword operani is sp0cifieJ by the knyvord, a~ eoual sian, ani a

k2anicq~Jl name or phrase, as illustrated:

, i -,

IKame IO?erationlOoerand

,

j---+---+-IDSNA!E=na~e of ~ata set

~

,

_ _ _ _ _ _ - J

In describing the ^ma~ner in which an oDerand may be specified, the fo:lowing ter3S Ray be use~.

Relocatable £xoression: A relocatable eXDression reoresents the name assianea -to a Eipl'1 that ~Fty be relocate,~ within vir"Cllal stor'llJe 'lurina proqram qxec~tion. (In contrast, an absolute exoression repre~ents a -fiel~ that ray not he so reloc'Ited.) the val~e ~f a relocaiable expres-sion change~; by n i f the proqrdlU i1' \thich i t d1JpearS is relocated n bytps frOID its oriainally a~siqneJ storaqe area. All relocatable

ex-~reEsions nust have positive v~laes. A r~locatable exuression ~ay be a sinale relocatable ter:. AlEO. a reloca"Cable expression may contain mUltiple relocatable t~rms, or a combination of relocatable terms yith absolute ~erBS, unier these coniitions:

1. The expression must contain an ode! nurr.ber of relocatable terms.

All reiocatabie ~erms except one must be paired; palrina is Je-scribed later in "Absolute Exoression."

3. Ihe unDaire~ tprm ~ust not be ~irectly preceded by a ~inus sign.

4. A relocatable term must not enter into a multiply or divide

o~eration.

A relocatable expression reluces to a single relocatable value, vhich is tne value of the odd relocatable tern adjusted by the values reore-senteQ by the ahsolute t;e':~5 or pairee relocatable ter3S associatei with it.. The re:ocatatility attribute is that of the oid relocatable ter]!'.

C0ffiPlex relocatable expressions are oermitted (refer to Assembler Lag.9: ua.9:§:l .

In the !ollGwing e~anple~ of relocatable expressions, SAM, JOE, an~

FRAN~ are i~ the sallie control section and are relocatable; PT is absolute.

SAM

SAM-JOE+FF.ANK JOE-PT*5 S1I.1'l+3

Note that SAM-JOE is not relocatable, because the difference between two relocatable addr~sses is constant.

Rg.9:ister_~ot£iioQ: This is written as an absolute expression enclosed in parentheses. The absolute ex~ression, vhen evaluated, must be SOIe value 2 through 12, indicating the corresponding general purpose regis-ter. In t~ese examples of reqister notation, SAM and JOE are relocat-able and have the sane relocatability attribute and .PAL is absolute:

28

(5)

{PAL}

(PAL+3) (SAM-JOE)

-indicates register 5 -invalid

Page of GC28-2004-6 Revised 9 May 1979 By TNL GN20-3941

The absolute expression (SAM-JOE) is invalid because i t contains oaired relocatable terms. See !Q~olute~£ession below.

When register notation is used for an operand, the indicated register must be loaded with the de£ired value before execution of the macro in-struction. No register other than those stated as being permissible should be specified; the integrity of other registers cannot be relied upon. See "Using Parameter Registers" under R-Type Macro Instructions below.

HX Address:

(l)may-be exnlicit, written in the same form as an assembler language operand:

a (b ,c)

• • •

I I I

I

base register I index register I

displacement ExaJlljJles are:

2 (0,5) 0(2,4)

(2) may De implied (iniexed), written as a symhol, optionally indexed by an index register. For example:

r-r;l-I'IAL ALPMAY (4)

aote that ALPr.AY is indexed by register 4.

11mbol: 'this may he a symbolic address (that is, a single relocata:,le term), such as the symbolic name of an iastruction in an assembler lan-guage progra~, or i t may be a cbaracter string use~ for i1entificatiop, not location (such as the daname parameter of a DCB macro instcuction) .

In TSS, the alphabetic characters are the letters A-Z, pluF 1,

ro,

^~:

the alphameric characters are the alphabetic characters plus the diqits 0-9.

The symbol is ~ritten as a strinq of as many as eiqh~ alnhallieric char-acters, the first of which is alphabetic. ~mbedded commas a~J blanks are not permitted. Symhols beginning with the characters CHD anJ SYS may not be used, since symbols beqinning with those characters are reserved for system use. Examnles of symbols are:

!)c)NA~El

ROGER LOOP12 3TJI_r.T 1f1

l:{umber: Unless stated ot:vO!rwise, this will in!')ly a decima: inteoer.

~art 2: Macro Instructions 29

between absolute terms. An absolute expression may contain relocatable terms alone or in combination with absolute terms, provided that these conditions are met:

1 • . The expression must contain an even number of relocatable terms.

2. The relocatable terms must be paired.

3. Each pair of terms must have the same relocatability attribute;

that is, they must appear in the same control section of an assembly.

4. Each pair must consist of terms with opposite signs. The oaired terms do not need to be adjacent; for example, PT+AT-ST, where RT and 5T are relocatable with the same relocatability attribute and AT is absolute.

5. A relocatable term must not enter into a multiply or divide o?eration.

Pairing of relocatable terms (with oODosite signs and the same relo-catability attribute) cancels the effect of relocation. The value rep-resented by the paired terms remains constant, regardless of progra~ re-location. It should be noted that absolute expressions composed of l>ai:ced relocatable terms shoul.1 not be usei. as mac:co operands since the attempt by a macro ~efi~ition to u~e them in an AIF, SETA and SPTB will result in an error. The assembler does not assign location counter values to relocatable terms until all macro expansions are complete,l.

Example: In the absolut~ ex~r.ession A-Y+X, the term A is absolute, and the te:cms X and Yare relocatable with the same relocatability attribute. If A equals 50, Y equals 25, ani X equals 10, the value of the exp:cef;sio!l becomes 35. If X and Yare relocatei by a factor of 100, their values become 125 and 110. Howeve:c, the expression still evalu-ates as 35 (50-125+110=35).

An absolute expression reduces to a sinqle absolute value.

In these examples of ab~olute expressions, ^JOE and SAM are :celocat-able and defined in the same control section; 3ERNY and DAVE are absolute:

331 DAVE

3EI-NY+DAVl'!-83 JOE-::..:""l

DAVZ*4+bER~Y

Q~£~.2~£_NaD§:: this is tner.ame of one cla ta set or a group of ~3.ta

sets. lh~ rules for writin~ data set names are presented belo~; the types oi na~es that ~ay be written for each macro instruction are iden-tlfied unler the description of each macro instruction.

30

Fully aualified narue uni~uely identifies one data set.

1. A stand-alone data set name identifies a data set that is not a member of a oartifioned eata set no:c a qeneration of a aeneration uata group. ^~he name of a stanj-alone data set is written as a series of svrrcbols seDarate'l by periols. For example:

D~TASET.TFIAL.TESTl TEFI.POG~P.LAURIE

A.B

.c

Page of GC28-2004-6 Revised 9 May 1979 By TNL GN20-3941 Ihe rightmost sy~bol is the data set's simple name (TEST1,

LAURIE, and C above); the other syobols are qualifiers. In 'I.'55,

for cataloQing purpo~e~, the maxi~u~ number of characters in a data set name, including aeriods, is 35. The maximum number of

one-charac~er qualifiers for a one-ch~racter name is 17.

Nute: Data set names crea~ed un3er the IBM OS, or OS/VS SYstem can contain a maximu!.! of 44 characters; if ::ata sets with na!"ps greater than 35 characters are to be cataloqeJ in TSS, the user should em~loy the renami~g facility of the CAT macro instruction or CATALOG comman1 to define a suitable TSS name.

2. Partitioned Data Set and ~ember lame ide~ti~ies a data set that combines individual data sets, callail merub.~rs, into a sinql'~ :lata set. ~he partitione~ organization allows the user to refer to either the entire data set or to an in~ividual member of the data set •

• The rules for writing the name of a partitioned data set are the same as for vritincr the name of a stand-alone data set.

The parentheses and mRmber namq are merely considered as an appendacre to that na~e •

• Th~ rules for writinq a mem~er name vary with each macro in-ztruction that can manipulate members. sometimes (as in LOAD

an~ D~LFT~) only t~e simple me~ber name (a sy~bol) is written.

The full name is not required because the user ~as in1irectly defined the partitione,'!. data set (library) in which the module resides by assurinq that the library is on the progrilf.l library list prim: to issuincr those corr.manis. The user could write

LOAD SORTJi

if he has ~reviously entered SORTR in a library currently on the program library list.

In other macro instructions (for example, COPYDS), the user must give the fully oualified member na~e. This consist~ of the name of the aartitioned data set suf!ixed by the simple member name in parentheses. Por example:

HQW (ONETRY)

G.R.AB (H)

Here HQw and G.3.AB are partitioned data sets with merrbers OlETRY and H, respectively.

3. ~eneration Names identify data set3 which are part of a genera-tion data group. These data sets can be =eferred to on an abso-iute or relative basis:

a. Abso~ute Generation ~ames are ~ritten as the name of the generation data groua followed by a period and the characters bXXXXVyy, where xxxx is a four-digit decimal generation num-her, and yy is a two-digit decimal version number. Por example:

HURST.LI~ER.TT~G0001VOO

HJ.LA4.WW.G0003VOl HARQ.G0147V03

The characters GxxxxVyy are considered a fixed part of the overall name. The name of the generation data group (for ex-ample, HURST.LINER.TT) is a partially oualified name applica-ble to all generations in the group.

Part 2: Macro Instructions 31

If the qen~ra~ion is a partitioned data set, a mellibar (for ex-am?le, JOE) within t~at data set is referred to as follows:

A.5.C.GxxxxYyy(JO~)

h. Relative Generation lames are written as the name of the aeneration data aroup followed by the appropriate relativE generation number ~nclosed in oarentheses, such as:

G .D.G (0)

1he relative qeneration number of the most recent generation is (0); the generation just prior to that is (-1); the one be-:tore that is (-2), etc.; and a new generation to be added is

{+ 1}. For example:

bOST.U~.L19P(+1)

GOS'l.UU.L19P (-3)

I'RQ.'I.15.SiiII' (0)

If the generation is a partitioned data set, a member within that d3ta set is ref~r~e1 to as follows:

SEr.T (-3) (JOB)

whera JOE is the member in question.

Partia:ly Quali~ied ~ames refer to al: data sets having a given par-tially qualified name as their common higher-order qualifier.

1. Generation Data Grouu ~ame is th~ name that is common to each generation in the group. Generation data group names a:::p re-stricted to a maximu~ of 26 characters including periods.

2. Otner~££tiallY-Q~£lifipd-E£~g~ can also he use! to refer to two or ~ore Jata sets. For example, the oartially aualified name

~0.A~14 can ~e used to refer to bot~ of the followiLg data sets:

GO.AB14.A anj GO.AB14.B. If these were the only two of a user'R data sets with the same higher-order qualifier, GO.AB14, and he

wis~ea to erase then both, he could do so merely by specifying GO.A514 in the ERASE macro instruction.

Alphameric Characters: An alphameric-character operand is written as a 5trinq of alphameric characters, the first of which need not be alpha-betic. For example:

Au0764 10EO:)4

The limit on the nUlliber of characters is given in the description of each macro instruction in which i t is used.

TYPES OF MACRO INSTRUCTIONS

Most system macro instructions are either F-type (register) or s-type (storage). In this publication, the letter (R) or (5) follows the name of each macro instruction description to identify its type; macro in-structiolls that are neither B- nor s-type, referred to as "other" type macro instructions, are identifiel by (0).

Some macro instructions generate literals in their e~ansions. Conse-quently, the rules for literal pool coverage must be £olloved. Refer to Assembler Language, Section 2, "Terms and Expressions." Parameters can be contained in the two parameter registers, 0 and 1.

32

Page of GC28-2004-6 Revised 9 May 1979 By TNL GN20-3941 An R-type macro instruct~on does not generate a parameter list; the parameters are placed in the parameter registers by instructions in the macro expansions. Execution time can be sav2d i f the user places the data in the oarameter registers before executing an R-type macro in-struction, and uses register notation to specify the operands in the macro instruction.

Address operands in B-type macro instructions are always specified as an RX address, or in register notation. This arrangemen~ allows the user to employ indexinq, although the a1dresses passed in B-type macro instructions must be oroperly covered; t;iat is, the base register used for the passed address must contain the proner value to ensure that the address refers to the desired location in virtual storage. For eX.3.mple, assume an R-tyoe macro instruction, RTYPE, vhich will contain an address

"area" in register 1 anl the "length" of that area in register O. Its external macro description vould be:

I

---,

IName loperationlOperanJ

,

~---~I~---+I---I[sYllibolJ IRTYPE larea,lenqth --I

I area

specifies an a~dre~s.

~ecified-E§: Peqistec notation (1 th~o~gh 12), in which 8ase the address must be place~ in the register before ~x~cution o~ the macro instruction; an fX a~dress

length

specifies a length.

J

~ecifie~-E§: Register notation (0 or 2 thrOUqL 12), in which case the l~nqth must be placed in the reaister befo~~ execution of the macro instruction; or an absolute eXQression.

g§in~~££~ier_Regi~te~E: The user's ?roblem prOqr2m might ~e written so that one or both of the ~arameters are already in the proDer ?ararne-ter regis?ararne-ter when the macro instruction is issued. In this care, (l) or

(0) is written as the o?erand. Registers 1 and 0 cannet be ~s,,·'1 in "-macro iLstruction unless their use is Mentioned in the "Specitie2 as"

paraqraph for the operanJ.

S-TYDe ~acro Instructions

An s-type (storaqe) macro instruction iE used when the nu~her of parameters to be passed to the cal:ed routine cannot De contained in t~e

two ~arameter registers. T~ese paraEe~ars are place? in a para~eter

Ilst vhose aidre~s is passei to the callg} ~oQtine in reaister 1.

There are t~ree ~orms o! the S-tyoe macro instruction:

1. The standard Form (in ~hich the Ul= onarani i~ iefaulte!)

2. The L-lvrf'l (parameter :ist only - specifiPG as I'F=L)

3. T~e I-iorE (executahle cole only - specifieJ as KF=F)

S-'1:1D ]:;, S7A.l;:;~b~ FOFf.: 'l'his for::! 0-': macro ins.tructiG:l q"!n»rClt"s bot;:

the paraLeter l i s t require] by t~e callp~ routine and th~ linkaae to that routin8. If the S-tyoe macro ins~ruction is cod?~ in a mc:ule that has a PS~CT the paraseter list is generatal in the PSECT. In this case, the ~ ECT ~ust be pro~erly covered tv a hase reaister. If an s-type macrG nstruction is codeJ in a PSECT, or if i t is COdAJ i~ ~iA

?art 2: ~~cro In~tructions

Address operands in s-type standard form macro instructions are always specified as register notation or a relocatable expression.

Hence, they may not be indexen, and the user's problem program does not need to provide cover registers. As an exauple, assume an s-type macro instruction, STYPE, that exuects the a1dr:esses of two storage- areas,

"input" and "output," a!lcI the "l"!ngt~l" of those areas. Its external macro description might be:

---,

I!a~e IOperationloperane

1---+---+

l[sy.bol]ISTY~E linput,ont?Qt,length inpllt

l[sy.bol]ISTY~E linput,ont?Qt,length inpllt

Dans le document Macro Instructions (Page 29-60)