LIBSIM
======

The files LIBSIM.REL and LIBSIM.ATR contain a large number of useful
external procedures and classes for the SIMULA programmer.

Library procedures will be available to your program if you declare them
as external at the beginning of your program, e.g:

EXTERNAL CLASS safeio;
EXTERNAL INTEGER PROCEDURE hash;

You need not mention any explicit filename if you are using LIBSIM on
the SYS area or on your own area.  An external declaration in a
separately compiled segment (module) must be repeated in all dependent
modules including the main program.  Please note that when you use
modules in LIBSIM that are coded in SIMULA you will sometimes have to
explicitly declare other LIBSIM routines.  The compiler will duly tell
the user which declarations are missing.

If you want to use other libraries, see the DECsystem-10 SIMULA Language
Handbook part II chapter 7.1.1.

Normally, when you load your programs with the LOAD, EXECUTE or DEBUG
commands of DECsystem-10, you need not mention the names of any
separately compiled classes or procedures.  Just write:

.EXECUTE myprog

if your program has the name myprog.  Any external classes or procedures
declared as such inside myprog will automatically be loaded.

At installations using the MIC system for command language macros, there
may be a macro LIBSIM.MIC available for maintenance of LIBSIM libraries.
Type "DO LIBSIM" without parameters for information about this.

If you cannot find the necessary .SIM, .REL, .ATR, .HLP, .MAN or .DOC
files on the SYS:, HLP: or DOC: areas on your computer, contact the
computer center or the SIMULA development group.

In addition to the utilities listed below, a SIMULA programmer has
access to a number of built-in standard procedures.  These are described
in appendix B to the DECsystem-10 SIMULA Language Handbook part I.

The procedures, classes and main programs listed below are described in
DECsystem-10 SIMULA Language Handbook part III.

The first column for each program indicates type of result for function
procedures, K for separately compiled classes.  The following letters
indicate parameter types.

Letter codes in this list:

..=repetition of parameter, R=REAL, L=LONG REAL, I=INTEGER, C=CHARACTER,
T=TEXT, X=REF, B=BOOLEAN, G=LABEL, a=ARRAY, P=PROCEDURE, K=CLASS.

An asterisk (*) indicates efficient, MACRO-10 coded procedure.

1. UTILITY PACKAGES

1.1 APPLICATION PACKAGES

K T,T     SAFEIO            Safe conversational terminal I/O.  See
                            SAFEIO.HLP and SAFEIO.MAN
K T       SAFEI             SAFEIO without file handling facilities
K         SAFMIN            Small, simplified version of SAFEI
K T,T     SIMEIO            Same as SAFEIO but prefixed with SIMULATION
K T       SIMEI             Same as SAFEI but prefixed with SIMULATION
K         SIMMIN            Same as SAFMIN but prefixed with SIMULATION
K         SIMDBM            CODASYL DBTG type DBMS system.  Consists of
                            the external classes SIMDBM (DBMMIN), DBMSET
                            and the main programs DBDUMP, DBLOAD,
                            DBSORT, FETCH, HMAKE, TRANSF, LOAD, DIRED,
                            SPEC, PREP and PREP2
K I,I     STORE             Simple text-oriented DBMS
K         SELECT            Boolean condition searching TEXT or FILE
K I,I,I   GPSSS             GPSS-like queue simulation package
K I,I,I,C,I GPSSST          GPSSS with more automatic trace facilities
K         FIGURE            Plot package for Tektronix plotter.  GRAPHI,
                            COSYS, COSYSF and RUBOUT are also part of
                            this package.  See FIGURE.HLP
K         CALSIM            Curve plotting on Calcomp 835 plotter.  See
                            CALSIM.HLP
K I,I,X,B,I VISTA           Full control of alphanumeric display screen,
                            e.g.  to produce moving pictures
K I,I,X,B,I FORM            Form fill in data entry, subclass of VISTA
P I,I,I,T GETVIS            Terminal type input for VISTA
K T       DAHELP            Gives user help message when running SIMULA
                            program.  Uses direct-access file to store
                            help messages.  See DAHELP.HLP
