- Absolute Ref
1.9.4 ASSEMBLER DIRECTIVES: OVERVIEW
1.9.4.3 MACRO FACILITY DIRECTIVES,
A macro is a named section of text that can be defined once and repeated in other plac~s simply by using its name. The text of the
macro may be parameterized, so th.::1t each invocation results in a different version of the mac~o contents.
At the invocation point, the macro name is followed by a list of parameters which are delimited by commas (except for the last one, which is terminated by end of line or th~ comment indication
( ' i ' ) >. At invocation time, the text of the macro is inserted
(conceptually speaking) by the assembler after being modified by
parameter substitution. Whenever i.n (where n is a single decimal digit greater that zero) occurs in the macro d~'inition, the text aftha nth parameter is substituted. Leading afid trailing blanks are stripped from the parameter before the substitution. If a reference occurs in
th~ macro definition to a parameter not provided in a particular invocation, a null string is substituted.
A macro definition may not contain another macro definition. A
d e of i nit ion can c e r t a i n 1 Y I h owe v e r l i n c 1 u d Po ma c r 0 in v 0 cat ion s . T h i 5
"nesting" of macro invocations is limited to five levels deep.
The expanded macro is always included in the listing file (if listing is enabled at the pOint of invocation). Macro expansion text i s f loa 9 9 e d l i n the lis tin 9 , b y a ' #' JUs t i e f t 0 f e a c hex pan de d line.
Comments occurring in the macro definition are not repeated in the expansion .
. MACRO Indicates the start of a macro and gives it an identifier .
. ENDM
Page 110
Indicates the end point of a MACRO .
FORM:
EXAMPLE:
. MACRO <identifier>
(ma.c1"'O body) . ENDM
. MACRO HELP STA 'X1
LDA %2
. ENDM
-( comment :>
<: comment :>
The listing where the macro call is made may look like:
1.9.4.4
HELP FIRST. SECOND
51"1'.,.
LDA
FIRST SECOND
The 5tatem~nt HELP, calls th~ macro and ~ends i t two
parameters. FIRST and SECOND. These parameters are in turn referenced inside the macro using the identifiers Xi for the
va~iable FIRST, and 1.2 for the variable SECOND.
CONDITIONAL ASSEMBLY DIRECTIVES
Conditionals are used to selectively exclude or include
sections of cod~ at a$sembly time. When the assembler encounters an . IF directive, i t evaluates the associated expression. In the simplest case, if th~ ~xr~eSSiD" is falsel the assemble~ simply di5ca~ds the
text !.inti 1:~ E!\!D( 1.·E 'if~.'Elrhert If· there is ,~n ELSE direr.:tivp. bet{z.!fH~n
t h flo
r
Fan d . ENOC d .1 T' ~ c t: :i \l i~ S i t h e t ext b ~p 0 'r ~ the . ELSE i os s e 1 e r. ted i fthf~ s'q)T't:s<;;, on is t1'U€~. mnd the t~xt !3ftr~T' the ELSE if! the condition is false The unassembled part of the condition~l will not be included
Conciitjonals may b~ nested.
Th~ condit tiJn~l ff'XPT8Sision ti!j~(e~~ one of tldO fOT'ms. The first is the no~mbl a~ithm.tic/logical expres~ion used elsewhere in the assembler. This typm of exp~essicn is considered false if it
ev~luAte~ tn zerOi true othe~wise. The second farm of conditional
expr-E'SSlOn is COmf.H~·r'j,son for' equality or inequality (indicated by '=1 and ' . "~.: ~ r e ~;q) i? C t i \/ ely '- 0 n € !(i~;~ ~J C. 0 m paT' B 5 t r i n 9 s • c h a rae t e -r' S t Of' a~tthmRttc!logical expressions.
· IF
· ENDC
· ELSE
ldentlfias the beglnning of the conditional_
Identif.:ies th~ alte-rn3te to t h e . IF. If -the conditionall
exp~ession is egual to 0 then the else is used.
FORM: [lr.ibel] IF <expr~ssion>
. ELSE (* only i f there is an else *)
. ENDC
Page i i i
1.9.4.5
where the expression is the conditional expression to be met.
EXAMPLE: · IF LABELI-LABEL2 iarithmetic exp~ession
This text assembled only if subtraction result is now zero
IF "%1" ;:::"STUFF!I icomparison expression This text assembled if subtraction above was true and if text of first parameter
(assume we a~e in macro ) is equal to "STUFF"
.ENDC iterminate nested condo
· ELSE
This text assembled if subtraction result
i was zero
· EN DC iterminate outer level
iconditional
PASCAL HOST COMMUNICATION DIRECTIVES
The di~ective5 .CONST, . PUBLIC, and . PRIVATE allow the sharing of information and data space between an assembly routine and a Pascal host. These external referenc.es must eventually be resolved by the Linker. Refer to Section 1.8 Linker, for further details.
.CONST
. PUBLIC
Page 112
Allows access o~ globally declared constants in the PASCAL host by the assembly routine . . CaNST can only be used in a program to replace 16 bit relocatable obJects.
FORM: ,CONST <i d 1 is t)·
EXAMPL.E:
<*
see example after . PRIVATE *)Allows a va~iable declared in the global data segment o~
the PASCAL host to be used by an assembly language routine and the host program.
FORM: .PUBLIC <idlist>
EXAMPLE:
<*
see example after . PRIVATE*>
.PRIVATE Allows va~iables of the assembly routine to be sto~ed in the global data segment and yet be inaccessable to the Pascal host.
These va~iables retain their values for the entire execution of
the p-rog-ram .
FORM: . PRIVATE <identifier: integer list>
the integer is used to communicate the number of words to be allocated to the identifier.
EXl'~lPLE: (* for .CONST, . PRIVATE, . PUBLIC
*>
Given the following Pascal hast program:
PRO(~RAM EXAMPLEi
CONST SETSIZE=50; LENGTH=80i
VAR I,J.F/HOLD,COUNTER,LDC: INTEGER;
LST1:ARRAY[O .. 9J OF CHAR, BEGIN
END.
and the following section of an assembly routine:
_ CONST . PRIVt .. TE . PUBLIC
LENGTH
PRT .• LST2: 9 LDCI I I J
This will allow the canst LENGTH to be used in the assembly routine almost as if the line LENGTH. EGU
eo
had beenwritten. (Recall the limit~tinn mentioned above for the use . CONST identifiers. ) The vaT':i~3bles LOC, I. J to be used by both
'the Pase a 1 hO$ t and tile assemh 1 y~. outi ne, and the variables PRT, LST2 to be used only by the assembly routine. Furthe~,
the LST2:9 causes the va~iable LST2 to correspond with the b fl gin n i n goof a 9 tal 0 1" d b 1 () c~· 0 oF spa c e i n t h e 9 1
t.,
b a I d a ta segment"Page 113
1. 9. 4. 6
EXTERNAL REFERENCE DIRECTIVES
The use of . DEF and ~REF is similar to that of . PUBLIC . . DEFs and . REFs associate labels between assembly language routines rather than between an assembly routine and a Pascal host program. Just as with . PRIVATE and .PUBLIC~ these external references must eventually be resolved by the Linker. If such resolution cannot be accomplished, the Linker will indicate the offending label. Naturally! the assembler cannot be expected to flag these errors, since i t has no knowledge of other assemblies.
. DEF
. REF
· LIST
&
· NOL.IST
· PA(-1E
Identifies a label that is defined in the current routine and availabl~ to be used in other .PROCs or . FUNes.
FORfYi. .DEF <identifierlist>
EXAt1PLE:
<*
see listing in section 3.3.2.3 'O~ example *)Identifies a label used in this routine which has been declared in an external .PRQC or . FUNC with a .DEF.
During the linking proce$s~ corresponding .DEFs and .REFs
are rna t t: h e d .
FORM: . REF <identifierlist>
EXAMPLE:
<*
see listing in section 3.3.2.3 far example*'
Nate: The .PROC and th0 . FUNC directive also generates a . DEF l~ith the same ntune. This allows assembly procedures to call. PROC and . FUNes if they have been defined in a . REF.
LISTING CONTROL DIRECTIVES
Allow. selective listing of assembly routines.
If no Dutput file is declared then the default is CONSOLE:
when a . LIST is encDuntered. The . NOLIST is used to turn off the .LIST option. Listing may be turned on and off
rRpeatedl~ within an assembly.
FORM: , LIST 01" . NOLIST
Allows the programmer to explicitly ask for top of form page breaks in the listing.
i6 no ruUng ouitpld nile M ,t,pecJ..6ied then
au. .
LIST and .NOLISTdhc.e.c.Uvualte .6imply ignoJted.
. TITL.E
1, 9.4.8 . INCLUDE
FORM: . PAGE
Allows the titling of each page if desi~ed. The title may be up to 80 cha~acters in length. At the start of each procedure the title is set to blanks and must be T'eset· if title is desired"
The title;
INTERP SYMBOL TABLE DUMP
shown in S~ction 1.9.1 was caused by a . TITLE directive.
**
FORM . TITLE <:t i t 1 e:'-'"
where <tit}p> is a string EXAMPLE .1ITLE GRC12 interpreter
FILE. DIRECTIVES
Causes the indicatgd source file to be included at that point .
FORM: . INCLUDE <file identifier. TEXT> where the file
identifier is any file to be included. Only spaces are allowed between the end of the file name and the end o~ the Includ~ line .
CORRECT EXl\MPLE.: . INCLUDE SHORTSTART TEXT CORRECT EXAI'1PLE: . INCLUDE SHORTSTART.TEXT
i callo; starter
IN-CORRECT EXAMPLE: . INCLUDE SHORTSTART.TEXT calls starter
For a l i s t of gene~al errors and also notes on the
zao
and PDP-11 basedm /H~ h j !1 !'.'''! S :; p ;::, T.3 h 1 e 6.
**
Note:' The.ti:Ue iJ.> only c.£.eCVted a;t the -6.taJtt 06 .the {yUe. In -6 eetion 1.9. 1 the :ti.:tleSYMBOL TABLE DUMP Wa6 not f.:,et by a . TITLE cUJtec.:tive. That heading iJ.> a,fu)aY-6 tL6 ed on page!.> c.ontMMng f.:,ymboUabie dump-6. Upon M-6 emblinga 6wvthetL pJtoc.edwr.e the heading pJtinted JtetWtn6 to what i l WM f.:,et to be60Jte the -6ymboltabie dump.
Page 115
- Notes
-WARNING
Required parameters are listed along with the function/procedure identifier. Optional parameters are in [square bracketsJ. The default values for these are in {metabrackets} on the line below· them.
NOTE
Following a~e some definitions of terms used in these
documents. They tend to take th~ place of formal paTameter~ in the dummy declaration headers that preface each description of a particula~
routine, or set of routines,
SIZE SOURCE SCREEN STRING
TITLE
UN I TNllMBER
VOLID
BOOLEAN CHAR REAL STRING
or PACKED ARRA.Y[ .. ] OF CHAR
an INTEGER number ofbyte~ or characters; any integer
VJ..':jlup.
a STRING or PACKED ARRAY OF CHARacters to be used as a T'ead-only array, context d~pendent or as specified.
**
an array 9600 bytes long; or as needed.
any STRING, call-by-valuD unless otherwis. specified, i. e. may be a Q,lIoted stT'ing, or string val'iable or function which evaluates to a STRING
. a STRING con5t~ting of a file name
physical device number used to determine device handler used by the interpreter
a volume identifier, STRING[7J
**
i. e. in .6vung in.tJzA.n.6ieo, SOURCE i.6 go-Lng to have to be a .6;tJU,ng, -Ln A..nvun.6ieo that deal with pac.ked aJVLay.6 06 c.hafLac.telt-6, it may be eitheJt. A wOJtd 06 c.auUon about U6ing STRING.6 in {n:tJvtn.6ieothat expec.t c.ha.Jta.c.teJt aJVLay.6, the zeJtoethUement 06 :the .6.tJU.ng -fA the length byte, whic.h may c.aU6 e the pJtogJtammeJt .6ome unexpec.ted pJtoble.m6. (Wvr.e he not awMe 06 that 6ac.t!) ed.
Pqge 118
********************* *****************
*
STRING INTRINSICS* *
Section 2. 1. 1*
********************* *****************
Version l.S September 1978 FUNCTION LENGTH ( STRING ) : INTEGER
Returns the integer value of the length of the STRING.
Example:
GEESTRING := '1234567';
WR ITELN (LENGTH (GEESTR INC),' " LENGTH ( I , ) ) ;
Will print:
7 0
FUNCTION POS ( STRING I SOURCE ) : INTEGER
This function returns the position of the first occurrence of the pattern in SOURCE to be scanned. The INTEGER value of the position of the first cha~acter in the matched pattern will be returned; or if the pattern was not found, zero will be returned. Example:
STUFF := 'TAKE THE BOTTLE WITH A METAL CAP';
PATTERN := 'TAL';
WRITELN(POS(PATTERN,STUFF»;
Will p"rint:
26
FUNCTION CONCAT ( SOURCEs ) : STRING
There may be any number of source strings separated by commas.
ThislTunction returns a st~ing which is the concatenation oT
all the str-i.ngs passed to it. Ex.ample~
SHORTSTRING := 'THIS IS A STRING';
LONGSTRING :
=
'THIS IS A VERY LONG STRING. ' iLONGSTRING := CONCAT('START ',SHORTSTRING, ' - ' , LONGSTRINO)J WRITELN(LONGSTRING);
Will print:
START THIS IS A STRING-THIS IS A VERY LONG STRING.
Page 119
FUNCTION COpy ( SOURCE I INDEX I SIZE ) : STRING
This function return~ a st~ing containing SIZE characters copied from SOURCE starting at the INDEXth position in SOURCE.
Example:
TL := 'KEEP SOMETHING HERE';
WR ITELN (KEPT) i
Wi 11 print:
SOME.THING
KEPT
PROCEDURE DELETE ( DESTINATION , INDEX I SIZE )
COPV(TL,POS{'S',TL),9);
This procedure removes SIZE characters from DESTINATION starting at the INDEX specified. Example:
OVERSTUFFED:
=
'THIS STRING H~~S F.CtR TOO MANY CHARACTERS IN IT. ' j DELETE(OVERSTUFFEDJPOS('HAS',OVERSTUFFED)+3,8)~WRITELN(OVERSTlWFED);
Wj 11 print:
THIS STRING HAS MANY CHARACTERS IN IT.
PROCEDURE INSERT ( SOURCE I DESTINATION I INDEX
This inserts SOURCE into DESTINATION at the INDEXth position in DESTINr',T InN.
Example:
ID :
=
I INSERTIONS' IMORE := ' DEMONSTRATE';
DELETE (MORE, LENGTHCMORE) , l)i
INSERT O'iOREI ID. POS ( 'IO! 1 10) ) i
WRITELN( ID);
Will print:
INSERT DEMONSTRATIONS PROCEDURE STR ( LONG I DESTINATION )
Page 120
This converts thy lang integer LONG into a st~ing. The
~esulting string is placed in DESTINATION. See section 3.3.3 for mo~e
about the use of long integers.
Example~
INTLONG ;= 102039503;
STRCINTLONG,INTSTRING);
INSERT( '. ~ I INTSTRING, PRED(LENGTH( INTSTRING»);
WRITELN( '$', INTSTRING)i Will print:
$1020395.03
Note about using st~ing$ and st~ing functions:
In order to maintain the integrity of the LENGTH of a st~ing,
only st~ing functions or full string assignments should be used to
alter strings. Moves and/or single characte~ assignments do not affect the length of a string which means i t probab~ecome$ wrong. The
individual elements of STRING are of t~pe CHAR and may be indexed 1 .. LENGTH(STRINO). Accessing the string out~ide this range will have unpredictable ~e$ults if range-checking is off or cause a run-time error (1) if range checking is on.
Page 121
- Notes
-age 122
******************************* *****************
RESET (FILEID) witho~jt optional string parameter urewinds" the file by setting the -file pOinters back to the beginning (zero th
THESE ARE DANGEROUS INTRINSICS
[BLOCKNUMBER], [INTEGER] );
FUNCTION UNITBUSV ( UNITNUMBER ) : BOOLEAN;
This function returns a BOOLEAN value, indicating if TRUE that the device specified is waiting foT' an 110 transfer to complete.
Example:
UNITREAD(2{non-echoing keyboa~d}jCH[OJf
l{for one character}, {no block no.}, l{async:hronous},);
WHILE UNITBUSY(2){While the READ has not been completed} DO WRITELN(OUTPUT,'I am waiting for you to type something'};
WRITELN(OUTPUT, 'Thank you for typing a .. I CH[OJ)i
Execution of this example will continuously type out the line 'I am waiting far you to type something' until a character is struck on the keybo;:~T'd, Suppose a ' ! ' were tlJpedo The me'ssage 'Thank you foT' typing a · ' will then appear, and program execution will proceed
nOT'ma 11 y.
PROCEDURE UNITWf-\IT ( lINITNUMBER ) i
This waits for the sppci'ied d.vice to complete th~ 110 in
prog~es~. It can be simulated by:
WHILE UNITBUSV(n) DO {waste a small amount of time};
PROCEDURE UNITCLEAR ( UNITNUMBER );
UNITCLEAR cancels all IIOs to the spe~iFied unit and resets the hardware to its power-up state.
FUNCTION BLOCKREAD FUNCTION BLOCKWRITE
FILEID, ARRAY, BLOCKS.
FILEID, ARRAY, BLOCKS.
(RELBLOCKJ )
[RELBLOC~'{ J ) { sf'quential }
INTEGER~
INTEGER, These functions retu~n an INTEGER value e~ual to the number of blocks of data actll(~lly tT'ansferred. The FILE must be an untf,~ped file (1. e. F : FILE; ). T Ii f.\ 1 eng tho -f' AR R A V 5 h 0 U 1 d b e ani n t. e 9 Po r m u 1 tip 1 e 0 f
bytes-per-di~k-block. BLOCKS is the number o~ blocks you want
tran':;ft:>rr'ed. RElBLOC!, is the blocknomoC\;, reL:::"tive to the staT't 0; the file# the zeroeth block being the first block in the file. If no
RELBLOCK is specified, the reads/writes will be done sequentially. A random access 110 moves the file point~rs. CAUTION should be exercised when using thesel as the array bounds a~e nat heeded. EOF(FILEID)
becomes true when the last block in a file is read.
Page 124
Pf~GCE.DURE CLOSE ( FILEID OPTION ) i
OPTION may be null or " LOCK't or " NORMAL', or " PURGE', or
',CRUNCH', (Note the commas!)
If OPTION is null then a NORMAL close is done, i. e. CLOSE simply sets the file state to closed. If the file was opened using REWRITE and is a disk file, i t is deleted from the directory.
The LOCK option will cause the disk file associated with the FILEID to be made permanent in the directory if the file is on a
dfrectD~y-structured device and the file was opened with a REWRITE;
othe~wise a NORMAL close is done.
The PURGE option will delete the TITLE as~ociated with the FILEID fram the directory. The unit will go off-line if the device is not block structuT~d.
T h 1;:' C R UNC Hop t i. 0 n i ~~ as y n t u n d e fin (~ d i n ll' hat i t wi 11 do...
The intent is to ID~k a fil~ with the minimum number of blocks of u.eful information.
All CLOSEs rega~dlegs of the option will ma~k the file cloned and will make the implicit variable FILEIDA undefin~d. CLOSE on a CLOSEed file causeG no action.
FtJNCTHlt ... l EOF (FILEID) : BOOLEAN.;
FUNCTION EOLN (FILEID) : BOOLEANi
If (FILEID) i's nt,1t present, the fileid INPUT is assumed (e. g.
IF EOF THEN . . . >. EOLN and E.OF return fl.~.lHe d'fter the f i l e specified is RESET. They both return tr-ue on a c lased fi le. When EOF (FILEIO) is
t~ue~ FILEIDA is undefined. When GET (FILEID) sets FILEIDA to the EOLN character OT the EOF character; EOLN (FILEID) will return true, and FILE!'fY" (in a FILE OF CHAR) will be s~t; to a bIanlc, If) while doing
puts or writ.s at the end of a file, tho file cannot be ~~panded to accommDdate th~ PUT or WRITE~ EOF(FILEID) will return true.
FUNCTION IORESULT INTEGER;
I~d"t;(?r any I/O opf~r.ations IORESULT c.ontains an INTEGER value corresponding to the values given in Table 2.
Page 125
PROCEDURE GET ( FILEID );
PROCEDURE PUT ( FILEID )i
These procedures are used for operations on typed files. A typed file is any file for which a type is specified in the variable dec 1 a rat ion l i e . ' FILE I D : FILE OF <: t Y P e" t • T his i s a sop p 0 sed to
untyped files which are simply declared as: ' FILEID: FILEi'. 'F: FILE OF CHAR' is equivalent to 'F: TEXT'. In a typed file each logical
record is a memD~y image fitting the description of a variable of the associated <type>.
GET (FILEID) will leave the contents of the current logical record pointed at by the file pointers in the implicitly declared
"window" variable FILEIDA and increment the file pointers.
PUT (FILEID) puts the contents of FILEIDA into the file at the location of the current file pOinters and then updates those pOinters.
PROCEDURE READ{LN} ( FILEID, SOURCE )i
PROCEDURE WRITE{LN} ( FILEIDi SOURCE )j
These procedures may be used only on TEXT (FILE OF CHAR) or INTERACTIVE fi les for. 110. If 'FILEID, , is omi tted, INPUT OT' OUTPUT
<whichever is appropriate) is assumed. A READ(STRING) will read up to and not including the end-of-line character «a carriage return» and
leave EOLN(FILEID> true. This means that any subsequent READs of STRING variables will return the null string until a READLN or
READ(chara~acter) is executed.
There are three files of type INTERACTIVE which are
predeclared: INPUT, OUTPUT, and KEYBOARD. INPUT results in echoing of characters typed to the console device. KEYBOARD does no echoing and allows the programmer complete cont~ol o~ the response to user typing.
OUTPUT allows the user to halt or flu~h the output.
PROCEDURE PAGE ( FILEID );
This prOCedUT'E'1 as described in Jensen & Wirth <ibid.), sends a top-of-farm (ASCII FF) tQ the file.
PROCEDURE SEEt{ (, FILEID, INTEGER ) i
This procedure changes the,file pointers so. that the next GET or PUT frDm/to the file uses the INTEGERth record of FILEID. Records in·
files are numbeT'ed from O. A GET or PUT must be executed between
SEEK, calls since two SEEKs in a row may cause unexpected, unpredictable Junk to b,~ held in the window and associated' buffers.
Section 2.1.3 reserved for future use
Page 127
- Notes
-P.:.lnn 1:>P.
CAUTION releases, but no details are currently available. Probable implementa-t ion ( s ): T e k tor 0 nix 4006.