There are 26 other files named macsym.doc in the archive. Click here to see a list.
MACSYM.DOC -- Version 5
COPYRIGHT (C) 1976,1978,1982 BY
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.
MACSYM.DOC Page 2
MACSYM.DOC -- Version 5
MACSYM is a file containing macro definitions and object-time support
code which implement a number of useful machine-language coding
facilities used in the monitor and system program sources. These
facilities include variable naming and storage conventions and data
structure techniques similar in principle to capabilities found in
some implementation languages.
MACSYM is not an executable program. It may be assembled by and used
with MACRO version 53A.
MACSYM requires MONSYM.UNV for assembly and use.
2.0 EXTERNAL CHANGES
A new set of structured programming macros has been added to MACSYM.
A memo describing their use has been appended to this DOC file.
A set of macros providing extended addressing support, particularly
with byte pointers, has been added. Their use is documented in
3.0 KNOWN BUGS AND DEFICIENCES
There are no known bugs or deficiencies in MACSYM.
4.0 INSTALLATION INSTRUCTIONS
4.1 Files Needed for MACSYM Use
MACSYM.UNV - Universal file for MACRO assemblies.
MACREL.REL - Object-time support routines.
MACSYM.DOC Page 3
4.2 Instructions for Loading and Installing MACSYM
Mount the tape labeled Installation Tape on MTA0: and type the
SKIP MTA0:5 FILES
RESTORE <*>MACSYM.* (TO) SYS:*.*.-1,<*>MACREL.* (TO)
4.3 Files Needed to Build MACSYM
MACSYM is built from the following files:
In addition, the following file must be on SYS:
4.4 Instructions for Building MACSYM
Mount the tape labeled Distribution Tape on MTA0: and type the
RESTORE <*>*.*.* (TO) <self>*.*.*
Once the batch job has successfully completed, the files MACSYM.UNV
and MACREL.REL should be copied into SYS:.
4.5 Special Considerations
MACSYM is not an executable program. Hence, there is no .EXE file of
it ever created.
MACSYM.DOC Page 4
5.0 INTERNAL CHANGES
FLDDB. and FLDBK. have been changed to allow "" in help messages.
[End of MACSYM.DOC]
[APPENDIX A is appended as an integral part of MACSYM]
1.0 STRUCTURED PROGRAMMING MACROS
1.1 BLISS-style Subroutine Calls
MACSYM now has macros which implement Bliss-style subroutine calls and
which are otherwise compatible with the usual TOPS-20 conventions.
"Bliss-style" means that they push their arguments onto the stack and
then do a PUSHJ. They are not exactly compatible with actual BLISS
conventions in order to be fully compatible with TOPS-20 conventions.
The general format is this:
At routine entry, you say:
NAME: BLSUB. <sym,sym,...,sym>
Each symbol becomes defined as -n(P) much like symbols defined with
STKVAR. At runtime, they will address the stack locations setup by
A frame pointer is setup in .FP (P6) the same as with TRVAR. Hence,
STKVAR, SAVEAC and local calls can be used within a BLSUB., but TRVAR
To call a routine defined as a BLSUB., you say:
where the number of args must be the same as expected by the
Each arg can be one of several things:
1. a normal effective address optionally including indexing and
2. a structure reference;
3. an immediate address written as <.,adr>. This address is
computed with an XMOVEI, so section information will be
determined and retained at call time.
The difference between 1 and 2 isn't always syntactically obvious, but
the macro "figures it out". Be careful to use brackets if the
structure reference contains a comma however. E.g., if you would say
the call should look like
Here's a complete example:
This call has 4 args:
1. The contents of FOO as would be loaded by MOVE AC,FOO.
2. The contents of @FIE(X) as would be loaded by MOVE AC,@FIE(X)
3. The address FUM as would be loaded by XMOVEI AC,FUM
4. The contents of a defined structure as loaded by LOAD
Skip returns can be used as usual.
No ac's are automatically preserved by BLSUB.. Hence, you must save
any preserved ac's that you use in the subroutine. Seems like a good
idea to preserve the T's as well.
The benefit of these kinds of subroutines is that the calls are a lot
cleaner. You avoid a lot of juggling of ac's, particularly where
several arguments are involved. Also, it is obvious exactly what is
being passed to the subroutine, and the reader doesn't have to guess
what ac's are needed or merely incidental. So far, this has been used
in only one place; as an alternate way of calling DTEQ in TTYSRV.
The original DTEQ takes arguments in 5 (count 'em 5) ac's, and it's
more like 8 arguments in total since some of the ac's have independent
LH and RH. Each call in the original is typically preceded by a
hideous mess of Hxxx, EXCH, MOVE, etc. The calls to the new routine
(TTDTEQ) are always a neat single line.
BLSUB. can also takes a second list of symbols which will be defined
as local dynamic variables ala TRVAR. E.g.,
This means that AA, BB, and CC are arguments supplied by the caller,
and TT, UU, and VV are local stack variables.
1.2 Block-structured Macros
The beginning of a block is identified by one of the IFx macros. The
end of the block is identified by ENDIF. ELSE. may be used exactly
once within the block to indicate alternative code. The 'and' macros
(ANx.) may be used between the beginning of the block and the ELSE.
1.2.1 Skip Conditionals (Single Condition) -
IFNSK., IFSKP. - "IF NO SKIP", "IF SKIP"
These macros cause the following code to be conditionally executed
depending on whether the preceding instruction(s) skipped or not. The
following code is ended with ENDIF., and ELSE. is optional within the
Note: both of these result in the same or fewer instructions than the
use of literals to handle the same cases. Also, since the code is not
in literals, the binary appears in the listing, and the code is easier
to follow with DDT. If the preceding skip can be written in either
sense, it is better to use IFSKP. because one fewer instructions will
IFSKP. and IFNSK. have an alternate form where the consequence code is
given as a macro argument. In the normal case, no macro argument is
given. If this form is used, the consequence code is the first
argument. A second argument, the alternative code, may be given only
"IF NO SKIP"
If the instruction(s) preceding the macro does not skip, the
'consequence code' will be executed; otherwise (i.e. if the
instruction skips) the 'alternative code' will be executed.
If the instruction(s) preceding the macro skips, the 'consequence
code' will be executed; otherwise (i.e. if the instruction does not
skip) the 'alternative code' will be executed.
CALL TSOBEX ;OUTBUF EMPTY?
MOVEI T1,TTOBET ;NO, RETURN TEST TO WAIT FOR IT
;Example: shows both THEN and ELSE cases.
TQNN <TTSAL,TTHPO>,(T2) ;SPECIAL OUTPUT GOING?
TDCALL D,<<FE,TTXON1>>> ;YES, RESTART THE LINE
TDCALL D,<<FE,TTCHI3>> ;NO, STOP THE LINE
;Same as the preceding but using alternate form.
TQNN <TTSAL,TTHPO>,(T2) ;SPECIAL OUTPUT GOING?
TDCALL D,<<FE,TTCHI3>> ;NO, STOP THE LINE **the THEN case**
TDCALL D,<<FE,TTXON1>>> ;YES, RESTART THE LINE **the ELSE case**
;Example: shows both explicit END and bracketted cases
TTDOBE::CALL SKCOE ;SKIP IF CTRL-O INTERRUPT ENABLED
SKIPN CTRLOF ;NEW STYLE?
MOVEI T1,TTOMRK ;YES, JUST PUT MARKER IN OUTPUT STREAM
CALL TSOBED ;SEE IF OUTPUT IN PIPE
IFSKP. <RETSKP> ;NO, RETURN OK
;Example: shows nested useage
TTSOBE::CALL SKCOE ;SKIP IF CTRL-O INTERRUPT ENABLED
SKIPN CTRLOF ;NEW STYLE?
CALL OWNTTY ;JOB OWN TTY?
MOVEI T1,TTOMRK ;YES, JUST PUT MARKER IN STREAM
RETSKP ;SAY OUTBUF EMPTY
JN TTOTP,(T2),R ;RETURN NOSKIP IF OUTPUT IS STILL ACTIVE
;More complex example
TQNE TTNXO,(T2) ;END-OF-PAGE MODE?
CAME T1,T3 ;AND UNPAUSE ON PAGE CHARACTER?
TQNN TTSFG,(T2) ;ALREADY PAUSING?
CALL TTXONP ;YES, RESTART OUTPUT
RETSKP ;RETURN NOW, LOSE CHARACTER
LOAD T3,TTPPC,(T2) ;NOT PAUSING NOW,
CAME T1,T3 ;THIS THE PAUSE CHARACTER TOO?
RETSKP ;NO, JUST LOSE THE CHARACTER
CALL TTXOFP ;YES, MAYBE PAUSE NOW
IFSKP. <RETSKP> ;RETURN NOW IF PAUSED
LOAD T3,TTPPC,(T2) ;GET PAGE PAUSE CHARACTER
1.2.2 Skip Conditionals (Multiple Conditions) -
Multiple conditions can be specified for IFSKP. and IFNSK. with the
macros ANSKP. and ANNSK.. (Read "and skip", "and noskip".) Both "and"
macros may be used with either IFSKP. and IFNSK. The general form is:
first test condition
second test condition
third test condition
That is, you get to "consequence" only if first test AND second test
AND third test are successful. Note that any code can be present as
the second and subsequent test conditions; each test will be executed
until one is reached which does not satisfy its following macro,
whereupon control will branch to the ELSE. or ENDIF. as appropriate.
SETZM FOO ;THIS ONLY IF FLAG1=0 AND AF=1
1.2.3 Branch Conditionals -
The following may be used in cases where a jump instruction is
available to test the condition.
where 'x' is one of: L, LE, E, N, GE, G, and 'ac' is the ac to be
MOVEM T2, FIE
This reads: "If T1 is greater than 0, move FOO to FIE". Four
additional cases of IFx. are supported. They are:
IFXE. and IFXN. which take AC and MASK (ala TXNE/TXNN), and IFQE. and
IFQN. which take a structure identifier (ala TQNE/TQNN).
ANDx. macros are available for all the same cases as IFx., that is,
ANDE., ANDN., ANDG., ANDGE., ANDLE., ANDL., ANDXE., ANDXN., ANDQE.,
ANDQN.. They can be intermixed arbitrarily in conditionals started by
TMSG <NOT ALL CONDITIONS MET>
The above types "hallelujah!" if T1 is non-0 and FLG(XX) is on and the
call to MUMBLE skips, otherwise it types "not all ...".
1.2.4 Loop Control -
DO. - Loop block.
As with the other block macros, the use of DO. facilitates making
structure apparent and reduces the need for tags.
DO. begins a loop block; the matching OD. ends it. Neither
generates any code, only tags.
LOOP. assembles into a single instruction to jump to the top of the
EXIT. assembles into a single instruction to jump out of the loop.
TOP. assembles as the address of the top of the loop for jumps, e.g.
ENDLP. assembles as the address at the end of the loop for jumps out,
e.g. SOJL T4,ENDLP.
MOVEI T4,COUNT ;SETUP COUNT FOR LOOP
DO. ;TOP OF LOOP
SKIPN T1,TABLE(T4) ;SOMETHING HERE?
EXIT. ;NO, DONE
SUBI T4,1 ;COUNTDOWN ENTRIES
MOVE T2,0(T1) ;FOLLOW POINTER
JUMPE T2,TOP. ;NOTHING HERE, LOOP
BLCAL. XYOUT,<T2> ;DO SOMETHING WITH IT
JUMPE T1,ENDLP. ;NO GOOD, QUIT
LOOP. ;GO ON TO THE NEXT
.. ;HERE WHEN DONE
[End of APPENDIX A]