B T,T,I,I SQHELP            Gives user help message when running SIMULA
                            program.  Uses sequential file to store help
                            messages

2. SIMULA SOURCE CODE CONVERSION PROGRAMS

                            [These are main programs, and thus not
                            placed in LIBSIM]

M         SIMED             Prettyprinting, cleaner layout, indentation
                            of BEGIN-END, no semantic change of program
M         SIMEXP            Combines separately compiled modules into
                            one module
M         SIMIBM            Conversion to IBM Simula
M         IBMSIM            Conversion from IBM Simula
M         CDCSIM            Conversion from CDC Simula
M         FQCRED            Adds frequency count statements to a SIMULA
                            program
M         FQCLST            Edits SIMULA source program with frequency
                            measurements

3. DIRECTFILE HANDLING PROGRAMS

M         DIRED             Edits a directfile
M         MAKEDF            Converts sequential files to directfiles and
                            vice versa
M         FETCH             General-purpose SIMDBM Data Base Manipulator
M         MAKHLP            Creates help file for use with DAHELP


4. PROCEDURES NOT WRITEABLE IN SIMULA

                            4.1 TIME AND DATE

T         TODAY(*)          Gives TEXT with date:  yyyy-mm-dd
I         DAYNO             Number of this day in current year
T         DAYTIME(*)        Gives TEXT with hh:mm:ss
R         CLOCKTIME(*)      Gives REAL with time of day in seconds
R         CPTIME(*)         Gives LONG REAL with CPU time in seconds

                            4.2 REAL TIME

B X       INPUTCHECK(*)     Anything to read on file X?
P R       SLEEP(*)          Delays execution for R real seconds
I Xa,R    INPUTWAIT(*)      Sleeps until anything to read
K         REALTIME          Scheduler for terminal processes

                            4.3 INPUT/OUTPUT

I X       LINECOUNT(*)      Returns LINESPERPAGE setting
I X       FILENAME(*)       Gives TEXT with FILE object generation
                            parameter
C         GETCH(*)          Inputs character, will not wait for carriage
                            return (input from controlling terminal
                            only)
B R       TTYCHECK(*)       Checks if a character has been typed in at
                            the controlling terminal
P X,C,I   OUTCHR(*)         Outputs character bypassing image
P X       FORCEOUT(*)       Terminal output buffer to terminal
C X       INSINGLECHAR(*)   Inputs character, does not wait for carriage
                            return (Input from disk or controlling TTY)
C X       INSNGL(*)         As INSINGLECHAR, but line mode (waits for
                            break character)
P ILRCPa..  READ(*)         Reads many values in standard format
P ILRCTPa..  WRITE(*)       Writes many values in standard format
I X,RLICBTXa..  OUTPUT(*)   Binary output
I X,RLICBTXa..  INPUT(*)    Binary input
I RLICBTXa..  PUTSIZE(*)    How much will OUTPUT write?
B T       SCRATCHFILE(*)    Deletes file on secondary storage
X T       FINDINFILE(*)     NEW INFILE, but no error if file is not
                            available
X T,B     FINDDIRECTFILE(*) NEW DIRECTFILE, NONE if not available for
                            requested access
X T       FINDOUTFILE(*)    NEW OUTFILE, NONE if write protected
X T       FINDPRINTFILE(*)  NEW PRINTFILE, NONE if write protected
I X       LASTLOC(*)        Highest written line in a DIRECTFILE
B X       DOTYPEOUT(*)      Resets CTRL-O bit to resume terminal output.
                            TRUE if file is a terminal and the operation
                            was successful.

                            4.4 CONTROLLED ERROR HANDLING

P B       ENTERDEBUG(*)     Transfers to SIMULA debugging system
P T       ABORT(*)          User program generated error interrupt
P I       FORSIM(*)         Traps I/O calls from FORTRAN external
                            procedures

                            4.5 SCHEDULING AND JOB CONTROL

P T,I     RUN(*)            Runs a new program under current job
I T,B     SAVE(*)           Saves current main memory on a file
P T       RESTORE(*)        Resumes execution from save file
P I       FREEZE(*)         Exits to monitor, ready for SAVE
P I       EXIT(*)           Exits directly to monitor (I=0), after
                            closing files (I=1), to SIMDDT (I=2).

                            4.7 ENVIRONMENT ENQUIRY

