A by-product of producing software for the PDP-15 has been the appearance of a quantity of small but useful routines. These have now been collected and recorded on a magnetic tape marked LIBRARY in the PDP-15 area.
This paper describes these routines in order to make them available to anyone programming the PDP-15. It should be remembered that, by and large, they were produced in response to a particular programmer's needs; the facilities available may therefore be rather incomplete.
The paper is intended to be read by people already familiar with the PDP-15. However someone unacquainted with the Digital terminology, may find helpful the glossary in Appendix A. Whichever category the reader is in, section 0 should certainly be read as it explains the layout of the library description. It may be necessary to refer to it as a routine is read up.
The routines are described in full in section 1 onwards. Each section is devoted to a particular category, for example, section 1 concerns character and bit manipulation. Within a section, a numbered item can refer to:-
either (a) a file consisting of a single subroutine (example section 1.3),
(b) a file consisting of several routines (example section 1.1) (this is normally a MACRO-15 file since the Fortran compiler only accepts one routine per file).
or (c) a collection of files which were designed to be used together (example section 2.3).
In the description of an item, the headings used are as follows and will appear in the order given. A heading may be omitted if no information concerning the item is relevant to it.
This begins with a subroutine or function name, a file name or a list of routine names, corresponding to the possibilities (a) to (c) above. If a function name, it is preceded by a type (INTEGER, REAL or LOGICAL) (for instance WTTY in 2.2 xiv) unless this can be deduced from the normal Fortran type convention. If subroutine or function name, the list of arguments in the calling sequence should have the same number as the definition. The most likely consequence of defying this is the system error message 'IOPS 00' or a halt after an attempted access to non-existent memory.
Since each routine can be called from a Fortran program, type specification statements for each argument are included if necessary (for example see 4.4). If a specification statement is not present, it can be assumed that an argument has the type, that its initial letter suggests, according to the normal Fortran type convention. For instance, in the routine IBITS (1.1 v), all parameters are of type INTEGER even though IBIWRD is interpreted as a bit pattern.
The heading also includes the initials of the originator followed by the source language.
The originator should normally be able to provide more detailed information about the item credited to him and, if the item is not on the library tape, he should have a copy available.
The source languages used are MACRO-15 and Fortran IV. All the MACRO routines described can be called from a Fortran program and are described using Fortran terminology. Anyone wanting to use a library item in a MACRO program or write a MACRO routine to be included in the library should read Ref 6 (F4 Programming) Appendix or, if using the DOS system, Ref 5 (F1 Operating) Chapter 5.
After the item heading, a brief idea of the purpose is given. In a few cases, this is sufficient to describe the routine and the heading "Description" (see below) is omitted.
The number of words occupied by the program.
Any routines called by the item are listed here and, if in Fortran, any COMMON blocks. Routines referred to should be loaded whenever the item is loaded.
.DA, the run-time-system program which transfers argument addresses from the calling sequence, is loaded automatically from the system library (.LIBR BIN) and no mention is made of it under this heading even when it is called. It is 47 (octal) locations long.
Any parameter, whose entry-value is used by the routine, is listed here.
Any parameter, whose value is changed by the routine, is listed and described here. No parameter under this heading should be replaced by a constant in the calling sequence; PDP-15 Fortran does not guard against overwriting constants.
A full description of the routine is given at this stage.
Self-explanatory.
This section describes variables, local to a library routine or MACRO-file, for which the routine being described assumes a previously set value. The run-time environment (whether overlaying using CHAIN and EXECUTE or simply using the linking loader) affects the value of such a variable. (Standard Fortran specifies that such a variable in a Fortran routine is undefined until assigned).
Under the PDP-15 Advanced Monitor System, the local variable, on entry, can be assumed to have the value that was set, the last time that execution left the routine or a routine in the MACRO-file, unless:-
(i) no previous call to this routine has been made in this job
or (ii) since the last call, the routine has been overlayed. If either exception applies, the variable is set its initial value. The initial value in a MACRO-file is defined in the source program. In a Fortran routine, the initial value is as defined in a DATA statement; otherwise it is undefined.
This section is relevant to a routine written in MACRO and,
(i) to a programmer writing a call from a MACRO program
or (ii) if the routine may be transferred to a different DEC machine.
The information given could be about the following:-
(a) auto-increment registers-- words 10-17 (octal) of store:
(PDP-15 Reference p6-3)
(b) EAE-- long shifts, hardware multiply and divide:
(PDP-15 Reference pp8-1 to 8-11)
(c) Use of the index register:
(PDP-15 Reference p6-3, 6-l4, 7-9, 7-10)
Of these (b) is not present on all PDP-15's and (c) is impossible if the computer is running in Bank Mode (which hardly ever applies on the Atlas PDP-15).
The sequence outlined above applies if the item is simply a function or subroutine. If the item is a MACRO-file (a file consisting of several MACRO routines), the order is:-
File heading purpose size external references any information that applies to all routines
followed by a section on each routine in turn, each consisting of:
routine heading purpose input .... .... special hardware
The library exists on a magnetic tape labelled 'LIBRARY' in the PDP-15 area. It is recorded at 556 b.p.i. odd parity. A list may be obtained as follows:-
(a) mount the tape on unit number 1, without a write ring
and (b) type the following (your typing in emphasis; commands to be terminated by the return key
$4 MTO 1
$MTDUMP
MTDUMP
BUFSIZE n
>DLIST 1
directory listing appears here
>EXIT
$
The list will comprise the names of Fortran routines and the names of the MACRO-files.
A source version of every library item should be present on the tape. If the library item is not in the directory listing, the originator should have a copy. The file extension should be 'SRC' or a 3 digit version number.
A file can be copied to DECtape as follows (suppose the filename is LIBFIL 001):-
(a) Mount the library tape on decknumber 0 without a write ring.
(b) Mount the DECtape on unit 1 with the WRITE ENABLE/LOCK switch set to ENABLE.
(c) Type the following (conventions as above).
$PIP
PIP Vnn
>T DTl+MTo LIBFIL 001(A)
>copying complete
After the file has been copied, it can be compiled or assembled. However note that it is possible to specify the values of parameters of a MACRO program at assembly time; one source program can breed many binaries. For this reason, some files are recorded on the tape in binary form also, the particular binary version corresponding to the description in this paper.
If a file does exist on the library tape in binary form, this should normally be used.
If, for some reason, it is necessary to reassemble a file, which requires assembly-time parameters, proceed as follows. Suppose that the MACROfile MAGTAP (see 2.1) exists on disc unit 1 and is to be assembled with the parameters as specified in 2.1, giving binary also on disc unit 1.
$A DK1 -11,-13
$A TT -10
$MACRO
>BP←MAGTAP
SOFTMF=0
MTSLT1=7
MTSLT2=1
ctrlD
END PASS 1
SIZE=n NO ERROR LINES
> assembly complete
For a full write-up on entering parameters at run-time, see Software Performance Vol 1 No 1 Section MACRO 6. (Ref 10)
The file includes routines which manipulate PDP-15 bit patterns and increase the flexibility of the Fortran addressing structure.
Size
106 words (decimal).
(i) FUNCTION ICNTNT(IADR) has as its result the contents of the location pointed to by IADR.
Input
IADR
Example
See below.
(ii) FUNCTION IDRESS(IVAR) has as its result the address of the variable IVAR.
Input
IVAR can in practice be of any type, since its value is not used. The address of a multi-word variable (real or double-precision) is returned as the address of first word of the variable.
Example
If JAR is an integer array, in a Fortran program, then the expression IDRESS(JAR(26))-IDRESS(JAR(1)) takes the value 25.
The expression ICNTNT(IDRESS(J)) where J is integer takes the current value of J.
IDRESS(ICNTNT(J)) is unlikely to be useful.
(iii) SUBROUTINE STINAD(IAD, IX) carries out an indirect assignment.
Input
IX is the value to be stored.
Output
IAD is the address of the location where IX is to be stored. IAD itself is not altered. This could be a constant - an exception to 0.1 (v).
Example
The statement
CALL STINAD (IDRESS(I), e)
where e is an expression, has the same effect as
I=e
(iv) SUBROUTINE OCTAL(INP,ITOP,IBOT) prepares a number for printing in its octal representation.
Input
INP is the number to be printed.
Output
ITOP on exit contains the top 3 octal digits or INP.
IBOT contains the bottom 3 digits.
Description
If INP can be represented by the octal digits ABCDEF, then ITOP becomes 4000 + A*100 + B*10 + C and IBOT becomes 4000 + D*100 + E*10 + F. If ITOP and IBOT are then printed 2I3, the effect is to print the octal representation of INP with all 6 digits present.
(v) FUNCTION IBITS(IBIWRD,MINBIT,MAXBIT) has as its result the value of a selected bit pattern of IBIWRD.
Input
IBIWRD is treated as an 18-bit pattern; the most significant bit is 0, the least is 17. MINBIT is the most significant bit of the pattern to be selected. MAXBIT is the least significant.
Description
The result is bits MINBIT to MAXBIT inclusive, right adjusted and with the remaining bits masked.
Example
After
IBIWRD = 3*(8**5)
I = IBITS(IBIWRD,0,2)
I has the value 3.
After
J = IBITS(-1,0,5)
J has the value 63.
(vi) FUNCTION IAMAL(ITOPS,IBOT10) has as its result the bit pattern formed by amalgamating the bit patterns ITOP8 and IB0T10.
Input
ITOP8 and IBOT10.
Description
The function can construct bit patterns unobtainable by simple multiplication due to problems with the sign bit. The result is:-
x exclusive-or IBOT10
where x has bits 10-17 of ITOP8 in bits 0 to 7 and the remaining bits (8 to 17) zero.
Example
If ITOP8 = 128 (bit pattern 10.000.000) and IBOT10 = 0, then the result is the bit pattern 1 followed by 17 0's, unobtainable by Fortran arithmetic.
This file consists of 2 routines which unpack 6-bit and pack-up 7-bit characters. The characters are simply treated as bit patterns; no code conversion is made. 7 bit ASCII codes in the PDP-15 Advanced Software can be found in the MACRO-15 manual Appendix A. (Ref 8).
Size
74 locations.
(i) SUBROUTINE UNPK6(IPKDBF,IUNPKD,LECNGTH) unpacks a buffer of locations packed 3 to a word.
Input
IPKDBF is an integer variable which represents the first location of the packed buffer (which can of course consist of one word). In a MACRO program using this routine, this can be a symbol labelling an area of store set up by .BLOCK. In a FORTRAN program, IPKDBF would normally be either a one-word buffer or an element of a COMMON block or an array element. LENGTH is the number of words to be unpacked. LENGTH should be strictly positive.
Output
IUNPKD is an integer variable which represents the first location of the buffer of unpacked characters. At least 3*LENGTH locations should be allocated. IUNPKD itself will contain the first 6-bit character.
Description
Each packed word is unpacked directly into the corresponding 3 locations of the output buffer, the most significant 6 bits first.
Examples
In a MACRO program:-
JMP TOHERE
.GLOBL UNPKG
.DEC
UNPKED .BLOCK 9
FILNAM .SIXBT 'DAATTAEXT'
TOHERE JMS* UNPK6
JMP .+4
.DSA FILNAM
.DSA UNPKED
.DSA (3)
END NOP
When control reaches END, the 9 locations at and following UNPKED will contain the 6-bit character codes of D,A,A .....E,X and T. In Fortran, suppose that a record of 3*N 6-bit groups has been read from 7-track tape into the locations IBUFF(201) to IBUFF(200+N). Then the following statement will construct an array of 6-bit integers from IBUFF(1) to IBUFF (3*N):-
CALL UNPK6 (IBUFF(201),IBUFF(1),N)
Note that 1=<N=<100 to avoid overwriting.
Special Hardware
The index register EAE Auto-index register 10.
(ii) SUBROUTINE ADT075(ISTRNG_IECHR) adds a character code to a 5/7 string of character codes (5 7-bit characters in 2 18 bit words).
Input
The variable ISTRNG should contain on entry, an integer which contains information about the number of characters in the string. The characters themselves are stored in the locations following ISTRNG. The information and the characters already present will normally have been stored by a previous call to ADT075, The integer equals
1024*m+n
where m is the number of complete word pairs in the string and n is the number of characters in the uncompleted word pair, which could be 0,1,2,3 or 4. The format was chosen to make adding a character a quick process and the calling program need not make use of it. The number of characters in the string is 5*m+n and the number of words it currently occupies (including the head word) is 2*m+3. A string can be made to have no characters in it by setting
ISTRNG=0 , before entering ADTO75
NEWCHR contains the character code to be added to the string of character codes. Sensible results will only be obtained if 0 =< NEWCHR =< 127.
Output
On exit, ISTRNG contains the same information about the updated string.
Description
The routine proceeds as follows:- (m and n as above)
(a) pointer#8592;(address of ISTRNG) + m*2 + 1
(b) If n=0 (that is if NEWCHR is to start a new word pair), clear words addressed by 'pointer' and ('pointer' + 1)
(c) Add the character code NEWCHR to the current word pair, having shifted it to the correct bit position.
(d) If n=4, then m=m+1 and n=0 else n=n+1
(e) Update ISTRNG with new values of m and n
(f) Exit.
Example
Consider the following Fortran program:-
INTEGER FIRST, STRING(13)
C EQUIVALENCE STATEMENT REMOVES ARRAY ACCESSES.
EQUIVALENCE (FIRST, STRING(1))
FIRST=0
LETTA=65
LETTEZ=90
DO 20 I=LETTA, LETTZ
20 CALL ADTO75(FIRST,I)
WRITE(3,100) (STRING(J),J=2,13)
100 FORMAT(1H ,6A5)
STOP
END
This program will output the alphabet on the peripheral attached to slot 3. Note that
(a) STRING(1) does not form part of the character string.
(b) FIRST (in the example) must be an integer variable in order to be able to set FIRST=0. One way of storing the characters in a real array is:-
INTEGER FIRST
REAL STRING(7)
COMMON /ST/FIRST,STRING
FIRST=0
etc.
Special hardware
EAE ; the index register.
(from FRAH in MACRO-15)
Size
42 words (decimal).
Input
IST and IFI are respectively the most and least significant bit in the sequence to be replaced (0 is the most significant bit: 17 the least).
IVAL is the quantity to be inserted.
Output
Selected bits of IWORD are replaced.
Description
(a) Bits IST to IFI of IWORD are cleared (IST=<IFI on entry!)
(b) The bit pattern IVAL is shifted (17-FI) bits left (towards the most significant end); 0's fill the least significant end.
(c) IWORD=(IWORD) (exclusive OR) (IVAL)
Note that there is no check to prevent IVAL having bits set other than in the bottom (IFI-IST+1) bit positions.
Example
CALL INBITS(I,3,7,IBITS(J,9,13))
replaces bits 3 to 7 of I with bits 9 to 13 of J (for IBITS see 1.1). These 2 routines give complete flexibility in bit manipulation on the PDP-15.
Special hardware
EAE.
(by JRG in MACRO-15). Stores an integer in a modified address.
Input
ITEM is the value to be stored.
IOFFST is the number to be added to the base address to obtain the location where ITEM is to be stored.
Output
IBASE contains the value ITEM if and only if IOFFST=0. Otherwise the only output from the routine will be in the location addressed by
(addr(IBASE)+IOFFST)
Description
CALL STORE(IBASE, IOFF, ITEM)
has the same effect as
CALL STINAD (IDRESS(IBASE)+IOFF,ITEM)
(See section 1.1 for STINAD and IDRESS).
Example
CALL STORE (I(1),5,J)
has the same effect as
I(6)=J.
The chief use is when IBASE is a simple variable which is known to be the start of buffer.
Special hardware
Index register.
(by FRAH, JRG in MACRO-15)
File MAGTAP is a collection of routines for transferring records of bit patterns between core and 1/2" magnetic tape. Records transferred contain no header information. No filing system is assumed except that filemarks can be written and detected.
Size
249 locations.
Routine Summary
(a) Setting up
IRMT ..... initializes a slot for reading IWMT ..... initializes a slot for writing MODEMT ... sets density and parity before transfer SLCTMT ... selects an input/output slot.
(b) Positioning
BKSRMT ... backspace tape one record SKPRMT ... skip one record BKSFMT ... backspace one filemark SKPFMT ... skip one filemark RWNDMT ... rewind tape.
(c) Transfer
READMT ... reads one record from tape WRTEMT ... writes one record to tape.
(d) Tapemarks
FLMKMT ... writes one end-of-file mark
CLSEMT ... on output, writes 2 end-of-file marks and positions
tape between them.
Routines are described below in alphabetical order.
Input/Output slots
All routines refer to the currently selected .DAT slot. The slot initially assumed is 7, A new slot I may be selected by:-
CALL SLCTMT (I)
With the binary version of the package currently available, I must be 1 or 7. If this restriction proves to be cumbersome, see 'Instructions for assembling' below which describes how the list of slots may be changed or increased.
Device Handlers
When the program using the package is to be loaded, a magnetic tape handler must be assigned to the .DAT slots in the package (1 or 7). Because of the particular I/O requests made by the package (specifically .TRAN and .MTAPE), either MTA. or MT. (Atlas Lab version) should be assigned before loading. Both slots should be assigned to the handler even if only one is used by the calling program (This is because the Linking Loader will load the handler assigned the unused slot anyway and will therefore waste space). For example
$A MTAO 1/MTA1 7
(for assignments see Ref 1 (Advanced Monitor) p4-9)
Correct Initializing
Before any reference (other than selection) is made to a particular slot, an initializing routine must be called; IRMT, IWMT initialize for reading, writing respectively. If the handler MTF. is used, there are restrictions - viz:- after IWMT moving a tape forwards without reading it (ie using SKPRMT or SKPFMT) causes a system error message I0PS6.
Also the behaviour of CLSEMT depends on whether IRMT or IWMT has been called.
It should be noted that the restriction described above is handler-dependent. If there is any doubt at any time about what any particular handler allows, there is a Fortran program MAGMOV, which tests out the various routines in MAGTAP according to commands from a user at the keyboard. JRG has details. It makes use of routines in TIO (see 2.2).
Instructions for assembling
There is a binary version of MAGTAP on the library tape which should normally be used. It allows I/O via slots 1 and 7 only and assumes that the commands for moving forward or back to a filemark are not available in the magnetic tape handlers (this latter does not affect the appearance of the package to the user). The information in this section is for someone wishing to reassemble the file.
The source form includes the following conditional assembly parameters
Name Present value Use SOFTMF 0 Tested for absence or presence MTSLT1 7 If present, argument of .I0DEV MTSLT2 1 If present, argument of .I0DEV MTSLT3 undefined If present, argument of .I0DEV MTSLT4 undefined" If present, argument of .I0DEV . . . . . . . . . . . . . . . . . . . . . . . . MTSLT9 undefined If present, argument of .I0DEV
Alternative courses of action are:-
(i) If the system macro .MTAPE, at some stage, allows spacing to a filemark, then assemble with SOFTMF undefined.
(ii) If different .DAT slots are wanted, then assemble with other numbers assigned to any of the group MTSLT1, .... , MTSLT9.
Example
MTSLT 4=2
MTSLT5=4
MTSLT6=6
ctrlD
will cause
.IODEV 2,4,6
to be assembled.
It is possible to have no .DAT slots defined at all, in which case a dummy MACRO program must be assembled to supply the .IODEV's.
Routines in detail
(i) SUBROUTINE BKSFMT(ISKPFA) causes the selected tape to be moved back to just before previous filemark. One filemark is passed, whatever the initial position of the tape, unless tape hits load-point first.
Output
ISKPFA=-1 if tape is moved back to load-point before a filemark is found (tape is left at load-point).
0 otherwise.
Retained Information
Selected slot number; initially 7.
(ii) SUBROUTINE BKSRMT (ISKPFA) causes selected tape to be moved back one record.
Output
ISKPFA=-1 if tape already at load-point (no movement).
ISKPFA=0 if record passed is a data record.
ISKPFA=1 if filemark passed.
Retained Information
Selected slot number.
(iii) SUBROUTINE CLSEMT "closes" selected tape.
Description
After IRMI, routine has no effect except chat IRMT or IWMT is necessary to subsequently access the tape.
After IWMT, 2 filemarks are written and the tape is positioned between them. IRMT or IWMT is necessary to subsequently access the tape.
Retained Information
Selected slot number.
(iv) SUBROUTINE FLMKMT writes a filemark to the tape attached to currently selected slot. Filemark is written at the current position.
Retained Information
Selected slot number.
(v) SUBROUTINE INITMT is identical to IWMT. Its name is retained for compatibility with an earlier version of MAGTAP.
(vi) ROUTINE IRMT causes selected device number to be initialized for reading.
Retained Information
Selected slot number.
(vii) SUBROUTINE IWMI causes selected device number to be initialized for writing. See 'Correct Initializing' above for a note of the routines that cannot be used after IWMT.
Retained Information
Selected slot number.
(viii) SUBROUTINE MODEMT(JMODE) sets parity and density and channel for selected device slot number.
Input
JMODE is a code number interpreted as follows:-
JMODE Channel Parity Density(bpi) 0 7 EVEN 200 1 7 EVEN 556 2 7 EVEN 800 3 9 EVEN 800 4 7 ODD 200 5 7 ODD 556 6 7 ODD 800 7 9 ODD 800
Description
Subsequent routine calls with the same selected device number will assume the channel, parity and density as tabled above.
The 9-channel settings are inapplicable at Atlas.
(ix) SUBROUTINE READMT(IDRDADR,IRDLNG,IRDERR,IRDALN) reads into core the next record on the selected tape.
Input
IRDLNG is the maximum record-length allowed.
Output
IRDADR is the first variable in the block of core to be filled; for most uses of the routine, it would be an array element.
IRDERR is set as follows:-
-3 if record too long (number of 6-bit characters in record > 3IRDLNG). Tape moved past long record.
-2 if read error (8 attempts to reread are made before the routine gives up and returns this value; tape is left before bad record).
-1 if tape at end-of-tape. (tape not moved)
0 if read successful (tape positioned after record).
1 if filemark found (tape positioned after filemark)
IRDALN is actual length (in words) of record read (if record not too long).
Description
The 6-bit bit-groups (for 7-channel operation) in the next record on the selected tape are read without modification and without headers into the specified buffer; IRDADR is the first location of the buffer. The bit-groups are packed 3 to a word. If the number of characters is not a multiple of 3, the unused character positions in the final word contain zeroes. Note that, for this reason, the precise number of characters is not available to the program, unless it is known that all the bit-groups in the record are non-zero.
Example
Suppose that the selected tape consists of records each containing 26 stripes which represent the 26 6-it ASCII codes corresponding to the alphabet. Then after the following sequence:-
INTEGER LETTRS(9)
CALL IRMT
CALL RWNDMT
10 CALL READMT(LETTRS(1),10,IERR,IRDALN)
IF (IRR .EQ. 0) GOTO 20
IF (IERR .NE. -1) GOTO 10
END OF TAPE
PAUSE 1
.
.
.
C RECORD READ OK
20 PAUSE 2
.
.
.
if 'PAUSE 1' is printed, the tape consists wholly of bad records or end-of-file marks; if 'PAUSE 2' is printed, then one record has been successfully read, the tape is positioned after that record, IRDALN contains 9 and the array LETTRS contains the following:-
element index octal representation_ of value
1 010203
2 040506
. .
. .
. .
8 262730
9 313200
Retained Information
Selected slot number.
(x) SUBROUTINE RWNDMT causes tape attached to selected slot to be rewound back to its load-point.
Retained Information
Selected slot number.
(xi) SUBROUTINE SKPFMT(ISKPFA) causes selected tape to be spaced forward until immediately after the following filemark.
Output
ISKPRA = -1 if tape already at end-of-tape (no movement)
ISKPRA = 0 otherwise.
Retained Information
Selected slot number.
(xii) SUBROUTINE SKPRMT(ISKPAG) causes selected tape to be spaced forward one record.
Output
ISKPAG= -1 if tape already at end-of-tape (no movement)
ISKPAG= 0 if data record skipped.
ISKPAG= 1 if end-of-file mark skipped.
Retained Information
Selected slot number.
(xiii) SUBROUTINE SLCTMT(IDEV) causes subsequent input/output using the package to be transferred via .DAT slot IDEV.
Input
IDEV. This should be either 1 or 7. If no call of SLCTMT is made then selected slot number is assumed to be 7,. Note that after the first call to SLCTMT for a particular slot, either IRMT or IWMT must be called before any other routines.
(xiv) SUBROUTINE WRTEMT(IWRADR,IWRLNG,IWRERR) writes a record from core to tape attached to selected slot number.Input
IWRLNG is the number of words to be output.
output
The variable IWRADR is the first location of the area in core to be copied out; for most uses of this routine, it will be an array element.
IWRERR is set as follows:-
=-2 if write error (retried 8 times; this value is only set if 8 failures - tape positioned as on entry).
=-1 if end-of-tape bit (tape is not moved).
=0 if write was successful (tape positioned after the written record).
Description
An attempt is made to write the IWRLNG words of core, starting at IWRADR, to the selected tape at its current position. If successful, each word is recorded as 3 6-bit groups; the total number of 6-bit groups written is thus always a multiple of 3. The record will not contain any extra heading information.
Retained Information
Currently selected slot number.
(by JRG in MACRO-15)
File TTIO is a collection of routines for input to and output from an alphanumeric peripheral (for instance DMAC table, display keyboard, teletype). The most frequent use of the package is as a replacement for BCDIO (see Ref 6 (Fortran programming pp 8-2 to 8-5) the standard PDP-15 Fortran I/O package. TTIO is much smaller, provides free-format I/0 and is intended to be more convenient to use at a teletype.
Size
415 locations.
Routine summary
(a) Initializing
INITTY ... initializes slots 3 and 4
(b) Errors
ERRVAR ....specifies variable in user program which is set in case of error
(c) Input
KBRDLN .... inputs a record of characters
WTTY .... checks if input initiated by KBRDLN is complete
NXTCH .... returns ASCII code of next character in record previously read in by KBRDLN
KBRDLN .... calculates integer from decimal digits in record previously read in by KBRDLN.
(d) Output
TYPBFA .... outputs a record of packed characters, terminated by a control character; requires 2 spare words for header information.
TYPBFH .... outputs record of characters stored one per word; terminated by word count. Needs 2 spare words.
TYP8 .... outputs an octal number.
TYPCH .... outputs a single character.
TYPSTR .... outputs a specified Hollerith string.
NEWLIN .... one newline.
NLS .... several newlines.
DUMP .... types an area of store in octal.
Restrictions
To provide the facilities mentioned in the heading to this section, there are certain limitations which a user should be aware of:-
(a) Only one device slot is available for each transfer direction, slot 3 for input and slot 4 for output.
(b) Using a FORMAT statement elsewhere in a program, which used TIO, would cause BCDIO to be loaded as well from the system library; the space saving would then be lost.
(c) TTIO does not a precise layout to be specified so easily as a FORMAT statement and the output of a complex sequence of data types, becomes a long sequence of subroutine calls.
(d) Hollerith strings longer than 5 characters (see TYPSTR) require setting up in a DATA statement.
(e) The method of dealing with read errors (see KBRDLN) is designed for input from teletype and a bad record from a non-interactive input device would be lost.
Use of package
Before any routine is used, INITTY must be used to initialize both device numbers.
Control X
If the monitor in use responds to the commands 'VT ON' and 'ctrl X' (see Ref 4 (DOS-15) pp 3-17 to 3-19), input from and output to the control teletype can be made to appear on the VT15. However, this facility will cause chaos if other graphical output is produced!
Routine descriptions
The routines are described in alphabetical order.
(i) SUBROUTINE DUMP(IADDR,N) causes an area of store to be output in octal.
Input
The variable IADDR is the first location of the area in core to be output. This would normally be an array element. N is the number of words to be output.
Description
N words of core are output in octal form to device slot 4, 8 to a line with one space between each number - (8(06,1X)) in Fortran FORMAT terminology. There is a strict conversion of bits to octal digits - negative numbers begin with 4,5,6 or 7 not a '-' sign. The routine begins and ends by outputting a newline.
Example
The following instructions:-
INTEGER IA (18)
DO 2o I=1,18
20 IA(I)=I-10
CALL DUMP (IA(1), 18)
causes the following output:-
newline 777767 777770 ................... 777776 777777 000000 000001 ............ 000006 000007 000010 newline
(ii) SUBROUTINE ERRVAR(IERR) specifies a variable in the calling program, which is subsequently used for error conditions.
Input /Output
The address of IERR is stored. ERRVAR itself does not cause any information to be written to IERR.
Description
After 'CALL ERRVAR(I)', any subsequent call to KBRD10 (see below) causes certain information to be recorded in I. This information can be accessed by the routine which called ERRVAR; other routines can access it if I is declared to be COMMON.
(iii) SUBROUTINE INITTY is necessary before any data transfer takes place using TTIO.
Description
(a) The routine executes a .INIT to device slots 3 and 4.
(b) Under certain circumstances, the typing of 'ctrl P' on the control teletype causes a program to continue executing from (and including) the last call to INITTY. This will not work if either a PAUSE or a normal Fortran I/O statement has been executed since the last call to INITTY; if the latter, then the message .OTS 10 will be typed (if using F4S) and control will return to the monitor.
(iv) SUBROUTINE KBRDLN(IBUFF,IWAIT) reads a record of characters from device number 3.
Input
If IWAIT=0, control is returned immediately to the calling program; the program must call WTTY before the contents of the buffer can be accessed.
If IWAIT≠0, control is returned to the calling program only when input is complete; it is not in that case necessary to call WTTY.
Output
IBUFF is the first location of the buffer to be used for input. Characters are stored in 5/7 ASCII from the 3rd word of the buffer onwards. If from teletype, 34 words should be allocated to the buffer, if the whole width of the paper is expected to be used.
Description
(a) Input is initiated from device number 3.
(b) If IWAIT=0, control is returned to the calling program.
(c) If IWAIT≠0, routine waits in a loop until input is complete; input must be terminated by altmode or carriage return. The first 2 words contain header information and are followed by the characters themselves.
(d) If read errors occur, a message '????' is output on device number 4 and the routine attempts to reread the record. The effect depends on the device. If input is from a keyboard, the routine waits for the user to retype the line. If from a non-interactive device such as the paper tape reader, the next line is read.
(e) When input is complete and error-free, the user can access the contents of the buffer as if characters had been read using A5 format. Alternatively KBRD10 and NXTCH can be used (see below), in which case nothing need be known about the way characters are stored.
(f) If input is from control teletype, the last character typed in the current line can be deleted using the RUBOUT key (echoed '\') and the whole line can be deleted using 'ctrlU' (echoed'@'). Behaviour on other keyboards, depends on the particular handler being used (Sprogs paper 7 describes some keyboard handlers).
Example
INTEGER IARRAY(34)
LOGICAL MATCH
CALL KBRDLN (IARRAY, 1)
DO 20 1=3,33,2
IF (MATCH(IARRAY(I), 5HABCDE)) GOTO 30
20 CONTINUE
STOP
30 CONTINUE
PAUSE
.
.
.
The above program pauses and types 'PAUSE 1' if there is a word pair in the input record containing the 5 characters 'ABCDE'. (MATCH is assumed to be a LOGICAL FUNCTION which compares the 36-bit pattern 5HABCDE and the 36-bit pattern IARRAY(I) and IARRAY(I+1).
(v) FUNCTION KBRD10(I) inspects the buffer last input by KBRDLN and converts a string of decimal digits (if present) to the corresponding number.
Value of the function
= the number itself if digits are found
= 0 otherwise (if an illegal character is found first)
Input
The Fortran compiler requires a dummy argument; it has no other significance.
Output
Suppose the statement 'CALL ERRVAR(I)' has been obeyed (see ERRVAR above). Then I can equal (suppose N >=0).
N if number correctly terminated by a character with ASCII code N
-N if premature terminating character with ASCII code N.
This information is inaccessible to the program if ERRVAR has not been called.
Description
The function obtains the next character in the buffer and repeats the process until terminated in some way as described below.
Only spaces or a minus sign may occur before a sequence of digits. Any other character (the terminator) causes:-
(a) IERR = - (code of terminator)
(b) value of function=0
(c) exit; 'next character' is the one following the terminator.
If no premature terminator, a sequence of digits possibly preceded by spaces or immediately preceded by '-' will be terminated by any non-digit. In this case:-
(a) IERR=code of terminating character.
(b) value of function= sequence of digits converted to a number.
(c) exit; 'next character' is the one following the terminator.
If a sequence of digits represents a number satisfying
n > 131071 or n < -131071, then an incorrect result will be stored.
It is apparent that, if KBRD10 is being used to read in a sequence of digits, only one delimiter is necessary; in fact 2 non-space delimiters will cause premature termination.
Note
KBRD10 cannot be used without KBRDLN.
Examples
* denotes preceding characters that have already been accessed. The 'next character' on entry is the first character after the last '*' is an irrelevant subsequent character. * denotes a space.
Input String Result of IERR code character Next character
function on exit
*** ^^1237/... 123 63 ? /
^^X-205YZ.. 0 -88 X -
***-^205//... 0 -32 space 2
*-205^4 .... -205 32 space 4
000131000 CR 131000 13 CR undefined
1XY... 1 88 X Y
Retained Information
Pointer to the current buffer. This is set initially by KBRDLN and will be overwritten by a further call to KBRDLN. Pointer to the 'next character' in the current buffer. After a call to KBRDLT, this refers the first character in buffer. Pointer is changed only by NXTCH (see below) or KBRD10. Pointer to error location set by ERRVAR.
(vi) SUBROUTINE NEWLIN outputs one newline on device number 4.
Description
The routine uses the .CLOSE system macro, which for a teletype simply issues a newline. If another output device is being used, the specification of .CLOSE in the description of the relevant handler will give the effect. of NEWLIN.
(vii) SUBROUTINE NLS(I) causes I newlines to be output on device number 4.
Input
I is the number of newlines to be output.
Description
The routine calls NEWLIN I times. The remarks made under 'Description' of NEWLIN apply here.
(viii) FUNCTION NXTCH(I) obtains the next character from the buffer last filled by KBRDLN. Te value of the function is the ASCII code of the character obtained.
Input
A dummy argument is necessary when using DOS Fortran. For example:-
I=NXTCH(I)
Description
NXTCH accesses the 'next character' in the buffer. Immediately after KBRDLN is called the 'next character' is the first in the buffer. On exit from NXTCH, the 'next character' is the one following the one just read. KBRD10() is the only other routine to change the 'next character'.
The ASCII character code table can be found in Ref1 (Advanced Monitor) Appendix A.
Retained Information
Pointer to current input buffer - set by KBRDLN. Pointer to 'next character' in input buffer - moved forward NXTCH and KBRD19, reset by KBRDLN.
(ix) SUBROUTINE TYPBFA(IBUFF) outputs to device number 4 the characters packed in a specified buffer.
Input
IBUFF is the first location of the buffer to be output. This is normally an array element.
Output
IBUFF and the next core location are used by the routine to store header information which is then used by the I/O system. The user need not be aware of their contents.
Description
This routine and TYPBFH (see below) are not strictly essential to an outside program (in contrast to KBRDLN for input). They are called automatically by TYPCH, TYPSTR and TYP8.
The core area, starting at IBUFF (except the first 2 locations) is assumed to contain a sequence of characters in 5/7 ASCII form. When all previous output to device slot 4 is complete, the routine initiates output from the specified buffer. The sequence of characters is output on device number 4 until a control character is encountered (carriage return or altmode).
The routine is left immediately, without waiting for output to finish; the character by character output is dealt with by the interrupt system.
(x) SUBROUTINE TYPBFH(IBUFF,LENGTH) outputs to device slot 4 characters stored one per word in a specified buffer.
Input
IBUFF is the first location of the buffer to be output. This will normally be an array element.
LENGTH is the number of words that the buffer contains and should be even; if odd it will be rounded down. The number LENGTH should include the word-pair used for header information.
Output
IBUFF and the following location are used by the routine to store header information by use by the I/O system. The user need not be aware of their contents.
Description
This routine, like TYPBFA, is not essential for an outside program; it is called automatically by TYPCH and TYP8. The core area starting at IBUFF (missing the first 2 locations), is assumed to contain a sequence of characters stored in 7 it ASCII stored one to a word.
Output is initiated when all previous output to slot 4 is complete. The sequence of characters is output on device slot 4 until the word count LENGTH is satisfied; a carriage control character is not necessary. The routine is left as soon as the output is initiated; the actual character by character output is performed by interrupt routines in the Advanced Monitor.
Example
INTEGER IARR(28)
C ASCII CODE FOR 'A' IS 65.
C THE FOLLOWING INSTRUCTIONS OUTPUT THE
C ALPHABET ON DEVICE 4 AND POSITION
C THE PRINTER CARRIAGE IMMEDIATELY AFTER
C THE '8'.
DO 20 I=1,26
20 IARR(I+2)=64+I
CALL TYPBFH(IARR(1),28)
etc
Special hardware
EAE.
(xii) SUBROUTINE TYPCH(ICH,NLINE) causes a character to be output on device slot 4.
Input
ICH is the 7-bit ASCII code of the character to be output. NLINE=0 if a newline is wanted after character. Otherwise the teleprinter carriage remains immediately after the output character.
Description
(a) Routine waits for previous output to finish.
(b) The character code is copied to a buffer and output is initiated using TYPBFH.
(c) A newline command is added if NLINE=0. In this case routine waits for completion. Otherwise (NLINE not=0) routine is left immediately.
Example
INTEGER INPUT(34)
INTEGER BKAROW
C SET UP ASCII CODE FOR '+'
DATA BKAROW/95/
CALL TYPCH(BKAROW,1)
C (KBRDLN DESCRIBED ABOVE)
CALL KBRDLN(INPUT(1),1)
The Fortran statements cause '+' to be typed on device 4 and wait for a typist to input a line with the teleprinter carriage starting immediately after the '+1' (This assumes that slots 3 and 4 are assigned to the same device, that device being a teleprinter). It is useful in a program as a signal for the program user to begin typing.
Special hardware
Index register
EAE.
(xii) SUBROUTINE TYPSTR(STR,LENSTR,NLINE) outputs the specified text on device slot 4.
Input
STR is the variable containing the string to be output. The string is stored in 5/7 ASCII.
LENSTR is the number of characters to be output (can be a multiple of 5).
NLINE is described under TYPCH.
Description
(a) Routine waits for previous output to finish.
(b) Word pairs are copied to a buffer until LENSTR characters have been copied.
(c) A suitable control character (if NLINE=0 then 'return' otherwise 'altmode') is stored in the final character position of the final word pair copied. If this position is used, the control character is stored in the next word pair. None of the LENSTR characters are lost, some trailing spaces may become included.
(d) Output is initiated using TYPBFA and routine is left immediately.
This routine is normally more useful than TYPBFA since no allowance needs to be made for header-pairs and the routine user does not need to insert control characters; all this is organized within the routine. One by-product is that literal Hollerith strings can be used as arguments.
Examples
CALL NEWLIN
CALL TYPSTR(5HABCDE,0)
causes the output of
ABCDE ↑
where '↑' denotes the final position of the teleprinter carriage.
For longer Hollerith strings, it is necessary to use a DATA statement thus:-
REAL ALPHAB(2)
DATA ALPHAB(1),ALPHAB(2)/5HABCDE,3HFGH/
CALL TYPSTR(ALPHAB(1),8,1)
This will cause the output of
ABCDEFGH ↑
Notes on last example
(a) 9 characters are output since altmode is stored in final character position.
(b) 9th character is a space since Hollerith strings, which do not have an exact multiple of 5 characters, are filled out with spaces by the Fortran compiler.
Special hardware
Index register.
(xiii) SUBROUTINE TYP8(N,NLINE) outputs a number in octal representation to device number 4.
Input
N is the number to be output.
NLINE is described under YPCH.
Description
(a) Routine waits for previous output to finish.
(b) N is converted to 6 characters which represent N in octal. One space character follows.
(c) Output is initiated using TYPBFH.
(d) If NLINE=0, a newline is added and routine waits for completion. Otherwise, routine is left immediately.
Examples
Argument N as Fortran integer Characters output -2 777776^ 10 000012^ 0 000000^
Special hardware
Index register.
(xiv) LOGICAL FUNCTION WTTY(I) returns the truth value of the statement "Input initiated by KBRDLN is complete".
Input
Dummy argument required; it has no significance.
Description
This routine is used if KBRDLN has been called with 2nd argument equal to 0; otherwise it is unnecessary.
(a) If input is not complete, return with value .FALSE.
(b) Otherwise (if input complete), function checks for read errors. If read errors occur, '????' is output on device slot 4 and routine attempts to reread. Function returns with value .FALSE.
(c) Otherwise (if no read errors), return with value .TRUE.
Example
Suppose some calculation or data transfers are to be made while input is taking place. We might proceed as follows:-
INTEGER IBUFF(34)
LOGICAL WTTY
CALL KBRDLN(IBUFF(1),0)
.
.. other calculation
.
.
10 IF(WTTY(I))GOTO 20
GOTO 10
20 CONTINUE
C AT THIS POINT THE PROGRAM CAN NOW ACCESS
C THE CONTENTS OF THE BUFFER 'IBUFF', PERHAPS
C USING NXTCH OR KBRD10.
Retained Information
The 2 actual arguments used the last time KBRDLN was called.
in Fortran by JRG) makes it possible to output decimal digits using TTIO (section 2.2)
(i) SUBROUTINE TYP10(N,NLINE) causes a number to be output on device slot 4 as a sequence of decimal digits.
Size
40 locations.
Input
N is the number to be output.
NLINE=0 if a number is wanted after the number. Otherwise the teleprinter carriage is positioned so that one space occurs between the number and the next item.
Description
(a) N is converted to a string of decimal digits with leading zeroes suppressed and a preceding '-' if N is negative. One space follows the digits.
(b) Output is initiated using TYPBFH (see 2.2).
(c) If NLINE=0, a newline command is obeyed and routine waits for completion.
(d) Otherwise (if NLINE not=0), routine is left immediately.
Note
A fixed field-width cannot be specified; only sufficient digits to represent the number are output.
External References
TOBF10 see below.
TYPBFH in TTIO (section 2.2).
(ii)SUBROUTINE TOBF10(N,IBUFF,LENGTH) converts a number into a string of decimal digits stored one per word.
Size
136 locations.
Input
N the number to be converted.
Output
IBUFF is an array name. The characters are stored in IBUFF(1) onwards. One space character follows the decimal digits and a null (ASCII code 00) follows the space. Leading zeroes are suppressed and a minus sign precedes if N is negative.
LENGTH= (the number of characters produced) + 1.
Examples
Before - N After - IBUFF LENGTH
Element Value (after)
23 1 50 4
2 51
3 32
4 0
---------------------------------------------
-400 1 45 (minus) 6
2 52
3 48
4 48
5 32
6 0
(in MACRO-15 by JRG)
SUBROUTINE TIMEP(ISECS,IPULSE,IOFF) allows the current state of the clock to be available to a Fortran program. It works in the same way as the Fortran system routines TIME and TIME10 (see Ref 6 (Fl Programming) pp 8-15,8-16), but gives a result accurate to 1/50th second (1 clock pulse).
Output
On exit from TIMEP,ISECS,IPULSE and IOFF=0. However ISECS and IPULSE are subsequently updated by the clock.
Description
The routine itself simply clears all 3 arguments, stores their addresses internally and winds up the clock. At any time after (while IOFF=0), ISECS and IPULSE contain the number of seconds and clock pulses respectively that have elapsed since TIMEP was called. For example if ISECS=2 and IPULSE=25, then 2½ seconds have elapsed.
The clock is stopped by assigning to the actual parameter of TIMEP corresponding to IOFF a non-zero number. The 2 "hands" remain frozen at the value they had when this assignment took place. The clock should be turned off before reading it (Consider the effect of reading IPULSE at 3.98 seconds and ISEC at 4.00).
This routine destroys any effect of TIME and TIME10 and vice versa; no 2 of these 3 routines can be in effect simultaneously.
Example
INTEGER SECNDS,PULSES,OFF
.
.
.
CALL TIMEP(SECNDS,PULSES,OFF)
DO 10 I=1,500
10 CALL SUBROT(I)
IOFF=1
WRITE(5, 100) SECNDS, 2*PULSES
100 FORMAT(1H ,I5,1H.,I2,6H SECS.)
.
.
.
causes the time used by the loop to be output in a form such as:-
^^^^5.78^SECS
The clock will be stopped at the end of the sequence of instructions.
(in MACRO-15 by GAE)
3.1 FUNCTION ISTORE(IA) finds an area of free core and has its value the length of the piece found.
Size
60 locations (decimal).
0utput
IA must be declared as a one-dimensional array in the calling routine.
Description
The function searches for the largest consecutive piece of core unused by the user program, resident monitor and previous (if any) calls to IST0RE. The piece if found will lie wholly within one 4K page. When a piece is found, the array header block belonging to IA is modified in such a way that IA(1) is the first location of the piece found. The piece of store previously referenced by IA is subsequently inaccessible to the program.
If all store has been allocated, the value of the function becomes zero and the array header belonging to IA is unchanged.
Note
If DDT is used to load a program which
(a) calls IST0RE
(b) uses a named COMMON block,
then the program will fail in unpredictable fashion due to a bug in DDT.
Example
Suppose we want to build up a display file in a fresh area of core. We could obtain the space as follows:-
C NUMBER IN INTEGER DECLARATION IS IRRELEVANT
INTEGER VT15(1)
J=ISTORE(VT15)
C CHECK THAT SOME CORE WAS FOUND
IF (G .GT. 0) GOTO 10
WRITE(5, 100)
100 FORMAT(15H NO MORE STORE!)
PAUSE 1
10 WRITE(5,101) J
101 FORMAT(1H ,I5,15H LOCATIONS FOUND)
PAUSE 2
Retained Information
A note of areas of core previously allocated to the program by ISTORE (so that they aren't reallocated).
Special hardware
Index-register.
(from FRAH in Fortran)
SUBROUTINE SC4020(IPARAM)
INTEGER IPARAM
INTEGER XPOS,YPOS,XMIN,YMIN,XMAX,YMAX
COMMON /SC/XPOS,YPOS,XMIN,YMIN,XMAX,YMAX,
1 ISCBUF(3l2),IBFPTR,ISVR,INCR,IBRT,TBLNK,
2 IROT,IOFSET,LBTS,ITER,INV
This routine generates a frame of SD4020 output equivalent to a specified display picture.
Size
718 words.
External References
The following routines are described in section 4.2:-
TODXDY,SLCTCM,IGRSRD,PLOTCH,ADVFLM
SMALLR is described in section 1.1.
INBITS is described in section 1.3.
MAGTAP is described in section 2.1.
FTRDSI is described in section 4.5.
The following routines are also required:-
SEEVEC,DRAWVC,INSVWD,TOBUF,SHRTVC.
They fill 924 words
One COMMON nlock is used, namely /SC/. A list of elements appears in the heading of this section. To use SC4020, the only variables which need be set are XMIN, YMIN, XMAX and YMAX. See section 'Input'. A more detailed description of the others appears in section 4.2.
Input
IPARAM is the first element of a display file as set up by the DEC graphics package VTPRIM. It will be assumed that the file was set up by a call of the form:-
CALL DINIT(IPARAM)
IPARAM is normally an array element.
XMIN,YMIN,XMAX,YMAX(in COMMON block /SC/) must on entry contain the VT15 coordinates of the 2 opposite corners of a rectangular window, with its edges parallel to the edges of the picture. Output to the SD4020 tape will be scissored by this rectangle. Normally XMIN=YMIN=0 and XMAX=IMAX= 1023.
Always 0 =< min(XMIN, YMIN) and max(XMAX,YMAX) =< 1023
Description
Each display order in turn, beginning at location addressed by ((address of IPARAM) + 2) (routine assumes VTPRIM format), is sent to the magnetic tape attached to the currently selected .DAT slot.
(a) Lines are translated precisely; VT15 line brightness is converted to the equivalent number of overstrikes.
(b) A character in the display file is mapped onto the equivalent SD4020 hardware character if there is one.
(c) V15 features which have no SD4020 equivalent are ignored. For instance, broken lines on the VT15 appear solid on the SD4020.
(d) Display subroutine calls are ignored.
The routine uses WRTEMT (see MAGTAP in 2.1) for its output. The required .DAT slot must be selected (SLCTMT in MAGTAP) and initialized (IWMT in 2.1) before calling SC4020.
No camera is selected by the routine. It can be selected before entering by calling SLCTCM (see 4.2).
Retained Information
Contents of the COMMON block /SC/
By FRAH in Fortran)
These routines are used to send SD4020 orders to the currently selected magnetic tape (select by SLCTMT in 2.1).
Common
The routines make use of COMMON block /SC/ defined as follows:
INTEGER XPOS,YPOS,XMIN,YMIN,XMAX,YMAX
COMMON /SC/XPOS,YPOS,XMIN,YMIN,XMAX,YMAX,
1 ISCBUF(342),IBFPTR,ISVR,INCR,IBRT,
2 IBLNK,IROT,IOFSET,LBTS,ITER,INV
The following have to be set on entry to any of these routines:-
(a) XMIN, YMIN define the minimum raster coordinates of the rectangular window. These are V15 coordinates; XMIN,YMIN define the lower left hand corner of the picture to be recorded. They are normally 0.
(b) XMAX,YMAX define the maximum raster coordinates of the rectangular window. They are normally 1023.
(c) XPOS,YPOS must be set before the first drawing routine (TODXDY or PLOTCH). They define the origin of plotting.
(d) IBRT defines the number of overstrikes required.
(e) INV determines line visibility (=1 if visible) (=0 if invisible)
(f) INCR controls character spacing and is normally set to 1.
(g) Currently IBLNK,IROT,IOFSET,LBTS,ITER are not used.
Routine descriptions
{i) SUBROUTINE TODXDY(IX,IY) causes a vector to be added to the SD402O tape buffer.Size
498 words.
Input
IX and IY are the X,Y beam movement respectively. The line drawn is from (XPOS, YPOS) to (XPOS+IX, YPOS+IY). INV determines visibility. The units are VT15 raster units.
(ii) SUBROUTINE SLCTCM(I) causes a 'select camera' order to be added to the SD4020 buffer.
Size
28 words.
Input
I is the camera to be selected.
I=1 for microfilm, =2 for hardcopy, =3 for both
(iii) SUBROUTINE IGRSRD fills the current SD402O buffer with NOP's (code 12) and causes the contents to be written to magnetic tape. After calling this routine no graphical output remains in the SD4020 buffer.
Size
47 words (decimal).
(iv) SUBROUTINE PLOTCH(ICHR) adds a 'plot-hardware-character' order to the SD4020 buffer.
Size
242 words (decimal).
Input
ICHR is the ASCII code of the character to be added. The equivalent SD4020 code is added.
Description
The order added to the buffer is 'plot character equivalent to ICHR at position (XPOS,YPOS)'. After plotting, XPOS and YPOS are assumed to be set as follows:-
XPOS ← XPOS + 7INCR, YPOS ← YPOS
Carriage return causes (in VT15 coordinates):
XPOS ← 0, YPOS ← IPOS-14*INCR.
(v) SUBROUTINE ADVFLM causes a 'frame advance' order to be added to the SD4020 buffer.
Size
17 words.
External references (applies to all routines in 4.2)
SEEVEC,DRAWVC,TOBUF (together they fill 668 words).
SMALLR (see 1.1)
MAGTAP ( see 2.1 ).
By FRAH in Fortran
Program TESTT converts, under commands from an input stream, an SD4020 tape which contains Advance Repeat orders to one which has them removed.
Size
367 words (decimal).
External references
READR, WRITER (not described in this paper) (315 words).
MAGTAP (see 2.1).
Description
TESTT is a main program. It uses .DAT slots 7 and 8 for the input and output tapes respectively. Note that for this reason the program requires a different binary version of MAGTAP to that described in 2.1 (See 'instructions for assembling' in 2.1).
The routine reads numbered commands from .DAT slot 4; it can be assumed that they are read using formatted READ as follows:-
READ(4, label) I,J,,L,M
label FORMAT(I1,4I5)
The value of I determines the type of command as follows:-
I=1 Initialize input tape as 556 bpi and odd parity
I=2 Initialize output tape as 556 bpi and odd parity
I=3 Cause output tape to be moved to the next filemark
I=5 Write filemark on output tape
I=6 Records are read from the input tape and recorded on the output tape until one of the terminating conditions described below is satisfied. An Advance Repeat order on the input tape causes the input tape to be reversed to the previous Advance Repeat order; the records in between are read and again written to slot 8. The process is repeated as many times as the argument of the second Advance Repeat. The tape on slot 8 becomes an unwound version of the tape on slot 7. Copying is terminated by one of the following conditions:-
(a) The number of records input >= L
(b) The number of records output >= M
(c) The number of filemarks read >= K
(d) The number of advance repeat sequences >= J
Null records are ignored by the command I=6.
I=7 Backspace a record on the output tape. Unwanted filemarks can be removed with this command.
These 7 commands allow flexible movement and unwinding of tapes containing Advance Repeats.
(by FRAH in Fortran)
SUBROUTINE PRSBFL(ISBFL,ISTRSB)
INTEGER ISBFL(1) ,ISTRB
This routine prints the contents of a VT15 display file.
Size
250 words (decimal).
External References
SMALLR (see 1.1)
DSPCD (not described in this paper) (173 words)
FTRDSI (see 4.5).
Input
The display file is contained in the array ISBFL. It is assumed that the display file has been produced using the DEC package VTPRIM and that the first word of the display file is ISBFL(ISTRSB).
Description
The display file should have been initialized by a subroutine call to VTPRIM of the form:-
CALL DINIT(ISBFL(ISTRSB))
or CALL <subpicture routine name>(<arg.list>,ISBFL(ISTRSB))
If VTPRIM is not used, the following assumptions made by the routine about the display file should be noted:-
(a) ISBFL(ISTRSB) contains the length; in other words the final display order - a jump to the beginning of the file - resides in ISBFL (ISTRSB+ ISBFL(ISTRSB))
(b) ISBFL(ISTRSB+2) contains the first display order.
The printed interpretation is sent to .DAT slot 4 using Fortran formatted I/O. The following information appears on each line:-
(a) Address of display order,
(b) Octal representation of display order,
(c) Display mnemonic,
(d) Corresponding call to VTPRIM if match is found.
The display mnemonics used in (c) are:-
CHARI Single character CHARS Character string CHRS* Character string indirect PY Point plot Y PX Point plot X GY Graph plot Y GX Graph plot X SV Arbitrary vector (always 2 words) SHAR Short arbitrary vector DNOP No-operation PRMi Parameter word i SKPi Skip word i SKIP Unconditional skip SAVE Save RSTR Restore Vi Basic Vector BSV Basic Short Vector DJMP Display Jump DJMP* Display Jump indirect DJMS Display Jump to subroutine DJMS* Display Jump to subroutine indirect
If a VTPRIM call is found in part (d), it usually corresponds to a sequence of more than one display order. Routine name is included opposite the first display order in the sequence.
(by FRAH in Fortran)
SUBROUTINE FTRDS (ISBFWD,INVSTG,ITYPE) compares a sequence of given display orders with those produced by VTPRIM to find a match.
Size
269 words.
Input
The variable ISBFWD contains the address of the first display order in the sequence to be matched.
Outputs
ITYPE on exit contains a number dependent on the type of VTPRIM call matched.
INVSTG contains the number of display orders matched, except when ITYPE = 0 or 11.
The meaning of ITYPE is as follows:-
ITYPE SUBROUTINE CALL
0 No recognition
1 COPY subroutine with SAVE/RESTORE
2 COPY subroutine without SAVE/RESTORE
3 TEXT
4 PRAMTR
5 GRAPH GX
6 GRAPH GY
7 LINE VI type
8 LINE Arbitrary vector
9 LINE Approximation
10 SETPT
11 Display file return sequence.
Return address is stored in INVSTG
Documents are referred to by number in the paper. A reference will be to either a DEC manual or a Sprogs paper.
(1) Advanced Monitor Software System for PDP 15/20/30/40 DEC-15-MR2A-D
(2) PDP-15 Chain & Execute Utility programs DEC-15-YWZA-DN2
(3) PDP-15 DDT-dynamic debugging technique utility program DEC-15-YWBA-DN1
(4) The preliminary DOS-15 manual (Quote - "This document will be obsolete as of December 1971" (!) - no further manuals received yet)
(5) PDP-15 Fortran IV Operating Environment DEC-15-GFZA-D
(6) PDP-15 Systems: Fortran IV Programming manual DEC-15-KFSA-D
(7) Graphic-15 programming manual DEC-15-ZFSA-D
(8) MACRO-15 Assembler DEC-15-AMBA-D
(9) PDP-15 Systems: Reference manual DEC-15-BRBC-D (Page references are taken from the 4th printing)
(10) PDP-15/20 Software Performance Summary Vol 1 No 1 November 1970
(11) SPROGS Paper 1: The PDP-15 Fortran Graphic Routines - VTPRIM amended by
(12) SPROGS Paper 4: Changes to VTPRIM
(13) SPROGS Paper 7: Some new handlers
(14) PDP-15/20 User's Guide (a booklet) DEC-15-MG2A-D
(15) PDP-15 Utility Programs DEC-15-YWZA-D