Trailing-Edge
-
PDP-10 Archives
-
QT020_T20_4.1_6.1_SWSKIT_851021
-
swskit-tools/zsubs.mem
There are no other files named zsubs.mem in the archive.
USING THE ZSUBS PACKAGE
The ZSUBS package consists of a universal file of symbols, OPDEFs, and
macros, and a REL file of subroutines to implement many of the common
functions performed by a system utility type of MACRO program. There
are routines and functions related to:
o Initialization file processing
o Text output to terminals and files
o Somewhat formatted numeric output to terminals and files
o File specification output
o Program version number output
o Error handling and error message output
o COMND JSYS parsing of commands
o Simple basic PSI setup
o Inferior fork control
o Code suitable for implementation of simple common commands in many
command scanners -- EXIT, TAKE, PUSH
ZSUBS is used by a number of the SWSKIT programs to provide a common and
consistent interface and avoid duplicate code.
It is not necessary to use all of the ZSUBS facilities in any given
program although using ZSUBS does place some contraints on a program.
ZSUBS uses the LUUO mechanism for most of its calls. There are OPDEFs
for the LUUOs and MACROs for calling them with the normal form of
argument usage.
As usual, the actual program listing is the ultimate arbiter of usage
questions.
INITIALIZATION
1. A SEARCH ZSUBS must be in the program.
2. The $INIT macro must be used fairly early in the program. It
generates a .REQUIRE ZSUBS.REL, defines a list of locations as
externals, and calls an initialization routine with a JSP CX,$INIT..
This routine sets up a stack, the LUUO location, initializes some
USING THE ZSUBS PACKAGE Page 2
internal variables, and sets the PSI system before returning to the
caller. If you wish to use a different stack than the one in ZSUBS
(about 100 octal locations) you can reset P with another value after
this call and ZSUBS will use that stack in place of its own.
3. TAKINI is the address of a routine to process an initialization
file. Called with a pointer to the init file name in T1, TAKINI
builds the name PS:<USERNAME>filename and causes that file to be
processed like a TAKE file. The caller will need to handle any
special casing of his commands for processing in an init file.
TAKINI returns +1 on success.
TEXT OUTPUT
1. PRINT(STRING) is used to call the PRINT. LUUO with the address of
the ASCIZ string. Output will go to the JFN in OJFN if set, or to
.PRIOU if not.
2. TYPE(STRING) is used to call the TYPE. LUUO with the address of the
ASCIZ string. Output will go to .PRIOU.
3. PSPACE <number> is used to print that number of spaces. Output will
go to the JFN in OJFN if set, or to .PRIOU if not.
4. TSPACE <number> is used to type that number of spaces. Output will
go to .PRIOU.
NUMERIC OUTPUT
1. OCTOUT(VALUE,SIZE) is used to output an octal value with optional
field size for right justification. Output is to the JFN in OJFN if
set and to .PRIOU if not.
2. DECOUT(VALUE,SIZE) is used to output a decimal value with optional
field size for right justification. Output is to the JFN in OJFN if
set and to .PRIOU if not. The value will end with a "." to indicate
a decimal value.
3. TOCT(VALUE,SIZE) is used to type an octal value with optional field
size for right justification. Output is to .PRIOU.
4. TDEC(VALUE,SIZE) is used to type a decimal value with optional field
size for right justification. Output is to .PRIOU. The value will
end with a "." to indicate a decimal value.
USING THE ZSUBS PACKAGE Page 3
FILE SPECIFICATION OUTPUT
1. PRTJFN(VALUE,MODE) is used to output the file specification string
for the JFN in location VALUE. Output will go to the JFN in OJFN if
nonzero, otherwise to .PRIOU. Any non-null value for MODE will
select output of the complete file specification, otherwise the
default from JFNS is used.
2. TYPJFN(VALUE,MODE) is used to output the file specification string
for the JFN in location VALUE. Output will go to .PRIOU. Any
non-null value for MODE will select output of the complete file
specification, otherwise the default from JFNS is used.
PROGRAM VERSION NUMBER OUTPUT
1. VERSIO ADDR is used to output the string corresponding to the
version number in ADDR in the standard form
<major>.<minor>(<edit>)-<who>. Output will be to the JFN in OJFN if
nonzero, otherwise to .PRIOU. VI%DEC in the version number word
will determine the output radix for the numbers.
ERROR CONTROL AND ERROR MESSAGE OUTPUT
1. WARN(STRING) is used to type out warning messages to .PRIOU. It
calls the WARN. LUUO to synchronize output, get to the beginning of
a line and output the string, preceded by a "%".
2. ERROR(STRING) is used to type out error messages to .PRIOU and
transfer control. It calls the ERROR. LUUO to synchronize output,
get to the beginning of a line and output the string. It then
clears the input buffer and transfers control to the address just
previous to the address specified in the COMND JSYS block CMDBLK as
the reparse address. Very useful for issuing error messages from a
COMND scanner based setup.
3. LERROR(STRING) is used to type out error messages to .PRIOU and
transfer control. It calls the LERRO. LUUO to synchronize output,
get to the beginning of the line and output the passed string. It
then outputs the error message string corresponding to the last
error in the process. If any selected output file (OJFN is
non-zero) is open, it will be closed. Any TAKE file in progress
will be aborted. Control is then transferred to the reparse address
in the CMDBLK COMND block minus one. Very useful for COMND based
routines which want to report the errors and do cleanup.
4. LOSE is the address of the generic error handling routine. It
performs as described above for the LERROR call, but without the
passed text message.
USING THE ZSUBS PACKAGE Page 4
COMND JSYS PARSING
The COMND routines use a normal COMND argument block with address at
CMDBLK. The JFN block is at JFNBLK, the text buffer is at TXTBUF, and
the atom buffer is at ATMBUF.
1. PARSE ADDR is used to pass the address ADDR of a COMND style FLDDB.
parse block to a routine to do the parsing. The block CMDBLK is
used for the parsing. ACs T1, T2, T3 will have the COMND results on
return.
2. CONFRM is used to parse a command confirmation (end of line).
3. NOISE(STRING) is used to call the NOISE. LUUO to parse guidewords
corresponding to STRING.
4. AA(NAME,DATA,BITS) is a MACRO used to generate keyword table entries
for COMND where NAME is the keyword, DATA is the data field value,
and BITS, if specified, selects the extended form of the TBLUK table
entry, and sets CM%FW and BITS in the flag word. The user is
responsible for the table header word and keeping the entries in
alphabetical order.
5. COMMND is the address of a COMND calling primitive, sometimes
(though hardly ever) useful for really special parsing. Called with
T2 containing the address of the COMND descriptor block, it returns
+1 on a NOPARSE return from COMND, and +2 on a successful parse. It
exits via LOSE if the COMND JSYS takes the ERJMP return.
6. .EXIT is the address of a generic EXIT command routine; it parses
the confirmation and then makes sure OJFN is closed and halts. A
continue will return to the command processing loop. Using .EXIT is
not mandatory.
7. .PUSH is the address of a generic PUSH command routine; it parses
the confirmation and then uses the DEFAULT-EXEC: logical name to
invoke a new EXEC in an inferior fork and run it. Use of .PUSH is
not mandatory.
8. .TAKE is the address of a generic TAKE file command routine; it
parses the filename and confirmation and then saves the old primary
I/O designators in OLDPRM, followed by an SPJFN to the TAKE file.
The TAKE file JFN is stored in TAKJFN. Nested TAKEs are not
allowed. The error processing code in LOSE will recognize
end-of-file on the TAKE file JFN and cause UNTAKE to be called to
reset the primary I/O and release the TAKE file JFN. Use of .TAKE
is not mandatory, but it would be difficult to use a different TAKE
command routine in place of this one.
USING THE ZSUBS PACKAGE Page 5
PSI SYSTEM
The PSI system database is tables LEVTAB and CHNTAB. Only level one and
channel zero are defined in them. Initialization activates the channel,
but there is nothing attached to it.
1. SETABT ADDR is used to establish the address of an abort routine to
be taken upon receipt of a Control-E character. Saves the current
stack value (from P) into location SAVPSI, and sets the Control-E
interrupt on channel 0 (INTCHN). Upon receipt of a Control-E, the
interrupt code is deactivated, and a DEBRK is done to the abort
routine address.
2. CLRABT is used to clear the terminal interrupt code for Control-E
(in the event an interrupt was not received during the interval
SETABT was in effect).
FORK CONTROL
The routine used by the PUSH command is accessible directly.
1. DOFORK is the address of a routine which takes a pointer to a
filenname in T2, and then GETs the file into an inferior fork, runs
it, and waits for it to complete. It then kills the inferior fork.
DOFORK returns +1 on file errors, via LOSE on actual fork errors
trying to run it, and +2 on success.
GLOBAL VARIABLES
1. $INIT. - initialization routine.
2. CMDBLK - normal form COMND argument block.
3. JFNBLK - Long form GTJFN block used by the COMND block.
4. TXTBUF - Text buffer pointed to by CMDBLK.
5. ATMBUF - Atom buffer pointed to by CMDBLK.
6. LEVTAB - PSI level table.
7. CHNTAB - PSI channel table.
8. SAVPSI - copy of P saved here by SETABT.
9. OJFN - if nonzero, the JFN used by PRINT-class routines for output.
USING THE ZSUBS PACKAGE Page 6
10. JFNTMP - single level JFN stack for use in parsing JFNs.
11. PDL - internal stack set by $INIT available for use.
12. TAKJFN - if nonzero, the JFN of a TAKE file in progress.
13. .EXIT - generic EXIT processing command routine, closes OJFN.
14. .PUSH - generic PUSH command processing routine.
15. .TAKE - generic TAKE command processing routine.
16. LOSE - general error routine.
17. DOFORK - routine to run an inferior fork.
18. COMMND - a more primitive COMND entry point.
19. TAKINI - routine to process an init file.
EXAMPLES
For examples of usage, see the SWSKIT programs DS, DSKERR, SWSERR, FIND,
or MTCOPY.
[End of ZSUBS.MEM]