I         MAXINT(*)         Returns largest positive INTEGER
R         MAXREAL(*)        Returns largest positive REAL

                            4.8 PACKING INTO PARTS OF WORDS(*)

B IRLa,I,IRLCBTa,I,.. PACK  Packs many variables of varying type
B IRLa,I,IRLCBTa,I,.. UNPACK Reverse of pack

                            4.9 MIN AND MAX

I I1,I2   IMAX(*)           Max(I1,I2)
I I1,I2   IMIN(*)           Min(I1,I2)
R R1,R2   RMAX(*)           Max(R1,R2)
R R1,R2   RMIN(*)           Min(R1,R2)
L L1,L2   LMAX(*)           Max(L1,L2)
L L1,L2   LMIN(*)           Min(L1,L2)


5. PROCEDURES WRITEABLE IN SIMULA

                            5.1 PARTITIONING OF TEXTS

T T       REST(*)           Subtext after POS
T T       FRONT(*)          Subtext before POS
T T,I     FROM(*)           Subtext after pos=I in T
T T,I     UPTO(*)           Subtext before pos=I in T
T T       FRONTSTRIP(*)     Subtext without leading blanks
T T       GETITEM(*)        Subtext = next identifier, number or
                            delimiter after POS
T X       INITEM(*)         GETITEM on INFILE
C T,I     FETCHAR(*)        Returns T.Sub(I,1).Getchar, null if I out of
                            range
P T,I,C   DEPCHAR(*)        T.Sub(I,1).Putchar(C), no action if out of
                            range.
T T,I1,I2 TSUB(*)           T.Sub(I1,I2), NOTEXT where Sub gives error

                            5.2 SEARCHING AND TESTING OF TEXTS

T T,C     SCANTO(*)         Next occurrence of C in T
T C       SKIP(*)           Skips string of characters = C from T.Pos
B T1,T2   FRONTCOMPARE(*)   Does rest of T1 begin with subtext = T2?
B T1,T2   UPCOMPARE(*)      Same as FRONTCOMPARE, but upper and lower
                            case letters are regarded as equal
I T1,T2   SEARCH(*)         Finds first subtext = T2 from T1.Pos
I T       CHECKREAL(*)      Checks if GETREAL can be performed
I T       CHECKINT(*)       Checks if GETINT can be performed
I T       CHECKFRAC(*)      Checks if GETFRAC can be performed
I T,I     HASH              Computes hash value from text in interval
                            [0:I-1]
C T1,T2   FINDTRIGGER(*)    Next occurrence of any character of T2 in T1
B T,I,Ta,I MENU             Searches for unambiguous text in a text
                            array
B T,Ta,I,I,I LOOKUP         Performs binary search in sorted text array

                            5.3 OPERATIONS ON TEXTS

T T,T     CONC2(*)          Concatenation of TEXTs, two parms
T T..     CONC(*)           Concatenation of variable no. of TEXTs
B T1,T2   PUTTEXT(*)        Copies value of T2 starting at T1.Pos
T T       UPCASE(*)         Converts to upper case
T T       LOWCASE(*)        Converts to lower case
T C,I     MAKETEXT(*)       NEW text, all I characters equal to C
T T,C     COMPRESS(*)       Removes given character from text
I T       STARTPOS(*)       Returns starting position for a (sub)text
B T1,T2,T3 CHANGE           Replaces first substring of T1 = T2, if any,
                            with T3.  Search starts at T1.Pos
L T       SCANREAL(*)       GETREAL, safe from bad data, starts at T.Pos
I T       SCANINT(*)        GETINT, safe from bad data, starts at T.Pos
I T       SCANFRAC(*)       GETFRAC, safe from bad data, starts at T.Pos
T T,R,C,I PUTTIME           Edits a number in TIME format
T T,R     PUTFLOAT          Edits a number using minimum no. of
                            characters
T I,I     RADIX             Edits 2nd parm to an item in 1st parm base.
I I,T     GETRADIX          Deedits an item(T) in base I to an integer
                            value.
