PDP-10.its/doc/_info_/palx.order

PALX command string format:

BIN, LST, ERR _ SRC1, SRC2,...,SRCN

The SRC files are effectively concatenated and assembled.

If the BIN spec is empty, no bin file is generated, unless the BIN spec is
followed by the "_".

If the LST spec is empty, a LST file is generated with default names iff there
is no ERR spec.

If no LST is wanted, the comma should be omitted as well.

If the ERR spec is present (that is, the LST spec is followed by a comma) an
ERR file is produced with the default names.  (If you don't want one, omit the
comma between the LST spec and the "_")

The device defaults to DSK for the BIN, LST and 1st SRC files.

The 1st name for BIN, LST and ERR files defaults to that of 1st SRC file.

The 2nd name for the BIN file defaults to BIN;
  That of the lst file, LIST if /c isn't given, CREF if it is
  That of the ERR file, to ERRORS
  That of the SRC files, to > .

:_SRC1,SRC2,...,SRCN		can be abbreviated
SRC1,SRC2,...,SRCN

Switches do not constitute a non-null spec. (":" or ";" will do that)

The switches are:

/B - Suppress binary. (useful with short format)
/C - Output cref listing. forces /L.
/D - Give back tty and run disowned.  Logout when finished.  Forces /E.
/E - Force error file to be written.
/H - Double size of symbol table for each /H seen.
/L - Output listing even if no LST spec.  (useful with abbreviated format)
     If /L appears twice in the command string, listing will be done on both
     passes.
/M - Suppress listing of lines generated by macros.
/N - Suppress error messages on tty.  Forces /E
/P - Output bin on Ptp:. Forces /S.
/R - Reproduce source in listing.  Forces /L.
/S - No symbols in BIN.  Forces BIN to be generated unless /B.
/T - Cause normal listing if LST is on tty, cause tty-type listing if LST isn't
     on tty.
/V - Sets the number of lines per page to be used in the listing.  It should be
     followed by an L for LPT, an X forf XGP, or a decimal number terminated by
     a comma, which should be the desired number of lines per page including
     space for margins.  (That is, 60. for the LPT, etc.)  This is the only
     switch which affects more than one command string - the value set by the
     switch will be used for each assembly until another occurrence of the V
     switch alters the value.

Command files:

If "@FILSPEC" is placed in a command string, the contents of the file FILSPEC
are effectively inserted in the command string, surrounded by spaces.  The
character following "@FILSPEC" is lost, and should be a comma unless "@FILSPEC"
is at the end of the command string, when the same ^M that ends the command
string will end "@FILSPEC".

^M and ^J in the file are treated as spaces; ^L and ^C terminate the file.
Command files may refer to other files to a depth limited by the iopdl.

Command file names default independently to DSK: >
They have no effect on the defaulting of other file names.

The character ^U cancels an entire command string, just as a sufficient number
of rubouts would.

in DDT,
:PALX command
is equivalent to
PALX^K
command^C

On finishing a command, PALX will normally ask for another.  But, if the
command was terminated by ^C instead of ^M, and no fatal errors occurred during
execution, PALX will do a .BREAK 16,140000 to delete itself without flushing
the typein buffer.  Fatal errors do flush it.  Thus, one can type DDT commands
after a command terminated by a ^C.  (And also commands to other programs that
might be run by the DDT commands).


Macro-argument scan:

If the first character read when a macro-arg is expected is ^, the next
character is used as the delimiter and all successive characters up to the next
appearance of the delimiter go in the macro arg.  After that, spaces are
skipped, and a comma, CR or ; should follow.

If the first character seen is <, all characters between it and the matching >
(not including the < and > themselves) go in the macro arg.  After the >, 
spaces are skipped and a comma, CR or ; should follow.

If the first character is \, an expression is read in and its value is
converted to a string in base 8, which becomes the macro argument.  After the
expression, spaces are skipped, etc.

Otherwise, all characters up to but not including the first comma, CR or ;
go in the macro arg, except that trailing spaces (and tabs, of course)
before a ; will be ignored.

If the scan of the argument stopped on a CR or ;, there are no more arguments.
Any more arguments wanted will be made null. The CR or ; will remain to be
re-read after the expansion of the macro, etc.  If the scan stopped on a comma,
the next argument's scan will start with the character after the comma.


Pseudo-ops:

Ordinary pseudo-ops are legal only as the first symbol in a line.  Each use of
a pseudo-op uses a whole line.

Value-returning pseudo-ops may be used anywhere an ordinary symbol may be used.
Such a pseudo will usually skip over any comma following its last arg.  If
there is to be anything on the line after the psuedo's last arg the comma
should be used; eg:
    foo==.length ^/ gg,,hh /,+1	;sets foo to 9.

