Trailing-Edge
-
PDP-10 Archives
-
SRI_NIC_PERM_FS_1_19910112
-
c/user/libord/formac.hlp
There are no other files named formac.hlp in the archive.
FORMAC - A MACRO library for FORTRAN programs Page 1
Description of programs in the library FORMAC
December 29, 1982
Norm Samuelson, 2644
All of the routines described in this document are available in the
relocatable library FORMAC. (The source is in MAC:FORMAC.MAC). To
access any or all of these subroutines, simply add
SYS:FORMAC.REL/SEARCH
to your LOAD, EXECUTE, or DEBUG command, or to the LINK commands used in
loading complex programs.
There are now three variants of FORMAC.
1. FORMAC.REL - traditional version, all LOWSEG
2. FORMAS.REL - sharable version, TWOSEG for use with fortran code
loaded with /SEGMENT:DEFAULT.
3. FORMAP.REL - psected version, psect names are .CODE. and
.DATA. for use with FORTRAN code compiled with the /EXTEND
switch.
All of these routines are designed to be called from FORTRAN programs.
Some can be called from COBOL also. Some are FUNCTIONS, others are
SUBROUTINES (see comments with each one).
The source file contains RUNOFF input to produce this documentation. To
get a copy type the command:
RUNOFF TTY:=MAC:FORMAC.MAC
or RUNOFF LPT:=MAC:FORMAC.MAC
1.0 SHIFT ROUTINES
The following group of FUNCTIONS are special case routines to produce
results equivalent to the strange SHIFT FUNCTION found on CDC 6600 and
7600 computers.
Calling sequence:
SHIFT(W,N) left=circular right=sign extended
or ASH(W,N) left=zero fill right=sign extended
or LSH(W,N) left=zero fill right=zero fill
or ROT(W,N) left=curcular right=circular
where W is a SINGLE WORD quantity to be shifted
and N is the SHIFT COUNT (+=LEFT, -=RIGHT)
The FUNCTION to be used should be declared LOGICAL in the calling
program.
FORMAC - A MACRO library for FORTRAN programs Page 2
2.0 DSHIFT ROUTINES
The following group of DOUBLE PRECISION FUNCTIONS are special case
routines to produce results equivalent to the strange SHIFT FUNCTION
found on CDC 6600 and 7600 computers.
Calling sequence:
DSHIFT(DD,N) left=circular right=sign extended
DASH(DD,N) left=zero fill right=sign extended
DLSH(DD,N) left=zero fill right=zero fill
DROT(DD,N) left=curcular right=circular
where DD is a DOUBLE WORD quantity to be shifted
and N is the SHIFT COUNT (+=LEFT, -=RIGHT)
The FUNCTION to be used should be delcared DOUBLE PRECISION in the
calling program.
3.0 MASK FUNCTION
The MASK function generates a mask of up to 72 bits, similar to the MASK
function on CDC computers.
Calling sequence:
BITS = MASK(NBITS)
where NBITS is integer number of bits in the mask
and BITS and MASK are of the same type (both LOGICAL, both REAL,
or both DOUBLE PRECISION)
Note: If NBITS is negative the mask generated is the complement of that
generated by MASK(ABS(NBITS))
4.0 CSHIFT
CSHIFT is either a SUBROUTINE, or a FUNCTION. It does character
shifting in DOUBLE PRECISION (ie: A10 FORMAT) such that the characters
come out in normal character positions, in spite of the extra bit in
each word.
Calling sequence:
CALL CSHIFT(DPVAR,NUMCH,DPRES)
or DPRES = CSHIFT(DPVAR,NUMCH)
where DPVAR is a DOUBLE PRECISION variable in A10 format
DPRES is the DOUBLE PRECISION result (in A10 format)
NUMCH is the number of character positions to shift
if NUMCH is positive, the characters are shifted
LEFT, END AROUND (ie: rotated).
If NUMCH is negative, the characters are shifted
RIGHT, END OFF with blank fill
on return the contents of DPVAR and NUMCH are un-changed.
NOTE - If called as a FUNCTION, CSHIFT must be declared DOUBLE PRECISION
in the calling program.
FORMAC - A MACRO library for FORTRAN programs Page 3
5.0 TERMINAL CONTROL ROUTINES
These FORTRAN SUBROUTINES take no arguments. A call to ECHO will turn
on echo, a call to NOECHO will turn it off. A call to CTRLO will
restart typeout in case the user stopped it with ^O. (This is a good
idea before typeing error messages).
6.0 IBYTE
IBYTE is a FUNCTION which returns an arbitrary sized byte from any word.
Calling sequence:
IBYTE(WORD,SIZE,LOC)
where WORD is the word containing the desired byte
SIZE is the (INTEGER) length of the byte
and LOC is the (INTEGER) location of the rightmost bit
(bits are numbered from 0 on the left to 35 on the right)
IBYTE should be declared LOGICAL in the calling program.
7.0 PUTBYT
PUTBYT is a SUBROUTINE which puts an arbitrary sized byte into any word.
Calling sequence:
CALL PUTBYT(WORD,SIZE,LOC,VAL)
where WORD is the word to be modified
SIZE is the (INTEGER) length of the byte
LOC is the (INTEGER) location of the rightmost bit
and VAL is the value to be stored
(bits are numbered from 0 on the left to 35 on the right)
8.0 NCHAR
NCHAR is a FUNCTION which returns the Nth character of an ASCII
character string.
Calling sequence:
NCHAR(STRING,NPOS)
where STRING is a variable (or array) containing an ASCII string
and NPOS is the position of the character desired
(starting with position 1 at the left)
NCHAR should be decalred INTEGER or LOGICAL in the calling program.
FORMAC - A MACRO library for FORTRAN programs Page 4
9.0 PUTCHR
PUTCHR is a SUBROUTINE which replaces a character in an ASCII string.
Calling sequence:
CALL PUTCHR(STRING,NPOS,CHAR)
where STRING is a variable (or array) containing an ASCII STRING
NPOS is the position of the character to be replaced
(starting with position 1 at the left)
and CHAR is the character to insert into the string right justified
(as is the character returned by NCHAR)
note: to take a character from one string and put it into another
you can call PUTCHR and NCHAR as follows:
CALL PUTCHR(STR1,NPOS1,NCHAR(STR2,NPOS2))
10.0 DYNAMIC MEMORY MANAGEMENT
Two routines are provided to interface with the memory allocation
routines in FOROTS (the fortran run-time library). One to allocate core
(MORCOR) and the other to return it (RELCOR).
10.1 MORCOR
MORCOR is a FORTRAN FUNCTION which requests core from FOROTS and returns
the OFFSET to be used to make future references to the allocated memory.
Calling sequence:
OFFSET = MORCOR(ARAY,LENGTH)
MORCOR should be declared LOGICAL or INTEGER in the calling program.
The newly allocated memory will be zeroed by FOROTS.
To access the allocated memory use the following:
ARAY(OFFSET+I)
10.2 RELCOR
RELCOR is a FORTRAN SUBROUTINE to release core allocated by MORCOR.
Calling sequence:
CALL RELCOR(ARAY,OFFSET)
where OFFSET is the value returned by MORCOR
NOTE: RELCOR returns the memory to FOROTS, but FOROTS does not,
at present, release the core to the system.
It does, however, re-use it if possible on future calls to MORCOR.
FORMAC - A MACRO library for FORTRAN programs Page 5
11.0 EXTADR
Aquire extended memory for use by FORTRAN (v7)
This routine allocates very large arrays for use in FORTRAN programs.
The memory can be treated in FORTRAN like a very large array
(dimensioned very small in source). This is acomplished by returning
IOFSET, which can be used the FORTRAN as follows:
COMMON /BIGGER/ BIG(1)
INTEGER IOFSET
...
C allocate ISIZE words, return IOFSET
CALL EXTADR (BIG, ISIZE, IOFSET)
...
C use that array as follows:
DO 10 I=1,ISIZE
BIG (IOFSET+I) = I
10 CONTINUE
The program must be run in a non-zero section. To make that easier you
should do the following:
1. LOAD the program as usual
2. SAVE it
3. GET progname/USE-SECTION:1
4. SAVE progname
12.0 TTYINT
TTYINT is a FORTRAN (only) SUBROUTINE which allow a fortran program to
use the software interrupt system to signal when the user has typed a
particular control character.
Calling sequence:
CALL TTYINT (NUM,FLAG)
where NUM is the terminal interrupt code (see monitor calls manual
section 2.6.6 table 2-13 pg 2-58) [1=A, 2=B, 25=Y, etc]
and FLAG is a boolean variable to be set to true when the interrupt
occurs.
FORMAC - A MACRO library for FORTRAN programs Page 6
13.0 ZERO
ZERO is a group of FORTRAN SUBROUTINEs which clear memory. The entry
point names were chosen for an existing application (SPICE2) They are
related to IBM terminology (ie: REAL*4, REAL*8, etc).
Calling sequence:
CALL ZERO4(A,N)
or CALL ZERO8(A,N)
or CALL ZERO16(A,N)
where A is the start of the block to zero
and N is the number of elements to zero.
(ie: elements are words(ZERO4), double-words(ZERO8),
or quad-words(ZERO16))
The memory is cleared with Block Transfer instruction, which is very
efficient.
14.0 COPY
COPY is a group of FORTRAN SUBROUTINEs which copy blocks of memory. The
entry point names were chosen for an existing application (SPICE2).
They are related to IBM terminology (ie: REAL*4, REAL*8, etc).
Calling sequence:
CALL COPY4(A,B,N)
or CALL COPY8(A,B,N)
or CALL COPY16(A,B,N)
where A is the start of the FROM block
B is the start of the TO block
and N is the number of elements to copy.
(ie: elements are words(ZERO4), double-words(ZERO8),
or quad-words(ZERO16))
The Block Transfer instruction is used for fast block copying when
possible. That is not possible if the block is being moved up in memory
and the blocks overlap, in that case it is necessary to use a loop to
transfer one word at a time. The loop used is as fast as possible under
the circumstances.
FORMAC - A MACRO library for FORTRAN programs Page 7
15.0 TTSYNC
TTSYNC is a FORTRAN SUBROUTINE which allows a program to get back into
sync with terminal output. It waits for the output buffer to become
empty, then turns off the effect of any control-O which might have been
typed by the user. It can also wait a specified period after output has
stopped, to allow the terminal to settle down (eg: for TEKTRONIX
graphics terminals to clear the screen).
Calling sequence:
CALL TTSYNC(ITIME)
where ITIME is the number of milliseconds to wait after output stops.
16.0 FORK HANDLING ROUTINES
FORKS is a collection of FORTRAN (or PASCAL) callable routines to
manipulate forks. Facilities are provided to create forks, destroy
forks, load programs into forks, start forks, freeze forks, resume
forks, and wait on forks.
All fork handling routines require a 'fork handle' to distinguish
between possible multiple forks. When a fork is created a handle is
returned, that same handle must be used in all future references to that
fork
16.1 FRKCRE - Create A Fork
Calling sequence:
CALL FRKCRE(BITS,HANDLE)
where BITS is a logical mask to control the forks address space and
capabilities (Normally ZERO)
and HANDLE (on return) is the new fork handle (INTEGER)
16.2 FRKKIL - Kill A Fork
Calling sequence:
CALL FRKKIL(HANDLE)
16.3 FRKHLT - Halt A Fork
Calling sequence:
CALL FRKHLT(HANDLE)
FORMAC - A MACRO library for FORTRAN programs Page 8
16.4 FRKWAI - Wait For A Fork To Exit
Calling sequence:
CALL FRKWAI(HANDLE)
16.5 FRKFRZ - Freeze (suspend) A Fork
Calling sequence:
CALL FRKFRZ(HANDLE)
16.6 FRKRES - Resume A (suspended) Fork
Calling sequence:
CALL FRKRES(HANDLE)
16.7 FRKSTA - Start A Fork
Calling sequence:
CALL FRKSTA(HANDLE)
Optional calling sequence:
CALL FRKSTA(HANDLE,OFFSET)
where OFFSET is the offset into the entry vector to the desired starting
address.
16.8 FRKGET - Get (load) An .EXE File Into A Fork
Calling sequence:
CALL FRKGET(HANDLE,JFN)
where JFN is a 'Job File Number' for the file to be loaded (obtained
from GETJFN)
16.9 FRKSAC - Set Fork ACs. This Should Rarely Be Used, But
is necessary when running programs which expect parameters to be set in
the accumulators (ACs). (EDIT is such a program).
Calling sequence:
CALL FRKSAC(HANDLE,ACBLOK)
where ACBLOK is an array of 16 words (INTEGER)
FORMAC - A MACRO library for FORTRAN programs Page 9
16.10 GETJFN
The GETJFN routine returns a number (called a JFN) which is used by the
operating system for all calls related to files. It is included in the
FORKS package because a JFN is required in the FRKGET routine to specify
the file to be loaded.
Calling sequence:
CALL GETJFN(FILNAM,JFN)
where FILNAM is an array or literal containing the name of the file
desired
and JFN is (on return) the JFN for the desired file
17.0 EXIT0 ROUTINE
The routine EXIT0 can be called from FORTRAN ONLY! Its purpose is to
signal FOROTS that, on exit, the CPU time and ELAPSED time message are
NOT to be typed out. It does NOT exit, it merely sets that flag.
Calling sequence: fortran:
CALL EXIT0
18.0 DOJSYS ROUTINE
The routine DOJSYS can be called from either FORTRAN or COBOL to perform
any JSYS monitor call in TOPS-20.
Calling sequence: fortran:
CALL DOJSYS(NUMBER,ARG1,ARG2,...,ARGN [,$LABEL])
PASCAL:
Define DOJSYS as:
PROCEDURE DOJSYS(JSYSNUM: INTEGER; VAR AC1,AC2,AC3,AC4:
INTEGER); FORTRAN;
Call it with:
DOJSYS(NUMBER, ARG1, ARG2, ARG3, ARG4)
COBOL:
ENTER MACRO DOJSYS USING NUMBER, ARG1, ARG2,...,ARGN
[,PROC-NAME].
where NUMBER is the JSYS number to be performed
ARG1 thru ARGN are the arguments for the JSYS
$LABEL or PROC-NAME is the return address in case of error
Note: In PASCAL the error-return address cannot be used.
FORMAC - A MACRO library for FORTRAN programs Page 10
19.0 DATA CONVERSION ROUTINES
This is a collection of SUBROUTINEs to convert PDP-10 floating point
numbers to PDP-11 floating point and vice-versa.
19.1 F3632 - Convert 36bit Floating Poing To 32-bit
Calling sequence:
CALL F3632(FIN,FOUT,NUM)
where FIN is the input array of PDP-10 36bit real numbers
FOUT is the output array of PDP-11 32 bit numbers
and NUM is the length of each array
19.2 F3236 - Convert 32bit To 36bit
Calling sequence:
CALL F3236(FIN,FOUT,NUM)
where FIN is the input array of PDP-11 32bit real numbers
FOUT is the output array of PDP-10 36 bit numbers
and NUM is the length of each array
20.0 USRNAM - RETURN NAME OF USER
The SUBROUTINE USRNAM returns the name of the user who is running the
program. The username in TOPS-20 is up to 39 Characters, so this
routine returns 8 words (40 characters) with the user name left
justified and filled with trailing blanks.
Calling sequence:
CALL USRNAM (NAME)
where NAME is an array 8 words long (integer or real)
21.0 RUNTIME - RETURN PROCESS RUNTIME
The SUBROUTINE RUNTIME returns the runtime used by this process (not by
the JOB) in milliseconds.
Calling sequence:
CALL RUNTIM(ITIME)
where ITIME is an INTEGER
FORMAC - A MACRO library for FORTRAN programs Page 11
22.0 LOCF
LOCF is a FUNCTION which returns the address of the argument
Calling sequence:
LOCF(ARG)
where ARG is ANY argument of ANY type, including a literal
23.0 NXTJOB
NXTJOB is a FORTRAN SUBROUTINE which will never return. It is
equivalent to giving a RUN command at monitor level. It will cause the
monitor to replace the current program with a program which is in an
executable core image file (.EXE).
Calling sequence:
CALL NXTJOB(JFN)
where JFN is a TOPS-20 JFN for the file (see GETJFN routine)
Alternate calling sequence (macro)
MOVE T1,JFN
JRST NXTJB1
WARNING
Any files which are open for output should
be closed before NXTJOB is called, or they
will never be closed.
24.0 EXECDO
The purpose of this routine is to make it easy for a high level language
programmer to execute EXEC commands easily. It is NOT fool-proof. It
takes one ASCIZ string as input, writes it to a temporary file, followed
by <CRLF>POP<CRLF>. More complex commands can be handled by creating a
command file and using the TAKE command to execute that file.
Warning: DO commands will NOT work!
Calling sequence:
CALL EXECDO (COMAND)
where COMAND is a literal string in quotes, or an array or character
string which is the EXEC command to be executed
FORMAC - A MACRO library for FORTRAN programs Page 12
25.0 DDT
Load DDT if it is not already loaded, then transfer control to it. This
routine takes no arguments and is callable from any language.
26.0 CLEAR
Clear the screen of any supported terminal capable of it. This routine
takes no arguments and is callable from any language.
27.0 MOVE
This FORTRAN callable subroutine moves ASCII characters, assuming 8
(left-justified) characters per double word of memory.
Calling sequence:
CALL MOVE(A,I,B,J,N)
which causes N characters to be moved from B, beginning with the Jth
character (counting the first one as 1) to A, beginning at the Ith
;character position. If N <= 0, no characters are moved.
28.0 JOBENV
This FORTRAN callable subroutine stores into COMMON-BLOCK /CJE1/ various
aspects of the execution job environment.
Calling sequence:
CALL JOBENV
where the following declaration for /CJE1/ is assumed:
COMMON /CJE1/ USERID(4),IBATCH,IBAUD,ITERM
and the variable USERID is defined to be double precision.
This collection of subroutines uses the COMMD JSYS implemented in
TOPS-20 to carry out SANCA command parsing.
29.0 BEEP
start ringing the bell at the users terminal every few seconds and
continue until NOBEEP is called.
calling sequence:
...write prompt to users terminal...
CALL BEEP (TIME0,TIMED)
...read from users terminal...
CALL NOBEEP
where TIME0 is integer number of milli-seconds till first beep.
if less than 500, one second will be used by default
FORMAC - A MACRO library for FORTRAN programs Page 13
and TIMED is the delta to be added each time, if 0 then no delta,
if negative then double each time
Time will be incremented in case user is not around, to avoid driving
neighbors wacko.