P T,T,T,T SPLIT             Splits a text at given delimiter string
I T,T,Ta,I SPLITA           Splits a text and stores the parts in a text
                            array
I T,C,Ta,I SPLITC           Same as SPLITA but with character delimiter
I T,I,Ta,Ta SCAN            Identifies keywords in a command string.
I T,I,Ta,Ta SSCAN           Version of SCAN used by GETVIS.
K I       DECOM             (Subclass to SAFMIN) Interprets input
                            command of the format
                            outfil.ext/switch1/switch2...
                            =infil.ext/switch3/switch4...
I Ta      ARRLGD(*) Total length of texts in Ta + number of elements.
                            Used in SIMDBM.
P Ta,T,C  ARRTXT(*) Put all texts of Ta in T, with delimiter = C.  Used
                            in SIMDBM.

                            5.4 INPUT/OUTPUT

C X       LOOKAHEAD(*)      Next non-blank character readable by INCHAR
T T,X     INLINE            Types out a prompting question and copies an
                            infile image (stripped)
T T,T,T,B,T,T REQUEST       Sophisticated INLINE with input check, help
                            etc.
P X,R,C,I OUTTIME           Prints simulated time in hh:mm:ss.cc format
P ..      HISTP             Prints histogram of Ia on file X

                            5.5 SORTING AND SUMMATION ETC.

I R       ILOG              Returns integer part of 10LOG(Abs(R))+1;  if
                            R = 0 return 0.  I.e.  Number of integer
                            digits if Abs(R) >= 1 else number of leading
                            zeros after decimal point
I Ia,I    ISUM              Returns sum of an integer array
L La,I    LSUM              Returns sum of long real array (almost)
                            preserving precision
R Ra,I    RSUM              Returns sum of real array
R R,R,Ra,I SIGMA2           Returns variance, mean value of a real array
P R,R,I,R SIGMEAN           Returns current variance and mean value
                            including new observation
P "x"a,I  SORTxy            Sorts a given array in ascending or
                            descending order.
                            x = T(ext), R(eal), I(nteger) or L(ong real)
                            y = A(scending), D(escending) order
P Ia,I1,I2,I3 SORTDN        Sorts slice Ia[1:2,I1:I1-1+N] with respect
                            to either or both integers in each row.
R R,R,I   SCALESTEP         Adjusts approx.  max and min for diagram
                            design
B Ia,I,I,I,B IASHIFT(*)     Moves part of an integer array leftward.

                            5.6 RANDOM NUMBER GENERATION ETC.

P Ia,I,I,I SCRAMBLE         Random permutation of array
C Ia,N    PERGEN            Systematic generation of permutations
R R,R     RANDOM(*)         Random generator of random number series
                            start numbers
I         UNIQUE            Unique number to be used e.g.  as start
                            random number (seed)
I I1,I2   NEXTRANDOM(*)     Returns the I1:th successor to random seed
                            I2

                            5.7 SIMULA VERSIONS OF SYSTEM CLASSES

K         ZIMSET            SIMULA tracing version of SIMSET
K         ZIMULATION        SIMULA tracing version of SIMULATION


6.   SWEDISH LANGUAGE TEXT PROCESSING AND INPUT/OUTPUT

B C       BOKSTAV(*)        Swedish version of Letter
T X       INORD(*)          Swedish version of INITEM

T T       LITENBOKSTAV(*)   Swedish version of LOWCASE

B T,I,Ta,I MENY             Swedish version of MENU

T T       STORBOKSTAV(*)    Swedish version of UPCASE
T T       TAGORD(*)         Swedish version of GETITEM


7.   UTILITIES SPECIFIC TO DECSYSTEM-10

I I1,I2   ADJPTR(*)         Byte pointer I1 adjusted by I2 bytes

I I1,I2   ANDINT(*)         Bitwise AND function
I I1,I2,I3 BITFIELD(*)      Returns a bit field within I1 starting at
                            bit I2 (0-35) with length Abs(I3) (1-36) (I3
                            negative gives sign extension)