.ABS            Sets %ABSADR to nonzero.  Exactly the same as %ABSADR=-1

.ADRMD ADDR	is a value-returning pseudo whose value is the addressing mode
                of ADDR (the 6 bit quantity that would go in the SRC or DEST
                field of an ordinary instruction given ADDR as an arg).  If you
                want to follow this construction with an arithmetic operator
                put a comma in between; otherwise the operator may be included
                in ADDR.

.ALSO		Assembles the following code up to the matching .ENDC iff the
                last conditional succeeded; i.e. if %SUCCESS is non-zero

.ASCII /TEXT/	Generates several bytes from the chars of TEXT.  "/" may be
                replaced by any char not in TEXT.

.ASCIZ /TEXT/	Similar but puts a zero byte after the TEXT.

.AUXIL		Does nothing.  This operator gives information to the @ lister.

.BLKB N		is like .=.+N

.BLKW N		Moves to even addr, then leaves N words of space.  Like
                .=.+<.&1>+<2*n>

.BYTE A,B,C	Generates 3 bytes containing A,B,C respectively.  Any number of
                args may be given.  Only commas separate args.  Null args are
                treated as 0. 

.EJECT		Starts a new listing page.  Useful in macros, etc. where ^L's
                can't be used.

.ELSE		Assembles the following lines up the the matching .ENDC iff the
                last conditional failed; i.e. iff %SUCCESS is zero.  %SUCCESS
                is complemented.

.END ADDR	Ends a pass.  Remaining input is ignored.  Sets the starting
                address to ADDR.  ADDR may be absent, in which case 1 is used.

.ENDC		Terminates a conditional.  Error if unmatched.

.ENDM		Terminates a .MACR or .TTYMA .

.ENDR		Terminates a .REPT .

.EOT		Causes whatever remains in current SRC file to be ignored.

.ERROR MSG	Causes an error whose message is just the source line ".ERROR
                MSG".  As with other errors, the PC, page and line are printed.

.EVEN		Like ".=<.&1>+." -- moves up to even addr.

.EXPUNGE	Makes the symbols in the list following it undefined, like
                .KILL in MIDAS: .EXPUNGE A,B,C

.IALSO STATEMENT
		Assemble STATEMENT iff %SUCCESS is non-zero.  See .ALSO .

.IELSE STATEMENT
		Assemble STATEMENT iff %SUCCESS is zero.  See .ELSE .

.IF CONDITION
		Assemble lines up to following .ENDC only if CONDITION is true.
		The conditions are:
		 1) Arithmetic conditionals:
		    NAME EXP
		    where NAME can be E,EQ,L,LE,LT,G,GE,GT,NE,NG,NL,NZ,Z
		    and any expression can be used.  E.g., .IF EQ X-Y
		 2) String comparison:
		    DIF ARG1,ARG2
                    where ARG1 and ARG2 are macro-type args.  E.g.,
                    IDN ARG1,ARG2
		 3) String comparison with null string.
		    B ARG		true if ARG (a macro-type arg) is null
		    NB ARG		true otherwise.
		 4) Definition testing
		    DF EXP		true if all syms in EXP are defined.
		    NDF EXP		the opposite.
		 5) Pass number testing
		    P1			true on pass 1
		    P2			true on pass 2

.IFF		A subconditional.  May appear only inside a conditional.
                Switches the sense of the conditional for the code that
                follows, so that it will assembled iff the conditional failed.

.IFT		A subconditional that restores the original sense of the
                conditional for the code that follows.

.IFTF		A subconditional that causes the following code in the
                conditional to be assembled unconditionally.  This is different
		from ending the conditional because a .IFT may appear later and
		make assembly conditional again, for instance.

.IF1		Assemble lines up to following .ENDC only on pass 1.

.IF2		...only on pass 2.

.IFB LINE	...only if 1st nonblank in LINE is CR, ; or comma.

.IFDF EXP	...only if all symbols in EXP are defined.

.IFG EXP	...only if EXP is positive.

.IFGE EXP	...only if EXP is nonneg.

.IFL EXP	...only if EXP is negative.

.IFLE EXP	...only if EXP is nonpositive.

.IFNB LINE	...only if 1st nonblank in LINE isn't comma, CR or ; .

.IFNDF EXP	...only if some symbol in EXP is undefined.

.IFNZ EXP	...only if EXP isn't 0.

.IFZ EXP	...only if EXP is 0.

.IIF CONDITION STATEMENT
		Assemble STATEMENT only if CONDITION true.  See .IF for
                documentation of conditions.

.INSRT FILSPC	Pushes the current source file and/or repeat, macro, etc. and
                starts reading from the specified file.  After the end of that
                file, the file or macro containing the .INSRT will be resumed
                starting with the next line.  The characters "/@,_" are not
                special in .INSRT FILSPC's - they go right in the filenames.
                If the spec'd file isn't found, a non-fatal error occurs and
                assembly of the .INSRT-ing file resumes.  %FNAM2 is set to the
                2nd name of the .INSRTED file and remains set after the file is
                finished (unless that file has done a .INSRT, of course).

.IRP DUMMY,<A1,A2,A3>
		Repeats all the following text up to the matching .ENDM
                substituting A1 for DUMMY the first time, A2 for DUMMY the 
		second time, etc.  The stuff following the comma is a macro-arg
                and might also be delimited by ^/ ... /, for example.  If the
                arg is delimited with < and > then <'s and >'s within the arg
                are significant; i.e. ".IRP X,<FOO,<BAR,FAH>>" repeats over two
                args, "FOO" and "<BAR,FAH>", whereas ".IRP X,^|FOO,<BAR,FAH>|
                repeats over three args, "FOO", "<BAR", and "FAH>".


.IRPC DUMMY,STRING
		Repeats the text up to a matching .ENDM once for each character
		in STRING, each time substituting that character for DUMMY.
		DUMMY must be a symbol; STRING is read in as a macro-argument.

.LENGTH STRING	Where STRING is read in as a macro arg, returns the number of
                characters in STRING.  This is a value-returning pseudo and
                arithmetic can be done with it (but remember to put a comma
                between the arg and any following arithmetic operators).

.LALSO
ANY-STATEMENT-ON-NEXT-LINE
		Assembles the next line iff %SUCCESS is non-zero.  See .ALSO .

.LELSE
ANY-STATEMENT-ON-NEXT-LINE
		Assembles the next line iff %SUCCESS is zero.  See .ELSE .

.LIF CONDITION
ANY-STATEMENT-ON-NEXT-LINE
		Assembles the next line only if CONDITION is true.  If
                CONDITION fails, lists the next line but does nothing with it. 

.LIST		Decrement XLIST count if it isn't 0.  Listing takes place only
                if XLIST count is 0.  The .LIST itself lists only if XLIST
                count was 0.

.MACR M A,B,C	Define M as a macro with args named A,B,C .  The macro
                definition is on the following lines, up to a .ENDM
                (intervening matched .MACR'S and .ENDM's go into the macro
                being defined).

.MACRO M A,B,C	Same as .MACR M A,B,C .

.MEXIT		Pops out of the innermost .REPT, macro-call, .IRP or .IRPC .

.MSG LINE	Like .ERROR LINE, but doesn't increment the error count.

.NARG SYM	Sets SYM to the number of args in the innermost macro
                invocation (that is, does SYM==%NARG).  The symbol will be
                halfkilled.

.NCHR SYM,ARG	Sets the symbol SYM to the number of characters in ARG.  The
                syntax for ARG is the same as for macro args.  The symbol will
                be halfkilled.

.NTYPE SYM,ARG	Sets SYM to the addressing mode of ARG.  For example, if ARG is
                200(4), SYM will be set to 64.  The symbol will be halfkilled.

.NLIST		Increments the XLIST count. same as .XLIST .

.ODD		Moves to next odd address -- same as .=.+1-<.&1>

.OFFSET EXP	Sets the offset to EXP.  Whenever the symbol "." is used, in
                relative addressing, and in defining labels, the offset is
                added to the real location counter.  The offset is 0 at the
                start of a pass.

.PAGE		Starts new page in listing. same as .EJECT .

.PRINT /TEXT/	Prints TEXT on the tty.

.RAD50 /TEXT/	Generates several words of radix 50 code, one for every 3 chars
                in TEXT.  Zeroes fill up last word, if necessary.

.REM MSG	Same as .MSG MSG .  Don't ask me why RCC added this.
                - Look, if we're going to put comments in here: don't ask me
                why you wrote this documentation all in upper case.  It's so
                hard on the eyes that I spent 2 hours fixing it.  --PGS

.REPT EXP	Starts a repeat.  The body of the repeat consists of all
                following lines up to a matching .ENDR .  The body of the
                repeat is assembled EXP times.

.SBTTL LINE	Same as .STITL LINE .

.SEE SYM	May go anywhere a symbol would be evaluated.  Has no effect
                except to CREF the symbol SYM.  The @ lister also will see that
                SYM is used.

.STITL LINE	Sets the subtitle to LINE.  The subtitle lists on the 2nd line
                of each header.  If the .STITL is the first line of a page, it
                takes effect on that page; else, on the next page.

.TITLE LINE	Sets the title to LINE, also types it on tty.  The title
                appears on the 1st line of each header.  Takes effect as .STITL
                does.