B I1,I2   BITGET(*)         BITGET:=I1.bit(36-I2)=1
P I1,I2,B BITPUT(*)         I1.bit(36-I2):=IF B THEN 1 ELSE 0
I I1,I2,I3 BOOLFUNC(*)      One (0<=I1<=15) of 16 Boolean functions of
                            I2,I3 (bitwise, like ANDINT).  For any valid
                            I1, BOOLFUNC(I1,5,3)=I1.
B T,T     CALLMIC           Uses MIC to perform other tasks and
                            optionally return
T T,T     CHECKEXTENSION    Adds default extension if file spec contains
                            no dot and is not just of the form DEV:
I I1,I2,I3,I4 DEPBYTE(*) I=I2 with byte at bit I3 of length I4 replaced
                            by I1.
P X,I     ECHO(*)           Suppresses monitor echoing of terminal input
I X,T     FILCOP(*)         Efficient copying of disk files.  Also
                            copies creation date and version.
K         FILED             Reads and writes DEC 10 line numbered files
T X,I     FILSPC            Returns file specification string for file X
                            in format controlled by value of I.
I I       FLOKUP(*)         Look up file specified by FILOP. and LOOKUP
                            blocks.
I I1,I2   GETTAB(*)         Returns item I1 in monitor table I2
T I       IDRX50(*)         Interprets a 36-bit word as a "RADIX50"
                            symbol (code bits and 6-character
                            identifier)
T I1,I2   IDSIXBIT(*)       ASCII representation of up to 12 character
                            identifier given in I1 and I2 in SIXBIT (DEC
                            64-character code)
I R       INTREA(*)         "Retype" R as integer (same 36-bit pattern)
I X       JOBSTATUS(*)      Get JOBSTS word for PTY or TTY (subjob
                            control)
I I1,I2   LOADBYTE(*)       Get any byte in readable core.
I I       LOADWORD(*)       Get word at address (I) - any readable word.
I I1,I2,I3 MATCH6(*)        SIXBIT match of I1 to I2 according to
                            wildcard mask I3.
B         NUMBERED(*)       Did last inimage get a line-numbered line?
T T,I     OCTAL(*)          Octal representation of I, using T as work
                            area.
I X,R     PTYCHECK(*)       Any PTY (Infile X) activity in R seconds?
X X       PTYFIL(*)         PTY Outfile companion to PTY Infile X.
I X       PTYINIMAGE(*)     Get line of input from PTY Infile X.  Result
                            shows how line ended.
I T,I     RDX50             Converts I,T to "RADIX50"
R I       REAINT(*)         "Retype" I as real (same 36-bit pattern)
B X/T,T[,B] RENAME(*)       Renames or deletes first arg (file ref/spec)
                            to second arg (file spec).
B         RESCAN(*)         Makes invoking monitor command readable by
                            invoked program
I T       SIXBIT(*)         First 6 characters in T converted to sixbit
                            word.
I I1,I2,I3 STOREBYTE(*)     Stores the byte I1 using byte pointer I2,
                            modified (I3) bytes.
I I1,I2   STOREWORD(*)      Store I1 at (I2) (abs memory address).
I I       SXRX50             RADIX50 to SIXBIT.
T T,B     TMPIN(*)          Reads a "TMPCOR" core file into a new text
                            object, and deletes the file if B is TRUE.
T T       TMPNAM(*)         Creates a temporary file name like
                            "021PIP.TMP"
B T1,T2   TMPOUT(*)         Writes a "TMPCOR" core file from T2.
                            Returns TRUE if successful.
I I,X,I   TRMOP(*)          Modifies monitor-terminal interface
I I       TTYLINE           Gives network node and line for tty number I
T I1,I2   TTYNUMBER         TTY number for node I1 line I2 in network
I I1,I2,B,I3 XCALLI(*)      Execute CALLI AC1,(I2).  AC1=I1.  Return
                            (I3) if CALLI does not skip and B is TRUE,
                            otherwise return new value of AC1.
I T,I1,I2 WILDSIX(*)        SIXBIT translation of T, recording wildcards
                            (?  or *) in I1.

                          [END OF LIBSIM.HLP]