.TTYMA A,B,C	Reads a line from the tty, then defines A,B,C from that line
                using the macro-arg scanning rules.  Within the scope of the
                .TTYMAC (up to a matching .ENDM) A,B,C will be replaced by the
                strings obtained by scanning what was read from the tty.

.WORD A,B,C	Like .BYTE A,B,C but makes a word from each arg, instead of a
                byte.

.XCREF A,B,C	Prevents CREF output from being generated for symbols A, B, C.

.XLIST		Increments the XLIST count.


Special symbols:

These may be used as normal symbols, or set with "=".

.		The location counter (including offset).  . always equals
                %.+%OFFSET .  Setting .=A is equivalent to %.=A-%OFFSET.

%.		The unoffset location counter (where code will actually be
                loaded).  

%ABSAD		If nonzero, PALX will use absolute addressing as the default,
                instead of relative addressing.  That is, "MOV FOO,%0" will
                assemble in this mode the way "MOV @#FOO,%0" always does.  Note
                that "@FOO" will still use indexing by the PC.  Explicit
                indexing by the PC will not be overridden.

%COMPAT		If nonzero (as is the default), PALX gives an error message
                when an instruction that executes differently on different
                model PDP-11's is assembled.

%DAY		The number in the month of the day on which the assembly is
                done. (see %MONTH, %YEAR) [not Tenex]

%FNAM2		The result of taking the current source file's second name, and
                turning it into a decimal number, ignoring non-digits.

%MONTH		The number in the year of the month on which the assembly is
                done. (see %DAY, %YEAR) [not Tenex].

%NARG		The number of args given to the innermost macro invocation.

%OFFSE		The value of the offset.

%SUCCESS	Non-zero if the last conditional succeeded, i.e. the the
                condition was true; zero otherwise.  This is set both when the
                conditional is evaluated and when its scope is terminated (e.g.
                by a .ENDC).

%TTYFL		Initially 0. when nonzero, tty typeout is inhibited.  Cleared
                by any attempt to do tty input.
		
%XCREF		Stops CREFfing if not 0.

%XLIST		The value of the XLIST count.

%YEAR		The number of the year in which the assembly is done.  This is
                only that last two digits, so in 1980 %YEAR is 80., and in 2001
                %YEAR is 1. (see %DAY, %MONTH) [not Tenex]

.RPCNT		Normally 0 except in repeats.  In repeats, is 0 the 1st time
                through, 1 the next, etc. 

.IRPCN		Like .RPCNT but for IRPs instead of repeats.

Symbols of the form 69$ are "local tags."  The scope of these symbols is
limited to the area between two ordinary labels.  These are typically used for
tags in branches that skip over a few lines within a single routine.  These
symbols behave the same as in MACRO-11.

The following symbols are predefined in PALX:

For teletype: %TKS, %TKB, %TPS, %TPB and trap vectors %TKV, %TPV
For paper tape: %PRS, %PRB, %PPS, %PPB, and vectors %PRV, %PPV
For 60-cycle clock: %LKS and vector %LKV
For programmable clock: %PKC, %PKCSB, %PKCSR and %PKV
For line printer: %LPS, %LPB, and %LPV
For RF-11 disk: %DCS, %DWC (also %WC), %DCA (also %CMA), %DAR, %DAE, %DBR, %DSA
                (also %ADS), and %DV
For RK-11: %RKDS, %RKER, %RKCS, %RKWC, %RKBA, %RKDA and %RKV
For Knight display: %NGCSR, %NGREL
For DR-11: %DRS, %DRIB, %DROB, and %DRV1, %DRV2
For DC-11: %RCSR, %RBUF, %TSCR, %TBUF
For DM-11: %CSR, %BAR, %BCR, %TBR
For EAE: %DIV, %AC, %MQ, %MUL, %SC, %SR, %NOR, %LGS, %ARS
For processor traps: %ERRV(=4), %BPTV(=14), %IOTV, %PWRV, %EMTV, %TRPV
For processor regs: %PS, %SWR (switches)
For use with PDP11^K (the ITS PDP-11 simulator): %CSX

I will define others on request.


Error message format:

An error message has the following components:

REL-LOCTR   ABS.-LOCTR.  page  line  DESCRIPTIVE-MESSAGE.

The REL-LOCTR has the form LABEL+DISP.  It gives the value of the unoffset
location counter, relative to the most recently defined label.  It does not
appear if no labels have yet been defined (tabs are printed instead).

The ABS.-LOCTR is the unoffset location counter in octal.

The page and line numbers are in the source file.

In addition, on the first error in a source file other than the first file, the
message

FILE	such-and-such

will be printed.