perm filename ALLSIM.HLP[SIM,SYS] blob sn#498716 filedate 1980-04-21 generic text, type T, neo UTF8


     SIMULA command strings and switches


     Command string format:

     relfil,lstfil=source1,source2,...

     Syntax:

     1. Each file descriptor has the format:

     dev:filename.ext[ppn]/switch/switch...

     Default for device (dev) is DSK.  Default for ppn is the user's
     project-programmer number.

     2. relfil receives the object code generated by the compiler and is
     always created unless severe errors were detected during
     compilation.  Default filename is the name of the first source.
     Default extension (ext) is REL.

     3. lstfil receives the program listing generated by the compiler
     and is produced if one of the switches L or C is set (see below).
     Default filename is the name of the last source file.  Default
     extension (ext) is LST.

     4. source1, source2, ...  are the source files which, combined,
     make up one SIMULA source program.  Default extension is SIM.
     Device must be disk or a logical name assigned to a disk device
     with the monitor command ASSIGN.

     5. Left arrow (←) may be used instead of equal sign (=).

     6. If only one source file is used as input and default names of
     rel and lst files are desired the equal sign or left arrow may be
     omitted.




     Switches:

     Switches may be placed after any file descriptor.  Each switch
     starts with a unique letter.  Each switch is thus defined by one or
     more characters and must be preceded by a slash or enclosed in
     parentheses ().  The meaning of a switch is reversed if it is
     preceded by a minus sign.

     Name       Format  Default/Meaning

     ARRAY      /A      /A
                        Generate code to check array boundaries.

     CREF       /C      /-C
                        Generate a cross reference listing on the list
                        file.  This switch also sets the L-switch.

     DEBUGS     /D      /D
                        Generate a symbol table for SIMDDT.  

     EXTERNAL   /nE     /-E
                        Treat the source program as an external class or
                        procedure.  n is a decimal unsigned number
                        specifying the block level at which the external
                        program will be compiled.  Default for n is 1.
                        /-E indicates main program.  See below for
                        format in OPTIONS statement.

     HELP       /H      /-H
                        Type this information at the user terminal.
                        HELP can be placed anywhere before the second
                        source file descriptor.  HELP is only valid in
                        connection with the R command.

     IDENTIFICATION /I  /I
                        Generate a line number table to be used for
                        debugging with SIMDDT and for run-time
                        diagnostic messages.

     LIST       /L      /-L
                        Generate a listing of the source program.  If
                        this switch is present before the first source
                        file specification then all source files are
                        listed.  If it is present after say, the second
                        source specification, then the first will not be
                        listed.

     NOERR      /N      /-N
                        Suppress output of error messages on the user's
                        terminal.

     PAGE       /nP     /55P
                        Specify the number (n) of lines per page in the
                        source file listing.  If n > 55 then the default
                        vale 55 is used.  See below for extended format.

     QUALIFICATION /Q   /Q
                        Generate code to check that a class instance has
                        a certain qualification.

     RUNSWITCHES /R     /-R
                        File specifications will be read from TTY at the
                        start of the object program execution.  See
                        below for extended format.

     SEARCH     /S      /S
                        Enables automatic search of ATR libraries.
                        Libraries on the search list (see below) are
                        searched if an ATR file corresponding to an
                        external procedure or class cannot be found.
                        See below for extended format.

     WARNING    /W      /W
                        Warning messages are listed on the source
                        listing (if any) and on the user's TTY.

     Y          /Y      /-Y
                        Write the line number table after the source
                        listing.  The IDENTIFICATION and the LIST
                        switches must be set.


     Note that extended formats for switches E, P, R and S are
     available.  The extended format for the E switch can only be used
     in the OPTIONS statement, whereas the longer forms of the P, R and
     S switches can also be used with the R SIMULA command (explicit
     execution of the compiler).

E switch

     /nE:<codeword>,[<checkoption>,]entryname
     /nE:FORTRAN,entryname
     /nE:F40,entryname

     <codeword> is CODE or QUICK and specifies an external assembly
     procedure.  FORTRAN specifies an external FORTRAN-10 (new FORTRAN)
     procedure and F40 an external FORTRAN-IV (old FORTRAN) procedure.

     <checkoption> is CHECK or NOCHECK (-CHECK).  CHECK implies
     parameter checking and NOCHECK suppression of parameter checking.
     If <checkoption> is omitted parameter checking is assumed.  NOCHECK
     and -CHECK are equivalent.

     Entryname is the entry name of the external procedure.

     See SIMULA Language Handbook appendix E for further details.

P switch

     /P:"text"
     The text enclosed in quotes will be placed in the list file page
     heading.  The first line after the OPTIONS statement is printed on
     a new page.  This is also done for /P without argument.

R switch

     /R:"file spec"
     The file specification has the same syntax as file specifications
     in a command.  File specifications will be read from that file at
     run time.  (See chapter 8 in the handbook).

     Examples:

     /R:"SYSIN"
     /R:"TTY:"        (equivalent to /R)
     /R:"DSKC:FILES.SPC[130,131]"

S switch

     /S:"file spec"     !add to search list;
     /S                 !enable standard search list;
     /-S:"file spec"    !disable search for this file;
     /-S                !disable library search for all files;

     The file specification is of the same form as file specifications
     in a command.  The file extension should be ATR if given, otherwise
     ATR is assumed.  The file specification will be placed on a search
     list to be used when an ATR file is not found corresponding to an
     external declaration.  If S is preceded by a minus sign, the file
     will  n o t  be part of the search list.  An S switch without a
     file name enables search of the default libraries.  -S without a
     file name turns off library search for all files.  Selected files
     can then be put on the search list by further SEARCH switches.  For
     a declaration EXTERNAL CLASS A the standard search list is A.ATR,
     LIBSIM.ATR, SYS:LIBSIM.ATR.  This means that LIBSIM.ATR will be
     searched if A.ATR is not found on your own area, and SYS:LIBSIM.ATR
     will be used if your own LIBSIM does not exist or does not contain
     the ATR module wanted.
     Important!  Always make sure that each ATR file has a corresponding
     REL file, where ATR has been replaced by REL, while the rest of the
     file specification is identical.  The compiler tells LINK-10 to
     expect this.  A library such as LIBSIM.ATR  m u s t  have an index
     (X switch to FUDGE2).


                          [END OF SIMCOM.HLP]



DEBUGGING SIMULA PROGRAMS WITH SIMDDT


SIMDDT is an interactive program that is used to debug SIMULA programs.
SIMDDT allows the user to:

a) set up to 20 breakpoints in the program    [STOP] AT [module:] nn ...
b) continue from a breakpoint                 PROCEED
c) display the current breakpoint settings    [STOP] BREAKS
d) remove a breakpoint setting                REMOVE [AT n]
e) change the contents of a variable          INPUT x:= ...
f) display the contents of a variable         OUTPUT x, ...
g) display all variables in the storage pool  VARIABLES [/switches]
h) display the dynamic operating chain        CHAIN
i) display all scheduled processes            SCHEDULED
k) switch output to a disk file e.g.  a.bug   USE a.bug
l) display the source program                 DISPLAY [module:] mm[-nn]
m) move SIMDDT viewpoint :  to object x       INSPECT x
      to SIMDDT interrupt point               INSPECT/START
      to CLASS or PROCEDURE generation point  INSPECT/RETURN
      to viewpoint before last RETURN         INSPECT/RESET
      to statically enclosing block           INSPECT/UP
n) close open files                           [STOP] CLOSE
o) read SIMDDT control file e.g.  x.cmd       @x.cmd
p) terminate execution                        EXIT



1.  LOADING AND STARTING SIMDDT


The SIMDDT program is self-relocating and it is read from disk by a
SIMRTS routine when requested.  The SIMULA compiler switches I
(IDENTIFICATION, produces a line number table) and D (DEBUGS, produces a
symbol table) must have been set during compilation if the program is to
be debugged with SIMDDT.  The switches are set by default but if they
were set off, SIMDDT will give incomplete information to the user.

1.1 DEBUG

     If the source file has extension SIM or the /SIMULA switch is used,
     the DEBUG monitor command will ensure that SIMDDT is read into low
     segment core and started before the SIMULA program execution
     starts.
     Command example:

     .DEBUG MYPROG.SIM


1.2 LOAD, SAVE, GET, REENTER

     The monitor commands LOAD plus SAVE will save the user program not
     including SIMDDT on disk.  If issued directly after LOAD (+SAVE) or
     GET, the REENTER command will cause SIMDDT to be read into low
     segment core and started.  The START monitor command will start
     user program execution directly.
     Command example:

     .LOAD MYPROG.SIM
     .SAVE
     .REENTER


1.3 ↑C - REENTER

     After the SIMULA program has started to execute without the
     debugging system it is usually possible to invoke SIMDDT.  One or
     two ↑C commands will stop execution and return the terminal to
     monitor mode.  The REENTER monitor command will load and start
     SIMDDT, which will give the number of the source program line which
     corresponds to the statement which was interrupted by ↑C.  This is
     very useful when the program is looping.  ↑C can also be used if
     SIMDDT is already loaded.
     Command example:

     .EXECUTE MYPROG.SIM
     ↑C
     ↑C
     .REENTER


1.4 Program errors

     SIMDDT will be called to write the error message and information on
     where the error occurred.


1.5 CONTINUE after program exit

     The CONTINUE monitor command can be used to start SIMDDT after a
     normal program exit.  The variables in the storage pool can be
     displayed with the VARIABLES command.


1.6 REENTER after program exit

     The REENTER command should be used to restart the program and
     SIMDDT after program exit.  Note that all breakpoint settings will
     be removed.  If SIMDDT was not loaded at execution start, the START
     command will restart the program without invoking SIMDDT.



2  SIMDDT COMMANDS


SIMDDT operates in two modes, debug and error mode.  SIMDDT is in error
mode when entered after a program error, otherwise it is in debug mode.


2.1 Command syntax


     SIMDDT will translate all lower case letters to upper case.  The
     reserved words in the commands can be truncated to any number of
     characters as long as they are unique.  The keywords INPUT and STOP
     have also been given short forms namely I and ST.  A command may
     not occupy more than one line.

     A line starting with the character ; will be treated as a comment
     and ignored.


     The user identifies a breakpoint with a source program line number.
     In the command descriptions below the notation <LINE> is used.
     <LINE> has the form [<MODULE>:] <NNNNN>.

     <MODULE> is MAIN or the SIMULA name of a separately compiled
     procedure or class.  MAIN indicates the main program.  If <MODULE>:
     is omitted, the current module is used by SIMDDT, that is MAIN at
     program start and later the module in which the current breakpoint
     is placed.

     <NNNNN> is a line number in the source program.  The line should
     contain the beginning of an executable statement.  If not found the
     first higher numbered line on which a statement starts will be
     chosen.

     In the commands the user references a source variable with the
     notation <IDENTIFICATION> or <IDENTIFICATION2>.

     <IDENTIFICATION> ::= <IDENTIFICATION1> 
                          [QUA <CLASS IDENTIFIER>] !
                          <IDENTIFICATION>.<IDENTIFICATION1>

     <IDENTIFICATION1> ::= <IDENTIFIER> !  
                           THIS <CLASS IDENTIFIER>!
                           <ARRAY IDENTIFIER>(<SUBSCRIPT LIST>)

     <SUBSCRIPT LIST> ::= [-] <INTEGER> !
                          [-] <INTEGER>,<SUBSCRIPT LIST>

     <IDENTIFICATION2> ::= <IDENTIFICATION> !
                          [<IDENTIFICATION>.]<ARRAY IDENTIFIER> !
                          [<IDENTIFICATION>.]*

     The <IDENTIFIER> must be a simple variable of type INTEGER, REAL,
     LONG REAL, BOOLEAN or CHARACTER or a simple object reference or
     TEXT type variable.  When the <IDENTIFIER> is a formal parameter
     called by name it is not handled by SIMDDT.  A formal parameter
     with transmission mode by value or by reference will be treated
     like a declared variable.  The standard procedures SYSIN, SYSOUT,
     FIRST, LAST, SUC, PRED, PREV, EVETIME, MAIN, TIME and CURRENT are
     accepted by SIMDDT.

     The brackets ( ) around the <SUBSCRIPT LIST> can be replaced by a
     pair of square brackets, e.g.  A[1,2].

     In the commands below the notation <STRING> is used.  <STRING> is a
     string of characters enclosed in " .  The first 5 characters in the
     string are part of the message that SIMDDT outputs at the
     breakpoint.


2.2 Commands


     [STOP] AT <LINE> [,<N>] [<STRING>]

     SIMDDT ACTION:  Identifies a breakpoint and outputs a message every
     n:th time the referenced statement is executed.  If STOP is given
     execution is halted and new SIMDDT commands are accepted.  <N>, the
     loop counter, is an integer number.


     [STOP] AT <LINE> [<STRING>] [IFCHANGED] <IDENTIFICATION2> [,
     <IDENTIFICATION2> ]...

     SIMDDT ACTION:  Identifies a breakpoint.  If IFCHANGED is specified
     SIMDDT will output only changed variable values, otherwise the
     values are always given.  If IFCHANGED is specified the first time
     the breakpoint is reached, the value is compared to 0, FALSE,
     NOTEXT, NONE or CHAR(0), depending on its type.  * the complete
     block indicator and <ARRAY IDENTIFIER> are not allowed when
     IFCHANGED used.

     [STOP] AT <LINE> [<STRING>] IF <IDENTIFICATION> 
     <RELATION OPERATOR> <VALUE>

     SIMDDT ACTION:  Identifies a breakpoint.  SIMDDT will output the
     variable value if the relation is TRUE.
     The <RELATION OPERATOR> can be one of > >= < <= = \= == =/= GT GE
     LT LE EQ NE EQV IS IN.  The <VALUE> can be an <IDENTIFICATION>,
     TRUE, FALSE, NOTEXT, NONE, arithmetic constant, character constant,
     text value constant or CLASS identifier.


     REMOVE [ AT <LINE> ]

     SIMDDT ACTION:  Remove all breakpoint commands for a specific line
     or remove all breakpoints.


     [STOP] BREAKS

     SIMDDT ACTION:  List all breakpoint commands.  The input order is
     not kept.  If STOP is specified, SIMDDT will halt after each
     breakpoint command and give the user the possibility to remove it.
     When all breakpoint commands for a line are removed the breakpoint
     is removed.


     OUTPUT <IDENTIFICATION2> [/-TEXT][/-ARRAY]
     [,<IDENTIFICATION2>]...

     SIMDDT ACTION:  Output the values of the variables.  See VARIABLES
     for explanation of the switches.



     INPUT <IDENTIFICATION> <ASSIGNMENT OPERATOR> <VALUE>

     SIMDDT ACTION:  Changes the value of the referenced variable to the
     value given in the command.  The operators are := and :-.  See
     above for explanation of <VALUE>.


     DISPLAY [<MODULE>:]<NNNNN> [-<NNNNN>]

     SIMDDT ACTION:  Output the indicated source program lines.


     INSPECT <IDENTIFICATION> !  /START !  /RETURN !  /RESET !  /UP

     SIMDDT ACTION:  The point in the program, from which SIMDDT sees
     the variables, is moved.  This makes it possible to input and
     output variables, which are not visible from the block in which the
     program execution was interrupted.

     INSPECT <IDENTIFICATION>
     SIMDDT will now see inside the CLASS object, to which the variable
     refers.  It must be an object reference (not NONE).

     INSPECT /START
     SIMDDT will again see from the place, where program execution was
     originally interrupted and SIMDDT entered.

     INSPECT /RETURN
     SIMDDT should be looking inside a procedure or an active CLASS.
     /RETURN will make SIMDDT see from the point where the procedure was
     called or where the class was generated or called.

     INSPECT /RESET
     Go back to where SIMDDT was looking before the last INSPECT /RETURN
     command.

     INSPECT /UP
     Look directly at the statically enclosing block.


     PROCEED

     SIMDDT ACTION:  SIMDDT will either start program execution or
     continue processing at the point where it was interrupted.  PROCEED
     is not valid after an error from which it is not possible to
     continue or after a NOPROCEED command.


     USE <FILE SPECIFICATION>

     SIMDDT ACTION:  SIMDDT output will be written on the file specified
     in the command.  All output that signals a user action is also
     output on TTY e.g.  the message "STOP AT MAIN:17 " will be output
     both at the TTY and the file at the breakpoint stop.  The file is
     not closed until a new USE command is given or at the end of
     execution.  The format of the <FILE SPECIFICATION> is the same as
     the one used for the other user files, see chapter 8.2.  USE TTY:
     will reset SIMDDT output to the terminal.


     CHAIN

     SIMDDT ACTION:  Writes the dynamic operating chain starting with
     the current block.  Only procedures, class instances and inspected
     class instances are given.  The name of the block and its
     activation line are listed.


     VARIABLES [/-ARRAY][/-TEXT][/-GC]

     SIMDDT ACTION:  The complete storage pool is scanned and all
     variables that are of a type treated by SIMDDT are listed together
     with the name of the dynamic block in which the variables are
     declared.  If possible the garbage collector routine (G.C.) will be
     called before the storage pool is investigated if not /-GC was
     specified.  When /-ARRAY is specified all array elements are
     skipped in the output.  When /-TEXT is specified all text
     characters are skipped in the output.  To reduce output only
     variables which do not have their initial values are given.  The
     amount of data is often very large, and the USE command can be used
     to direct the output to a disk or LPT file.


     SCHEDULED

     SIMDDT ACTION:  For each scheduled process the following will be
     output:
     EVTIME= scheduled time
     Class name
     Octal address of dynamic area DETACHED <LINE>


     ALL [/-ARRAY] [/-TEXT] [/-GC]

     SIMDDT ACTION:  Produces the same information as if the commands
     CHAIN, VARIABLES and SCHEDULED had been given.  


     [STOP] CLOSE

     SIMDDT ACTION:  Lists and closes all open files except SYSIN and
     SYSOUT.  If STOP specified SIMDDT will halt and give the user the
     possibility to close the file.  Answer CLOSE or carriage return.


     NOPROCEED

     SIMDDT ACTION:  Inhibits the use of the PROCEED command.  After
     this command it will be possible to use a critical command such as
     USE or DISPLAY.  Not necessary when stopping at preset breakpoints.


     @ <FILE SPECIFICATION>

     SIMDDT ACTION:  SIMDDT input will be read from the file specified
     in the command.  The command will be output on the TTY before it is
     processed.  When end of file found SIMDDT will request input from
     the TTY.


     EXIT

     SIMDDT ACTION:  Returns control to SIMRTS which closes the SYSIN
     and SYSOUT files and then returns to the monitor.  


     HELP

     SIMDDT ACTION:  Lists part of the SIMDDT.HLP file.


     2.3 Command examples


     STOP AT 55 ,3

     EXPLANATION:  Set a breakpoint at first statement on line 55 and
     stop processing every third time the statement is executed so that
     the user can communicate with SIMDDT.

     AT MAIN:30 "LIST" VINT[1,3], VREF.VBOOL

     EXPLANATION:  Output the values of the variables VINT[1,3] and
     VREF.VBOOL each time the first statement on line 30 in the main
     program is to be executed.  The message will contain the letters
     "LIST".

     AT 10 IFCHANGED VREAL,VTEXT

     EXPLANATION:  Output the variable value if any of the variables
     were changed since the last time the statement at line 10 was to be
     executed.

     STOP AT 80 IF VREAL>=1.5

     EXPLANATION:  Stop execution at the statement on line 80 if the
     variable VREAL>=1.5

     INPUT VTEXT:="TEXT VALUE ASSIGNMENT"

     EXPLANATION:  Change the value of the text variable.  Note that
     only the characters may be changed, but not the length.

     USE DEBFIL.LPT

     EXPLANATION:  SIMDDT output will be written on file DEBFIL.LPT.
     Output in connection with a breakpoint stop will also appear on the
     user TTY.

     DISPLAY 1-10

     EXPLANATION:  Output the source program lines 1 to 10.




2.4 SIMDDT input and output

     The user TTY is normally used for input to SIMDDT .  A "*" on the
     terminal signals that SIMDDT is expecting a user command.  The @
     command will cause SIMDDT to read its input from the indicated
     file.

     The user TTY is used for output from SIMDDT when it is in debug
     mode and no USE command has been given.

     Both the user TTY and the SYSOUT file are used for output from
     SIMDDT when it is in error mode.The output from the ALL command is
     only written to SYSOUT but all other output is written on both
     files.
     If an output file is specified with the USE command it replaces the
     SYSOUT file.


                          [END OF SIMDDT.HLP]



With the SIMDIR program you can easily find out:
> Which separately compiled modules are required by one or several main
programs.
> Which program modules require a certain separately compiled procedure
or class.
To start the program type:
.R SIMDIR
SIMDIR responds with a "*" , signalling that it is ready for a command.

In the simplest case, you can now write:

   SEARCH /ALL REQUIRED BY main

This will list all modules on your PPN which are used by the module
main.  main is usually a SIMULA main program, but can be a separately
compiled module.

   SEARCH /ALL USING proc

This will list all modules on your PPN which use the separately compiled
module proc.

You can precede the SEARCH command with a DIRECTORY command to tell the
system to include other PPN:s in the search.  For example, you can
write:

   DIRECTORY [*,*]
   SEARCH /ALL USING proc

This will give a listing of all SIMULA programs on all PPN:s which
require your separately compiled procedure proc.

As input SIMDIR requires ATR-files from separately compiled classes and
procedures and REL-files from main programs.  This means that SIMDIR
only works when such ATR and REL files are present for the programs to
be listed.

The syntax of SIMDIR commands follows:

     <SEARCH-command>::= SEARCH <pattern> [<relation>[<pattern>]]
        <relation>::= USING ! REQUIRED BY
        <pattern>::= [<device>][<filename>][<ppn>][<switches>]
        <ppn>::= <left bracket><ppn1><right bracket>
        <ppn1>::= SELF ! OTHERS ! <pnr>,<pnr>
        <pnr>::= ! * ! <octal number>
        <switches>::= <switch> ! <switches><switch>
        <switch>::= /<switchname>
        <switchname>::= ALL ! MAIN ! CLASSES ! PROCEDURES !
                FPROCEDURES ! SPROCEDURES ! MPROCEDURES !
                FAST ! TTY
        <device>::= <name>:
        <filename>::= <name>

        SEARCH <pattern> means that all modules matching the pattern
        will be searched for and listed.

        SEARCH <pattern> <relation> means that all modules matching the
        pattern will be searched for and listed together with the
        modules which have the given relation to the modules.

        SEARCH <pattern> <relation> <pattern> means that all modules
        matching the first pattern and having the given relation to any
        module matching the second pattern are listed.

        A module matches a pattern when it matches all components of
        that pattern.  If any component is missing in a pattern, then
        all modules match that component.  The pattern may not be empty,
        however.

        There are two special PPN:s that you may use in a pattern:
        [SELF] is the LOGIN PPN.  [OTHERS] stands for all PPN's except
        [SELF] which have been given in DIRECTORY commands.

        Explanation of switches:
                ALL             All modules match
                MAIN            Main programs match
                CLASSES         Classes match
                PROCEDURES      Procedures match
                FPROCEDURES     FORTRAN procedures match
                MPROCEDURES     MACRO-10 procedures match
                SPROCEDURES     SIMULA procedures match
                FAST            Do not output PPN
                TTY             Change output device
                                temporarily to TTY.


     <DIRECTORY-command>::= DIRECTORY <directories>
        <directories>::= <directory> ! <directory>,<directories>
        <directory>::= [<switch>] <ppn> [<switch>]
        <switch>   ::= /MAIN ! /-MAIN

        Include the given directories when searching.
        /MAIN means that all modules are fetched from this directory,
        /-MAIN that only external classes and procedures are fetched.
        Default is /-MAIN.


     <LIST-command>::= LIST <file specification>

        Program output is written on the specified file.  Default is
        DSK:SIMDIR.LST


     <CLOSE-command>::= CLOSE

        The current list file is closed.


     <EXIT-command>::= EXIT

        Close current list file (if any) and return to monitor.


     <HELP-command>::= HELP [ /TTY ]

        Output help-text.


     All "reserved words" (upper case letters above) can be abbreviated
     arbitrarily.  Any conflicts are resolved as follows :
        /M means /MAIN
        /F means /FAST


     When SIMDIR is started a *D[S]/M command is automatically
     performed.


     EXAMPLES:

     List all SIMULA modules on your own PPN
      .R SIMDIR
      *S/ALL
        .
        .
        .

     List those of your own modules which are used by others in the same
     project.
      .R SIMDIR
      *DIR [,*]/M
      *SEARCH [SELF] REQ BY [OTHERS]
        .
        .
        .


                          [END OF SIMDIR.HLP]
			DECOM
			-----

DECOM is a SIMULA SAFMIN subclass designed for
interpretation of "standard" DEC command format:

outspec/switch1/switch2....=inspec/switch3/switch4...


Included procedures:
--------------------

DECCOM for initial separation of the input command
and opening of the files.

INTSWITCH for interpreting switch giving integer value.

BOOLSWITCH for interpreting switch giving boolean value.

ILLEGALSWITCH for finding if there are any uninterpretable
switches.

The DECCOM procedure helps interpreting a DEC standard file
command.

The CREATEFILES procedure is used to create the file
objects for the input and and output files.


Parameters to DECOM:

(I)	COMMAND		The string to be interpreted
(O)	OHEAD		Output file specifications
(O)	IHEAD		Input file specifications

Parameters to CREATEFILES:

(IO)	OHEAD		Output file specifications
(IO)	IHEAD		Input file specifications
(I)	OEXTENSION	Default extension for output file name
(I)	IEXTENSION	Default extension for input file name
			(Extension is only set if file spec lacks extension)
[O]	OFILE		Outfile object reference
[O]	IFILE		Infile object reference

Global data in the class DECOM:

(O)	SWARRAY    	TEXT ARRAY [1:LIMIT] saving switch values
(I)	LIMIT		Maximum number of  switches
(O)	NSWOUT		Number of received switch values on the output side
(O)	NSWIN		Ditto input side

Format of COMMAND:

<command>::= [<outpart>] <inpart>
<outpart>::= [<spec>] =
<spec>:= [<filespec>] [/<switches>]
<filespec>::= [<device>:] filename [ . [ext] ]
<switches>::= <switches> / <switch> | <switch>
<switch>::= <anything not containing '=' or '/'>

The <spec> for the <outpart> will be returned through OHEAD,
and through IHEAD for the <inpart>.

The switches on the outpart side will be stored in the array
SWARRAY[1:NSWOUT] and those on the inside side in the
elements [NSWOUT+1,NSWOUT+NSWIN].

I.e.
A/B=C/D/E
will return
OHEAD = "A"
IHEAD = "C"
SWARRAY [1] = "B"
	[2] = "D"
	[3] = "E"
NSWOUT = 1
NSWIN  = 2

If the number of switches exceeds LIMIT a warning message is issued and
the rest of the switches will be ignored.
Note that the unused SWARRAY elements will NOT be set to NOTEXT.

CREATEFILES will assert that OHEAD and IHEAD
are legal output and input file specifications respectively.
References to the files will be returned through OFILE and IFILE.

PROCEDURE INTSWITCH(id,result,default,okay,errmess,help)
Intswitch should be called after the call to DECCOM,
once for each allowed switch returning integer result. Parameters:

(I)     ID               User name of the switch (without /)
(O)     RESULT           Integer where switchvalue is returned
(I)     DEFAULT          Text containing default value, to be
			 used if switch is not given by the user
(I)     OKAY             Boolean condition, TRUE for valid results
(I)     ERRMESS          Message to be given if OKAY is FALSE
(I)     HELP             Boolean expression giving help message.

BOOLEAN PROCEDURE BOOLSWITCH(id,okay,errmess,help)
Boolswitch should be called after the call to deccom,
once for each allowed switch returning boolean result. The
parameters are a subset of the parameters for intswitch(see above).
Boolswitch returns TRUE if the switch is present, false if it is not
present. Okay is the condition under which a TRUE result is legal.

BOOLEAN PROCEDURE ILLEGALSWITCH(errmess,help)
This should be called after all legal switches have been interpreted.
Will give an error message for each duplicate switch or switch
which has not been interpreted, and will return TRUE
if there was any such switch.
Help is called if the illegal switch is /H or /HE or /HEL or /HELP.

Examples of use:

OPTIONS(/L);
BEGIN
  EXTERNAL TEXT	PROCEDURE rest, scanto, frontstrip, upcase,
  front, conc, checkextension;
  EXTERNAL REF (infile)	PROCEDURE findinfile;
  EXTERNAL REF (outfile)	PROCEDURE findoutfile;
  EXTERNAL BOOLEAN	PROCEDURE frontcompare;
  EXTERNAL CHARACTER	PROCEDURE findtrigger;
  EXTERNAL INTEGER	PROCEDURE scanint, search;
  EXTERNAL LONG REAL	PROCEDURE scanreal;
  EXTERNAL		PROCEDURE split;
  EXTERNAL		CLASS safmin, decom;

  COMMENT the following externals are only used by the demonstration
  program, not necessary for decom;
  EXTERNAL TEXT PROCEDURE from;
  EXTERNAL BOOLEAN PROCEDURE dotypeout;
  EXTERNAL BOOLEAN PROCEDURE sqhelp;

  INTEGER max←number←of←lines;
  BOOLEAN list←output, file←output;
  TEXT command, infilename, outfilename;
  REF (infile) infileref;
  REF (outfile) outfileref;

  decom(14) BEGIN
    PROCEDURE do←something←useful;
    BEGIN
      outimage;
      outtext("[COMDEM EXECUTION HAS STARTED]"); outimage;
      outtext("LINES = "); outint(max←number←of←lines,5);
      outimage;
      IF list←output THEN outtext("LISTOUTPUT") ELSE
      IF file←output THEN outtext("FILEOUTPUT") ELSE
      outtext("NEITHER LISTOUTPUT NOR FILEOUTPUT");
      outimage;
      outimage;
    END;


    BOOLEAN PROCEDURE decom←help(selector);
    VALUE selector; TEXT selector;
    BEGIN
      outimage;
      outtext("outfil.ext=infil.ext/switch1/switch2....");
      outimage;
      outtext("SWITCH  DEFAULT  MEANING");
      outimage;
      outtext("/LINES     5     Number of lines");
      outimage;
      outtext("/LIST  FALSE     List output");
      outimage;
      outtext("/FILE  FALSE     File output");
      outimage; outimage;
      IF selector == NOTEXT AND sysin.image =/= NOTEXT THEN
      BEGIN
        command:- sysin.image.strip;
        command.setpos(1); IF command.getchar = '?' THEN
        selector:- command.sub(2,command.length-1);
      END;
      sqhelp("DECOM",selector,19,72);
    END;

    PROCEDURE interpret←integer←switches;
    BEGIN
      intswitch("LINES","5",max←number←of←lines,
      max←number←of←lines >= 0 AND max←number←of←lines <= 11,
      "Must be between 0 and 11",decom←help(""));
      COMMENT etcetera;
    END of interpret←integer←switches;

    PROCEDURE interpret←boolean←switches;
    BEGIN
      list←output:= boolswitch("LIST",TRUE,NOTEXT,decom←help(""));
      file←output:= boolswitch("FILE",NOT list←output,
      "Only one kind of output",decom←help(""));
      COMMENT etcetera;
    END of interpret←boolean←switches;

    BOOLEAN PROCEDURE interpret←legal←command;
    BEGIN
      IF NOT deccom(command,outfilename,infilename)
      THEN GOTO out;
      interpret←integer←switches;
      interpret←boolean←switches;
      IF outfilename = NOTEXT THEN outfilename:-copy("TTY:");
      IF infilename = NOTEXT THEN
      BEGIN
        IF list←output THEN
        BEGIN
          infilename:- copy(outfilename);
          IF findtrigger(infilename,dottext) = '.' THEN
          infilename:- infilename.sub(1,infilename.pos-2);
        END;
      END;

      IF NOT illegalswitch(
      "Uninterpretable or duplicate switch: /",decom←help("")) THEN
      BEGIN
        createfiles(outfilename,infilename,
        copy(IF list←output THEN ".LST" ELSE ".ADR"),copy(".ADR"),
        outfileref,infileref,decom←help("CREATE"));
        interpret←legal←command:= TRUE;
      END;
      out:
    END;

    PROCEDURE read←input←command;
    BEGIN CHARACTER c;
      prompt: image:= "*"; breakoutimage; inimage;
      IF sysin.image.strip = NOTEXT THEN GOTO prompt;
      lastitem; c:= inchar;
      IF c = '/' OR c = '?' THEN
      BEGIN
        IF endfile THEN GOTO quit;
        decom←help(""); GOTO prompt;
      END;
      sysin.setpos(sysin.pos-1);
      command:- upcase(intext(sysin.length-sysin.pos+1).strip);
      IF NOT interpret←legal←command THEN GOTO prompt;
      do←something←useful;
    END of read←input←command;

    WHILE NOT sysin.endfile DO read←input←command;
  END;
  quit:
END

!            [END of DECOM.HLP]
DIRED - en editor f@r SIMULA direktfiler.
===---------------------------------------

DIRED fr$gar f@rst anv#ndaren efter namn och
imagesize f@r direktfilen. D#refter promptas man med en
asterisk att ge kommandon.
Man kan lista rader, byta ut rader , ta bort rader och
substituera str#ngar.
Man anger radnummer = location i direktfilen.
Hj#lpinformation kan i varje l#ge erh$llas genom att man
svarar med fr$getecken.

Kommandoformat.
←←←←←←←←←←←←←←←←←←

Ett tecken f@ljt av ett radintervall  n-m  (enbart n anger enstaka
rad). UNdantag:  kommandona  HT  och STOP, se nedan.

Editerings-kommandon.
--------------------

R = replace
        ers#tt rader, anv fr$gas efter nya rader en i taget.
D = delete
        tag bort rader
C = change
        byt str#ng i raderna (f@rsta f@rekomsten i varje rad)
        Anv promtas att ange  /gammal str#ng/ny str#ng/
        Alla rader som tr#ffats av editeringen skrivs ut.
L = list
        lista rader p$ terminalen. Sekvensnummer anges i v#nster-kanten.
        rader som inte ryms inom 80 positioner delas upp.
        Tomma rader skrivs inte ut.

Speciella kommandon.
←←←←←←←←←←←←←←←←←←←←←

HT      lista hela filen (dock h@gst 1000 rader)
STOP    avsluta exekveringen

EXEMPEL:

.r dired
Give name of direct file: a.bas
image size: 100
*L1-10


*D22-23
*R30-34
new image (within delimiters): /ny rad 30  /
new image (within delimiters): /ny rad 31 /
new image (within delimiters): /ny rad 32 /
new image (within delimiters): /ny rad 33 /
new image (within delimiters): /ny rad 34 /
*C40-42
CHANGE: /Gamla str#ngen/Nya str#ngen/
*STOP
					figure.hlp page 1:9







FIGURE,
======

SOME BASIC PLOTTING FEATURES IN DEC SYSTEM 10 SIMULA
====================================================

LANGUAGE DESIGNED FOR TEKTRONIX 4012 GRAPHIC TERMINAL
=====================================================




Version 2, January 1975

Author: Ake Blomberg, National Defence Research Institute
	Stockholm, Sweden


					page 2
The Tektronix 4012 terminal is equipped with a screen
divided into 1024*760 raster points, between which an
electron beam can draw visible lines. 
1 cm = 48 or 49 raster points approximately.

The raster points are addressed modulo 1024 in both di-
rections  and the addresses should be transformed to 
characters before transmission to the terminal.

The quality and sharpness of lines may vary over the
screen, but should be adjustable.
Further details concerning the terminal's mode of ope-
ration can be found in the terminal's Users Guide.

The user of a hard copy unit should notice that the
size and shape may be altered on the copy.

Special tty settings may cause failure (e. g. crlf).


The following files contain the code described:

source code:
figure.sim, graph.sim, getch.sim, getch.mac,
rubout.sim, rubout.mac, cosys.sim, cosysf.sim,
macsim.mac, all contained in DTA:DEQZ34 figsim.src.

object code is contained in the library sys:libsim.
(use the search switch when loading, but notice the automatic
 search performed by the Simula RTS).
attribute files are found in sys:libsim.atr.
					page 3
Plotting is achieved in two ways, by using class
figure or class graphics.

Using class figure, one generates figure objects
which in principle consist of text objects each
containing a sequence of plotting commands. The
figure objects can then be plotted, saved on ex-
ternal disk files, reread or transformed.

Class graphics is rather used as a block prefix,
thus allowing the user to operate directly on the
screen, without constructing figure objects.
Class graphics also contains a procedure for con-
trolling the terminals geometric cursor.

Neither class is highly optimized or far developed.
The user should not find it difficult to include
his own special procedures according to diffe-
rent requirements and some optimization may be
achieved by rewriting some procedures in assembly
language or perhaps by turning the security swit-
ches off at compile time.

When drawing lines the terminal is in geometric
mode and cannot produce characters before it is 
reset to alpha-numeric mode. Therefore, runtime
errors during drawing may result in non readable
error messages.

To save some time at execution, the addresses are
not calculated modulo 1024 and therefore runtime
errors may result when attempt is made to plot 
outside screen (usually ZYQ006 error message).
					page 4
Class graphics description
←←←←←←←←←←←←←←←←←←←←←←←←←←

Contained in the files graph.*. Class graphics
requires external character procedure getch,
which accepts single characters from the termi-
nal. Getch is coded in Macro-10 language and
uses macro instructions from the universal
macsim when compiled. Observe that a dummy pro-
cedure in simula is required to generate the
attribute file.


To use graphics, one has to declare

external class graphics=graph;
external character procedure getch;
graphics begin ...

Then the following procedures are available:

move(i,j);	(integer i,j) moves the turned
		off electron beam to the point 
		(i,j) on the screen. Also sets
		geometric mode.

draw(i,j);	draws a line from the previous
		position to (i,j). Assumes that
		geometric mode has been set.

reset←tty;	resets alpha-numeric mode. To
		be used before writing.

getpos(i,j);    gets current location of beam

cursor(c,i,j);	(character c, integer i,j) calls
		the geometric cursor. When push-
		ing a character key this charac-
		ter is sent to c and the address
		of the cursor to (i,j).
					page 5
Class figure description.
←←←←←←←←←←←←←←←←←←←←←←←←

Contained in the files figure.*. Written
entirely in the Simula language.

Should be declared as follows, for the case
of two figure objects:

external class figure;
ref(figure) a,b;
a:-new figure; b:-new figure;

Then the following operations are available
on a and b:

a.origin(ox,oy);  (real ox,oy) sets origin to
		  (ox,oy) measured in raster
		  points. (0,0) is default.

a.scale(sx,sy);   (real sx,sy) sets scale mul-
		  tipliers to (sx,sy) in x- and
		  y-direction. Scale does not
		  affect origin. Default (1,1).

a.checkon;	  turns the sizecheck on.
a.checkoff;
		  When the sizecheck is on, the
		  numbers a.xmin, a.xmax, a,ymin
		  a.ymax are calculated in each
		  following plotstep, measuring
		  the size of a in raster points.
		  Boolean procedure a.on←screen
		  returns true if a is contained
		  within the screen.
		  Checkoff is default.
					page 6
a.moveto(x,y);	(real x,y) moves the turned off
		electron beam to the raster point
		(ox+sx*x,oy+sy*y)

a.drawto(x,y);	(real x,y) draws a lline to the
		raster point (ox+sx*x,oy+sy*y)

a.plot;		plots a on the screen. Does not
		affect the contents of a.

a.addfig(b);	(ref(figure) b) concatenates the
		figure b to a. Does not affect the
		contents of b.

a.write(s);	(text s, text constant allowed)
		writes s into a.

a.savefig(s);	(text s, text constant allowed)
		writes the contents of a onto a
		disk file named s. Does not affect
		the contents of a.
a.getfig(s);	(text s, text constant allowed)
		reads a disk file named s previously
		written by savefig, into a. Old
		contents of a destroyed.

a.recompute;	unpacks the plot characters of a
		into real numbers and transforms
		them again with the current ori-
		gin and scale. Can be used to chan-
		ge origin or scale. Contains the
		decoding procedure for figure ob-
		jects and can be used as a model
		for other tranformations.

					page 7
The formulas for transformation between coordi-
nates and plot characters are contained in the
procedures trans←to←plotchar and recompute. The
plot characters are contained in the text object
T and the integer variable CC is a character
count for T. Most of the time CC = T.pos-1.

The user is recommended not to alter T, T.pos
or CC, which are qualified candidates for the
Hidden declaration, if anytime included in the
Simula language.


To erase the screen the procedure rubout can be
used. It is coded in Macro-10, but does not re-
quire macsim when compiled.


To make a pause in the execution after having
drawn a figure one can write setpos(0); inimage;
Nothing will happen before the Return key is
pushed.


Ref(figure) procedure cosys can be used to con-
struct coordinate systems with tic marks. The
source code contains description.


Ref(figure) procedure cosysfor(xmin,xmax,ymin,ymax)
constructs a coordinate system suitable for the
given extremes.



It should be possible to use the principles of Figure
for other graphic equipments than the Tektronix
4010 series.
					page 8
Example of the use of class graphics
------------------------------------



The procedure cursor can be used to transmit
commands to a program without having the com-
mands echoed on the screen and together with
geometric data.
The following program will allow the user to 
draw straight line figures by adjusting the
geometric cursor and sending a one character
command for moving, drawing or erasing.
It is not difficult to extend the program to
simulate the tools of Euclidean geometry, viz.
ungraded ruler and compasses.


Begin external procedure rubout;
External character procedure getch;
External class Graphics;
Character c; integer x,y;
Graphics begin rubout;
	 while c \= 's' do
	    begin
	    if c='m' then move(x,y)
	    else if c='d' then draw(x,y)
	    else if c='r' then rubout;
	    cursor(c,x,y);
	    end;
	 end*graphics*;
end

					page 9
Examples of the use of class figure
-----------------------------------


Let f denote an already constructed figure.

1. Translate f with (tx,ty) raster points, kee-
   ping the scale:
   f.origin(tx,ty); f.scale(1,1); f.recompute;


2. Change the scale with the factors (sx,sy)
   with fixed origin:
   f.scale(sx,sy);
   f.origin(ox*(1-sx),oy*(1-sy)); f.recompute;


3. Example of a program that will draw six con-
   centric ellipses:


Begin external class figure;  ref(figure) f;
Real w, dw;  Integer i;
f:-new figure; 
f.origin(510,380); f.scale(240,240); f.moveto(1,0);
w:=0; dw:=3.1415926/50;
for i:=1 step 1 until 100 do
begin w:=w+dw; f.drawto(cos(w),sin(w)); end;
f.plot;
for i:=1 step 1 until 5 do
    begin
    f.scale(0.9,0.6); f.origin(510*0.1, 380*0.4);
    f.recompute; f.plot;
    end;
end

--------------------End of Figure.hlp-----------------
     FQC - PROGRAM MEASUREMENT SYSTEM FOR SIMULA PROGRAMS
     ====================================================

     If a SIMULA program has been developed which will be used very
     often, e.g.  as a part in a regularly used production system, it
     is often profitable to spend some efforts on optimization of the
     program.

     A central problem in program optimization is to find the
     innermost loops of the program, and this is often non-trivial.
     Once the execution profile of a program is known it is usually
     easy to make it faster with a few changes such as modifications
     in processing algorithms or by using a small machine language
     subroutine.

     DEC-10 SIMULA is delivered with a frequency measurement system
     which assists in spotting frequently executed parts of a SIMULA
     program.  The system consists of two SIMULA programs, and as an
     indication of its usefulness serves the fact that when the first
     version of the system was applied to itself it was possible to
     double the speed of its largest program with less than two hours
     of analysis, recoding and testing.

     The system is used as follows:

     The program to be analyzed must have been tested well enough to
     run to normal completion.  It is read by the program FQCRED which
     produces two modified versions of it, one of which is a
     compilable SIMULA program and the other a listing later used to
     produce the frequency listing.  The modified compilable program
     is executed and produces, if normally terminated, a file of
     measured frequencies.  This file is merged with the listing
     output by FQCRED in the program FQCLST, which produces the final
     output.

     The measured program should satisfy some restrictions:

     i) A text constant should be contained in one line and it should
     not be longer than 72 characters, otherwise it will be truncated.

     ii) An end comment should not contain the character sequences
     END, ELSE, WHEN or OTHERWISE.

     iii) The program must not contain the identifier Z←Y←Q.

     iv) the program should not use a file on DSK: named D or SYSTAT
     (if so, the file names must be changed by inputting
     specifications to FQCRED of D, to the modified program of SYSTAT
     and to FQCLST of D and SYSTAT).

     v) National letters $, # and @ should not be used in identifiers.

     vi) External classes used in the program will have to be
     recompiled with a higher block level (/E switch).

     The following session illustrates the use of the system on the
     SIMULA program FLOPY.SIM (lower case text supplied by user):


             .copy =flopy.sim/w      ;to remove tabs
             .ru fqcred      ;edits program to be measured
       ENTER FILE SPECIFICATIONS:
             *sysin dsk:flopy.sim
             *punch dsk:flop1.sim
             *
       EXECUTION STARTED
       End of SIMULA program execution.

             .ex flop1(-w)   ;execute modified program
       SIMULA:  FLOP1
       ERRORS DETECTED:
           1 TYPE W MESSAGES
       LINK:   Loading
       [LNKXCT FLOP1 Execution]
       End of SIMULA program execution.

             .ru fqclst              ;edit measurements
       ENTER FILE SPECIFICATIONS:
             *sysout dsk:flop1.lst
             *
       EXECUTION STARTED
       End of SIMULA program execution.

             .type flop1.lst              ;type result


               BEGIN COMMENT FREQUENCY MEASUREMENT EXAMPLE;
               INTEGER I,J,K;
               FOR I:=1 STEP 1 UNTIL 100 DO
            1    !1
               FOR J:=1 STEP I UNTIL 2*I DO
          100    !100
               IF I<J THEN K:=K+1 ELSE K:=K-1;
          200   !200       !100        !100
               END;

       ***MAX FREQUENCY: 200 ******SUM FREQUENCY: 501 ***



     The results shown above can be produced by executing the
     FQC1 and FQC2 Mic macros.

     Simply do:

     /FQC1 flopy
     ... enter possible data while running your program
     After completion of your program do:

     /FQC2 flopy

     You may alternatively submit the following CTL file:

             .COPY =FLOPY.SIM/W      ;TO REMOVE TABS
             .RU FQCRED      ;EDITS PROGRAM TO BE MEASURED
             *SYSIN DSK:FLOPY.SIM
             *PUNCH DSK:FLOP1.SIM

             .EX FLOP1       ;EXECUTE MODIFIED PROGRAM
             .RU FQCLST              ; EDIT MEASUREMENTS
             *SYSOUT DSK:FLOP1.LST

             .TY FLOP1.LST           ;TYPE RESULT


     The program FQCRED can be used to produce an indented source
     version of a SIMULA program.  Precede the original source with
     two lines:

          %NOTRACE
          %INDENT=4

     After running FQCRED the indented program is on the file D.  

	[End of FQC.HLP]
     LIBSIM
     ======

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

     The routines are loaded from SYS:LIBSIM and thus available in your
     program if you declare them as external at the beginning of your
     program, e.g.

     EXTERNAL CLASS safeio;
     EXTERNAL PROCEDURE hash;

     You need not mention any explicit filename if you are using
     routines in LIBSIM on the SYS area or on your own area.  An
     external declaration in a separately compiled segment must be
     repeated in all dependent separately compiled segment including the
     main program.

     For accessing routines on other libraries, see the DECsystem-10
     SIMULA Language Handbook part II chapter 7.1.1.

     When you load your programs with the "LOAD", "EXECUTE" or "DEBUG"
     command of DECsystem-10, you need not mention these 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 is a macro LIBSIM.MIC available for creating and making
     directories of LIBSIM-s.  Write "/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, they
     may still be found on the SIMULA distribution tape.  REL and ATR
     files for separately compiled procedures or classes can be found in
     the libraries LIBSIM.ATR and LIBSIM.REL on the SYS: area.

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

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, M=MAIN
PROGRAM.

The first column for each program indicates type of result for function
procedures, K for separately compiled classes, M for main programs(not
in LIBSIM).  The following letters indicate parameter types.

1. UTILITY 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 DBMTXT, DBM, DBMSET and the
                         main programs FETCH, LOAD, DIRED, SPEC and PREP
K I,I     STORE          Simple text-oriented DBMS
K         SELECT         Boolean condition searching TEXT or FILE
K         FIGURE         Plot package for Tektronix plotter.  GRAPHI,
                         COSYS, COSYSF and RUBOUT are also part of this
                         package.  See FIGURE.HLP.
K I,I,X,B,I VISTA        Full control of infoton vista terminal display
                         screen, e.g.  to produce moving pictures
K T       DAHELP         Give user help message when running SIMULA
                         program.  Uses direct-access file to store help
                         messages.  See DAHELP.HLP
B T,T,I,I SQHELP         Give user help message when running SIMULA
                         program.  Uses sequential file to store help
                         messages
K I       DECOM          (Subclass to SAFMIN) Interpret input command of
                         the format
                         outfil.ext/switch1/switch2...
                         =infil.ext/switch3/switch4...
M         SIMDEM         SIMULA demonstration programs

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         SIMSTR         [NOT READY] Automatic structure abstract of
                         source 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         Produce a directfile from a sequential file
M         FETCH          General-purpose SIMDBM Data Base Manipulator
M         MAKHLP         Create help file for use with DAHELP

4. PROCEDURES NOT WRITEABLE IN SIMULA:

                         4.1 TIME AND DATE

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

                         4.2 REAL TIME
                         [PRE-RELEASE VERSION]

B X       INPUTCHECK     Anything to read on file X?
P R       SLEEP          Delay execution for R real seconds
I Xa,R    INPUTWAIT      Sleep until anything to read
K         REALTIME       Scheduler for terminal processes

                         4.3 INPUT/OUTPUT

I X       LINECOUNT      Return LINESPERPAGE setting
I X       FILENAME       Give TEXT with FILE object generation parameter
C         GETCH          Input character, do not wait for carriage
                         return (input from controlling terminal only) P
                         X,C,I OUTCHR Character output bypassing image
P ILRCPa..  READ         Read many values in standard format
P ILRCTPa..  WRITE       Write 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    Delete file on secondary storage
X T       FINDINFILE     NEW INFILE, but no error if file does not exist
X T,B     FINDDIRECTFILE NEW DIRECTFILE but no error if not found or not
                         updateable
X T       FINDOUTFILE    NEW OUTFILE, but no error if write protected
X T       FINDPRINTFILE  NEW PRINTFILE, but no error if write protected
I X       LASTLOC        Highest written line in a DIRECTFILE
P X       DOTYPEOUT      Reset CTRL-O bit to resume terminal output
I I,X,I   TRMOP          Modify monitor-terminal interface
B         NUMBERED       Did last inimage get a line-numbered line?
P X,I     ECHO           Suppress monitor echoing of terminal input
T T       TMPNAM         Create a temporary file name like "021SIM.TMP"

                         4.4 CONTROLLED ERROR HANDLING

P B       ENTERDEBUG     Transfer to SIMULA debugging system
P T       ABORT          User program generated error interrupt
P T,I     RUN            Run a new program under the current job

                         4.7 SAVE-RESTORE FACILITY
                         [PRE-RELEASE VERSION]

I T,B     SAVE           Save current main memory on a file
P T       RESTORE        Resume execution from save file
P I       FREEZE Exit to monitor with job ready to save

                         4.8 ENVIRONMENT ENQUIRY

I         MAXINT         Largest positive INTEGER
R         MAXREAL        Largest positive REAL

                         4.9 PACKING INTO PARTS OF WORDS

B IRLa,I,IRLCBTa,I,.. PACK Pack many variables of varying type (not REF)
B IRLa,I,IRLCBTa,I,.. UNPACK Reverse of pack


5. PROCEDURES (ALMOST) 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 argument position
T T,I     UPTO           Subtext before argument position
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        Return indexed CHARACTER from a TEXT
P T,I,C   DEPCHAR        Deposit a character at indicated position
T T,I,I   TSUB           Perform SUB returning NOTEXT instead of error

                         5.2 SEARCHING AND TESTING OF TEXTS

T T,C     SCANTO         Next occurrence of CHARACTER in TEXT
T C       SKIP           Skip all characters equal to argument from pos
                         and on
B T1,T2   FRONTCOMPARE   Does rest of TEXT T1 begin with subtext = T2?
B T1,T2   UPCOMPARE      Same as FRONTCOMPARE, but upper and lower case
                         characters are regarded as equal
T T1,T2   SEARCH         Find first subtext = T2 after POS in T1
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           Compute hash value from text in interval
                         [0:I-1]
C T,T     FINDTRIGGER    Next occurrence of any character in a given
                         string
B T,I,Ta,I MENU          Search for unambiguous text in a text array
B T,Ta,I,I,I LOOKUP      Perform binary search in sorted text array

                         5.3 OPERATIONS ON TEXTS

T T,T     CONC2          Concatenation of TEXTs, two parameters
T T..     CONC           Concatenation of TEXTs, variable no.  of
                         parameters
B T1,T2   PUTTEXT        Copies value of T2 at POS in T1
T T       UPCASE         Convert lower case letters to upper case
T T       LOWCASE        Convert upper case letters to lower case
T C,I     MAKETEXT       NEW text with all I characters equal to C
T T,C     COMPRESS       Remove given character from text
I T       STARTPOS       Return starting position for a (sub)text
P T,T,T,T SPLIT          Split a text at given delimiter
I T,T,T,T SPLITA         Split a text and store the parts in a text
                         array
B T,T,T   CHANGE         Replace old (sub)string with new string in a
                         master text
L T       SCANREAL       GETREAL but safe from bad data interrupt
I T       SCANINT        GETINT but safe from bad data interrupt
I T       SCANFRAC       GETFRAC but safe from bad data interrupt
I T,Ra,I  GETARRAY       [NOT READY] Reads from a text real values into
                         a REAL ARRAY
I T,Ia,I  GETINTARRAY    [NOT READY] Ditto INTEGER ARRAY
I T,Ra,I  GETLONGARRAY   [NOT READY] Ditto LONG REAL ARRAY
T T,T     CHECKEXTENSION Add defaultextension if file spec contains no
                         dot

                         5.4 INPUT/OUTPUT

C X       LOOKAHEAD      Next non-blank character readable by INCHAR
T T,X     INLINE         Type out a prompting question and copy an
                         infile image (stripped)
P RCIX    OUTTIME        Converts simulated time to hh:mm:ss.cc format
                         and prints it on a given outfile

                         5.5 SORTING AND SUMMATION ETC.

I R       ILOG           Return integer part of 10LOG(|arg|)+1;  if 0
                         return 0.  I.e.  Number of integer digits if
                         |arg| >= 1 else number of leading zeros after
                         decimal point.
I Ia,I    ISUM           Return sum of an integer array
L La,I    LSUM           Return sum of long real array (almost)
                         preserving precision
R Ra,I    RSUM           Return sum of real array
P R,R,I,R SIGMEAN        Return current variance and mean value
                         including new observation
P "x"a,I  SORTxy         Sort 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.

                         5.6 RANDOM NUMBER GENERATION ETC.

P Ia,I,I,I SCRAMBLE      Random permutation of aray
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

6. SWEDISH LANGUAGE TEXT PROCESSING AND INPUT/OUTPUT

B T,I,Ta,I MENY          Swedish version of MENU
                         [Accept $, #, @ and ← as letters.]


     The Swedish National Defense Research Institute, DEC or DECUS
     assume no responsibility for damage because of faults in these
     programs.

     [END OF LIBSIM.HLP]
LOAD - a program for loading a sequential file
==============================================
to a SIMDBM data base.
=====================

This program takes a sequential file with data fields
bound to fixed positions, and loads records in a SIMDBM
data base containing these fields.

The data base file must have been initialized previously
by running SPEC. The relevant record type containing
the fields needed must have been specified.

LOAD asks the user for the name and linelength of
the input file, and the record type. These are given on one
line as three items separated with commas.

Then an asterisk is used to prompt for field specifications.
They are are given one per line as the following four items
separated with commas:

   FIELDNAME   must be a field defined in data base record.
   FIELDPOS    start of field in sequential input file
   FIELDLENGTH length of input field, left blanks are
               removed for texts before storing in data base.
   FIELD TYPE  type of field, 1 for integer, 3 for text
               numeric fields are checked by LOAD.

The sequence of specificatons is ended with a period.
Should the user be uncertain as to the proper field names
available, the command .FIELDS can be given. LOAD will
then print a specification of them.
Help information can always be requested by typing
a question mark.

Whenever an error message is given for a specification,
it should be given again immediately.


EXAMPLE:
========

Suppose you have a file PERSON.DAT containing data in columns
1,21,41 and 51, which contain NAME,ADRESS,AGE
and INCOME for a number of persons and you want
these fields stored in a SIMDBM data base PERSON.BAS
We presuppose SPEC has been used to create a record
type PERSON with the fields mentioned, and that
NAME and ADRESS are texts, AGE and INCOME integers.

This is done by running LOAD in the following way:


   Give name of data base file:PERSON.BAS
   Image size: 72
   Ge infil,blk,postnamn: PERSON.DAT,80,PERSON
   *NAMN,1,20,3
   *ADRESS,21,20,3
   *AGE,41,10,1
   *INCOME,51,10,1
   *.

			MAKEDF
			------

The MAKEDF produces a SIMULA Directfile from a conventional
sequential file. Note that an imagesize = x such that x+2 mod 5
= 0 will make carefull (preserving line length x) text editing
possible.  Simply type:

.R MAKEDF
Input:myseq.ext
Imagesize: <Integer item>
Output(DA):mydirf.dat

		[End of MAKEDF.HLP]
			MAKHLP
			------

The MAKHLP program modifies or creates a DAHELP
Direct Access Help file by appending named sequential file
references.

MAKHLP can not delete any parts of the Direct Access
file. For such purposes - reconstruct the file from scratch
or use the DIRED program to patch up the file according to
DAHELP format (imagesize:73). See DAHELP.HLP for more
information.

IMPORTANT - never change the number of symbols per line
equal to 73 + <CR> + <LF> in a Direct Access DAHELP File.
(Since (imagesize+2) mod 5 = 0 TECO may be used, but CAREFULLY!!)


Note! The input file(s) may not contain the character '}'
(tilde - ASCII 176 octal) in column 1 (it will disappear).

Requested information is -

1. Name of DAHELP file to be created. Default extension is .HLP.

2. Name(s) of sequential input files to be appended.
   (Default extension is .HLP)

3. For each input file - enter DAHELP file ENTRY key word.
   Up to 64 upcased characters will be included.
   If no answer (i.e. empty line), the input file name will be used.

   End dialogue with EXIT (or ↑Z).

		[End of MAKHLP.HLP]
			SAFEIO
			------

SAFEIO is a SIMULA external class which can be used when
writing the conversational parts of SIMULA programs.

The SAFEIO system offers the following facilities in
a single procedure call :

1.	Issue a prompting question to the user.

2.	Store the input in a simple variable.

3.	Optionally accept default answers (equal to CR).

4.	Check the syntax of the input.

5.	Issue an appropriate message if the input is invalid.

6.	Issue a informative message if the user responds with
	anything starting with a questionmark '?'.

7.	Allow the user to substitute tty input for disk file input.
	This may be requested at any question.

8.	Allow the user to save all accepted program input on a disk file.
	This file may be used as an input file in a subsequent run.
	Correspondence between saved and current question will
	be checked (option by default).

It is assumed that the user types in only one item into each
input line.

The format of a question to the user is:

REQUEST("prompting question",default,***input(variable,validity),
" error message if not valid",helpproc←expression);

The parameter default is a text variable or text constant
(or may be a call of a text procedure). There is a SAFEIO attribute
NODEFAULT which can be used if default answers should be
prohibited.

The *** may be INT,REAL,LONGREAL,BOOL or TEXT.
For the BOOLINPUT procedure there is only one argument though, the
receiving variable.

The validity is usually a boolean expression involving the
variable but may also be a call of a boolean procedure
if more complicated validity checking is necessary.
If the SAFFEIO attribute CHECKVALIDITY is set to FALSE, no
validity checking (i.e. no evaluation of the 2nd parameter to
the ***input procedure) will occur, thus speeding up
SAFEIO execution. Note, however that this will endanger the
security of your program.


The error message is printed if the validity becomes FALSE.
The prompting question will then be repeated.

The helpproc←expression which will be evaluated each time the
user types in an answer beginning with a questionmark '?'.

The SAFEIO boolean procedure HELP (with one text parameter =
the help text) may be used for displaying a text on the user's TTY.

If no special information should be issued the SAFEIO procedure
NOHELP may be used. (The message - "There is no help in this case."
will be issued.)

Some examples:

BEGIN
    EXTERNAL REF (Infile) PROCEDURE findinfile;
    EXTERNAL REF (Outfile) PROCEDURE findoutfile;
    EXTERNAL TEXT PROCEDURE conc,upcase,frontstrip,rest,checkextension;
    EXTERNAL CHARACTER PROCEDURE fetchar,findtrigger;
    EXTERNAL LONG REAL PROCEDURE scanreal;
    EXTERNAL INTEGER PROCEDURE checkreal,checkint,scanint,ilog;
    EXTERNAL BOOLEAN PROCEDURE menu;
    EXTERNAL CLASS safeio;

    safeio(..<name of recording file saving the input or "">,
	<"English" or "Swedish">..)
	! Use "English" if english texts are wanted.
	  Use "Swedish" if swedish texts are wanted. ;

    BEGIN
	INTEGER i;   REAL x;   LONG REAL y;   TEXT t;   BOOLEAN b;
	TEXT ARRAY table[1:4];

	request("Enter integer:","14",intinput(i,irange(i,1,20)),
	   outofirange(i,1,20),help("...info issued at '?'.."));

	! The default value is 14. Only positive numbers are allowed.;
	! Note the use of the procedures IRANGE(i,low,high) and
	! OUTOFIRANGE(i,low,high). See also Summary Chapter 5
	! in SAFEIO.MAN.;

	request("Enter real item:",nodefault,realinput(x,TRUE),"",nohelp);

	! Default answer not allowed. Any legal real item is accepted
	  since validity is TRUE. No help information available.;

	request("Enter long real value:","E1",longrealinput(y,y NE 0),
	   "? Must not be zero.",nohelp);

	! Default value is 10 = E1;

	request("Enter yes or no:",nodefault,boolinput(b),"",nohelp);

	! Note that procedure boolinput has just one parameter.;

	table[1]:- Copy("START");
	table[2]:- Copy("END");
	table[3]:- Copy("GO");
	table[4]:- Copy("GOTO");

	request("Enter command:",nodefault,textinput(t,menu(t,i,table,4)),
	   commandmessage(index),commandhelp(table,4));

	! Note that the table must contain no lower case letters.
	  The user may use an abbreviated form when no ambiguity exists.
	  (Exact matches are always considered correct.)
	  The variable i will return the table index.
	  The length of the table (4) must also be supplied.
	  The procedure MENU resides in LIBSIM and checks
	  for correspondence between the T and the table.;
	  The text procedure commandmessage will tell the user
	  if his (illegal) command was either Unknown or Ambiguous.

	! A simple text request: ;

	request("Enter A or B:","A",
	   textinput(t,t = "A" OR t = "B" OR t = "a" OR t = "b"),
	   "? Answer A or B.",nohelp);

	! The user may define his own boolean procedure for input
	  validation if more complicated tests are necessary.;

	GO TO start;	! Will restart from SAFEIO prefix beginning;
			! START is a SAFEIO label located just
			! in front of INNER.;

	! If label EOF exists, End-of-file on SYSIN (=↑Z)
	! will jump to this label. If not existing in the
	! user program, the safeio block will terminate
	! through an internal safeio jump.
	! NOTE! Once Sysin.Endfile is TRUE, there can be no
	! more input on Sysin!. This mechanism will only work
	! for safeio prefixed blocks (i.e. NOT using NEW SAFEI(O)).;

    END of safeio block;

END of program;



At any question the user may input one of the SAFEIO commands:


?         gives help information.

!         FOLLOWED by:

*         changes the switch: Display-prompting-question.
/         changes the switch: Display-default-value.
=         changes the switch: Display-input (+ the *- and /-switches).
[         changes the switch: Trace (file messages).
+         closes and reopens current recording file in append mode.
;         treats line as a comment.
%         calls special procedure.
&         followed by input overrides validity test.
<FIL.EXT  opens new input file in waiting mode. Default extension =.saf
←         continues input in nowait mode.
<         closes current input file.
↑         closes all active input files.
←FIL.EXT  opens new input file in nowait mode. Default extension =.saf
>FIL.EXT  opens new recording file. Default extension =.saf
>         closes current recording file.
?         prints this text.

Anything else following ! is just displaying current question.

The != command will always change the values of the switches
Display-prompting-question and Display-default-value to the same value
as the switch Display-input.

Note that the !& facility may be switched off by calling
the procedure NOOVERRIDE.

The !% facility gives the programmer the possibility to declare his
own procedure SPECIAL (with exactly that name and without parameters)
which will be called when the user responds with !%. It is
possible to interpret the information following the !% in the
procedure, thereby expanding the power of the SAFEIO - ! commands.
See SAFEIO.MAN for further information on SAFEIO attributes.

If you are using SAFEIO by INSPECT it is no use specifying any
initial recording file, since it will be immediately closed. This
is because the INNER in SAFEIO will be passed. In order to
close all possible open SAFEIO files, end the connection block with
a call of the SAFEIO procedure closefiles. I.e. :

BEGIN   EXTERNAL declarations.....;

    ....
    INSPECT NEW SAFEIO("","") DO	! Default language is english ;

    BEGIN .... using safeio ......
	closefiles;
    END;

END program

By substituting the class SAFEIO by CLASS SAFEI (with the language
parameter only) the facilities numbered 1 to 6 will still be present
while the file handling facilities will absent. The class SAFEI
will require about 2/5 of the memory of SAFEIO.

By substituting to SAFMIN still more SAFEIO facilities
are excluded. See SAFMIN.HLP. Size of SAFMIN is about 1/2 of SAFEI.

The three classes SIMMIN, SIMEI and SIMEIO are identical with SAFMIN,
SAFEI and SAFEIO respectively in all respects but prefixed with
SIMULATION.


	[End of SAFEIO.HLP]
			SAFMIN
			------

SAFMIN is a SIMULA class which is designed to faciliate the
programming of conversational parts of SIMULA programs.
SAFMIN is a reduced variant of the SAFEI class.
SAFMIN does not contain the file handling facilities
and has thus no SAFEIO command (!...) functions.
Neither has SAFMIN the following SAFEI(O) properties:

1.	LONGREALINPUT
2.	IRANGE, RANGE
3.	OUTOFIRANGE, OUTOFRANGE
4.	COMMANDHELP
5.	COMMANDMESSAGE
6.	LANGUAGE FILE
7.	LOG FILE, COMMAND FILE
8.	PRINTINT, PRINTREAL
9.	INTPUT, REALPUT, FRACPUT

The procedure HELP accepts only texts not longer than Sysout.Length.
For more information, see SAFEIO.HLP and SAFEIO.DOC bearing in mind
the excluded facilities listed above.

Declaration example:

BEGIN
EXTERNAL TEXT PROCEDURE rest,upcase;
EXTERNAL LONG REAL PROCEDURE scanreal;
EXTERNAL INTEGER PROCEDURE scanint;
EXTERNAL CLASS safmin;		! Use SIMMIN for Simulations;

safmin BEGIN			! No parameters!;
	... calls to REQUEST
	eof:			! Go here if input terminated (by ↑Z);
	... start calculations
	END prefixed block
END of program

		[End of SAFMIN.HLP]
                                 SELECT
                                 ======

SELECT is a separately compiled SIMULA  CLASS  to  enable  searching  of
texts or files applying BOOLEAN search criteria like

"SWEDEN+DENMARK&-COPENHAGEN"

meaning that you want to find all lines or records which contain  either
the word "SWEDEN" or the word "DENMARK" but not the word "COPENHAGEN".

SELECT contains procedures to

a) Convert a text containing  such  a  BOOLEAN  search  formula  into  a
formula tree suitable for fast searching.

b) Procedures for applying such a formula tree to  a  text  or  part  or
whole of a text array.

The allowed operators in the formula are +(=OR),  &(=AND),  -(=NOT)  and
the  left  and  right  parenthesises,  ( and ).  If parenthesises do not
indicate otherwise, + is assumed to have the lowest  priority,  followed
by &, - and the parenthesises.  These operator characters can be changed
by the user.

SELECT does not contain any input/output procedures.

Accessible attributes of the CLASS select:


BOOLEAN PROCEDURE BUILD←CONDITION

          Translates a  text  string  like  "SWEDEN+DENMARK&-COPENHAGEN"
          into a formula tree
                                (OR)
                           SWEDEN   (AND)
                              DENMARK   (NOT)
                                      COPENHAGEN

          This tree can later  be  used  to  scan  a  text  through  the
          procedures  LINE←SCAN  and  ARRAY←SCAN.   BUILD←CONDITION will
          return FALSE if the input formula had bad  syntax,  e.g.  with
          non-balancing  parenthesises.   In  that  case, an appropriate
          error message is returned in the text SELECT←ERRMESS.

          Parameters to BUILD←CONDITION:

          REF (OPERATOR) TREE←TOP returns the formula tree.

          TEXT SELECTOR contains the input formula text.  SELECTOR  need
          not  contain  any  operators,  in which case it simply means a
          search for that whole  text.   If  SELECTOR  ==  NOTEXT,  then
          TREE←TOP  returns  NONE,  which  means  a formula matching all
          scanned texts.

          BOOLEAN CASESHIFT:  If TRUE, upper and lower  case  characters
          will be regarded as identical.


BOOLEAN PROCEDURE LINE←SCAN

          sapplies a scanning formula to a TEXT.  Returns  TRUE  if  the
          formula  is  satisfied  by  segments of the TEXT.  The formula
          "SWEDEN+DENMARK&-COPENHAGEN" is for example TRUE for the  TEXT
          "DENMARK  IS  A  EUROPEAN  COUNTRY"  but not TRUE for the TEXT
          "COPENHAGEN IS THE CAPITAL OF DENMARK".

          Parameters to LINE←SCAN:

          REF  (OPERATOR)  TREE←TOP  is  a  formula-tree   produced   by
          BUILD←CONDITION.   If  this  parameter is NONE, LINE←SCAN will
          always return TRUE.

          TEXT INLINE is the text to which the formula is to be applied.
          If  TREE←TOP =/= NONE AND INLINE == NOTEXT, then FALSE will be
          returned.


BOOLEAN PROCEDURE ARRAY←SCAN

          is similar to LINE←SCAN, but will apply the formula to several
          lines of TEXT comprising part or the whole of a TEXT array.

          Parameters to ARRAY←SCAN:

          REF  (OPERATOR)  TREE←TOP   is   the   formula   produced   by
          BUILD←CONDITION.

          TEXT ARRAY LINES is the array  of  text  lines  to  which  the
          formula is to be applied.

          INTEGER I1, I2 are the lower and upper bound of the  lines  in
          the  TEXT ARRAY to which the formula is to be applied.  I1 may
          be larger than the absolute lower bound of the array,  and  I2
          may be less than the absolute upper bound of the array, if you
          only want to apply the formula to part of  the  lines  in  the
          whole  array.   If  TREE←TOP  ==  NONE,  TRUE  will  always be
          returned.  If TREE←TOP =/= NONE AND I2 < I1, then  FALSE  will
          always be returned.


PROCEDURE TREE←PRINT

          will print a formula tree on SYSOUT in the format
          (SWEDEN+(DENMARK&(-COPENHAGEN)))
          i.e. fully parenthesized to show any  default  assumptions  of
          operator  priorities.   Outimage  should be called immediately
          after TREE←PRINT.

          Parameters to TREE←PRINT:

          REF (OPERATOR) TREE←TOP is the formula tree to be output.


PROCEDURE SET←OPERATOR←CHARACTERS

          will tell the package which  characters  are  to  be  used  as
          delimiters  in  formulas  input to BUILD←CONDITION.  A default
          assumption is made if SET←OPERATOR←CHARACTERS  is  not  called
          from your program.

          Parameters to SET←OPERATOR←CHARACTERS:

          TEXT T:  This TEXT should always be of length  5  and  contain
          the following five characters:

                    Default Character
                       +    OR
                       &    AND
                       -    NOT
                       (    LEFT PARENTHESIS
                       )    RIGHT PARENTHESIS


TEXT SELECT←ERRMESS

          If BUILDCONDITION finds a syntax error in  the  formula,  this
          TEXT  will  return an appropriate error message.  You can thus
          combine SELECT with SAFEIO and write e.g.:

                  request("Give selection criteria:",
                  NOTEXT,textinput(line1selector,
                  buildcondition(condition,selector,caseshift)),
                  selecterrmess,myhelp("SELECT"));


CLASS OPERATOR

          Is the qualification to be used when you declare formula  tree
          variables in your program, e.g.:

                    REF (OPERATOR) selector1, selector2;


OPTIONS(/l); COMMENT demonstration example for SELECT;
          COMMENT this program will list all lines in an input file
          which satisfy a selection formula;
          BEGIN
            EXTERNAL TEXT PROCEDURE rest, upcase;
            EXTERNAL TEXT PROCEDURE scanto, from, conc;
            EXTERNAL CHARACTER PROCEDURE findtrigger;
            EXTERNAL BOOLEAN PROCEDURE frontcompare, puttext;
            EXTERNAL INTEGER PROCEDURE scanint, search;
            EXTERNAL CLASS select;
            select BEGIN
              REF (operator) formula;
              LINECOPY←BUFFER:- blanks(150);
              ask←for←formula:
              outtext("Input selection formula:"); breakoutimage;
              inimage;
              IF NOT build←condition(formula,
              sysin.image.strip,TRUE) THEN
              BEGIN outtext(select←errmess); GOTO ask←for←formula;
              END;
              tree←print(formula); outimage;
              INSPECT NEW infile("Infile *") DO
              BEGIN
                open(blanks(150)); sysout.image:- image;
                WHILE NOT endfile DO
                BEGIN
                  inimage;
                  IF line←scan(formula,image.strip) THEN outimage;
                END;
                close;
              END;
            END;
          END;


EFFICIENCY CONSIDERATIONS:

          You need not consider this section to make the select  package
          work, only if you want to make your programs more efficient.

          Scanning of non-significant texts takes time,  especially  for
          complex  formulas requiring many scans of the text.  In such a
          case you can often save time by  only  applying  LINE←SCAN  or
          ARRAY←SCAN   to   those  parts  of  your  text  which  contain
          information, e.g. by supressing non-significant  blanks.   The
          simplest  case  of this is to strip your texts before scanning
          them.

          LINE←SCAN on a long text is more efficient than ARRAY←SCAN  on
          several  shorter  texts,  especially  if  CASESHIFT  is  TRUE.
          Sometimes, you can let your array elements be  subtexts  of  a
          common main text, and apply LINE←SCAN on part or whole of this
          main text  instead  of  ARRAY←SCAN  on  the  array.   However,
          ARRAY←SCAN is faster than LINE←SCAN if the total length of the
          scanned texts becomes  smaller,  e.g.  if  use  of  ARRAY←SCAN
          allows  you to avoid scanning of blanks at the end of lines in
          the text.



     TEXT LINECOPY←BUFFER

          LINECOPY←BUFFER is a text attribute to  select  used  to  keep
          copies  of  the  texts to be scanned when caseshift = TRUE and
          when the number of array elements to be scanned by  ARRAY←SCAN
          is larger than 10.

          Sometimes you  can  improve  efficiency  by  assigning  values
          yourself  to  this  buffer.  Do not make assignments to it too
          often.


     TEXT LINE

          If you want to write your own procedures similar to  LINE←SCAN
          and  ARRAY←SCAN  you  need access to this attribute of SELECT,
          which internally refers to the lines to be scanned.

                          [END OF SELECT.HLP]
SIMDBM version II  -  augusti -75.
==================================

F`ljande filer finns tillg{ngliga p⎇ [105,121]:

DOKUMENTATION.
-------------

SIMDBM.RNO
	Beskriver grundsystemet. Inneh⎇ller {ven relativt utf`rliga
	exempel p⎇ SIMULA-program som anv{nder systemet.

FETCH.RNO
	Beskriver programmen FETCH och SPEC som kan anv{ndas f`r att
	initialt skapa en databas.

LOAD.HLP
	Beskriver programmet LOAD som fr⎇n en sekvensiell kolumnbunden
	textfil skapar en SIMDBM-databas enligt specifikationer
	som ges interaktivt.

SEPARAT-KOMPILERADE SIMULA-KLASSER.
-----------------------------------

F`ljande filer finns med vardera tre extensions SIM, ATR och REL
och kan anv{ndas om man vill skriva egna program som utnyttjar
systemet. Se exempel i SIMDBM-rapporten appendix II och IV.

Filerna finns nu i biblioteket LIBSIM.REL  +  LIBSIM.ATR[105,121]
och blir automatiskt tillg{ngliga om dessa filer kopieras `ver till
den egna arean och man anv{nder n⎇gra av dem som prefix till
sitt program.

DBMTXT		har SAFEIO som prefix
DBM		alla procedurer utom de som hanterar SET.
DBMSET		hantering av set
DBMDAT		f`r initiering, kan {ven kopieras direkt i programmen.

Om man inte anv{nder SET eller proceduren DELETE, {r det tillr{ckligt
med DBMTXT och DBM i prefixkedjan.

Observera att f`ljande kommandon tillfogats i FETCH och finns
beskrivna i den aktuella upplagan av FETCH.RNO:

DELETE     f`r borttagande av poster ur databasen.
REMOVE     f`r att ta bort poster ur ett set.
TABLE      f`r att vid s`kning via .and och .or kunna f⎇ utskrivet
           data f`r funna poster som en formatterad sekvensiell fil.

SAV-FILER.
===========

(Om de inte skulle finnas p⎇ ppn [105,121] s⎇ finns alltid en
aktuell kopia p⎇ DEC-tapen H38O05).

FETCH.SAV
F0.SAV		(n{rmast f`reg. version av FETCH)
SPEC.SAV
LOAD.SAV	(skaper en SIMDBM-databas fr⎇n en sekvensiell fil)
PREP.SAV
PREP1.SAV
SELECT.SAV	(skapar en ny SIMDBM-databas som {r en delm{ngd av den som
		tas som indata)



PLANER F@R FRAMTIDEN.
=====================

Rapporten  "DBMSIM  -  ett programpaket f`r databashantering
i SIMULA"  {r n{stan helt inaktuell, det mesta av dess inneh⎇ll
finns nu i den rapport som ligger i SIMDBM.RNO.

Ytterligare dokumentation kommer senare under h`sten bl annat
f`ljande:

(a)  Om internstrukturen
     Det som tidigare skrivits om internstrukturen {r nu helt
     inaktuellt.
(b)  Om de tv⎇ preprocessorna PREP och PREP2 som genererar SIMULA-kod
     fr⎇n den lagrade dataspecifikationen.
(c)  Om ett reorganisationsprogram REORG, som l{ser hela eller en
     delm{ngd av en databas och skapar en ny ren s⎇dan. (detta program
     {r under utarbetande)
--- SIMEXP program Version 1.0 ---
Date:	74-10-16
Author:Mats Ohlin, FOA 1, Fack, S-104 50 STOCKHOLM, SWEDEN.
The SIMEXP program creates one complete main program source file by
copying the external SIMULA modules referenced in the original main module.

The files must NOT contain line numbers. Please remove line
numbers with .COPY =A.SIM(N) before using SIMEXP. New line
numbers can be created after processing with .COPY =B.SIM(S).

N.B. SIMEXP program may NOT be used on files with references to
external FORTRAN or MACRO routines.

The user is asked for the following information:-

1.	The file name for the main program module.
2.	The name of the output file (if no name is given a spooled LPT
	file is generated).

(N.B. SIMEXP can also be used for merging external file(s) into another
external file.)

	[End of SIMEXP.HLP]
--- SIMIBM --- Program Version 1.1
Date: 76-02-27
Author:Mats Ohlin, FOA 1, Fack, S-104 50 STOCKHOLM, SWEDEN.

The SIMIBM program converts SIMULA programs from DEC-10 to
IBM 360/370 representation.

N.B. The program to be converted MUST NOT contain line
numbers, please remove them with
.COPY = x.sim(N) before processing.

The following conversion problems must be considered
by the programmer:-

1. The use of the standard procedures Rank and Char gives
   different result on IBM.
2. The file names for IBM must contain no dot or ppn and must not
   be longer than 8 characters.
3. All OPTIONS statements are converted to COMMENTs.
   For OPTIONS(/P)  use %PAGE on a single record.
   For OPTIONS(/P:"title")  use %TITLE    title    on a single card.
4. External modules are not implemented the same way as in DEC-10 SIMULA.
   Use the SIMEXP program in order to resolve these references before
   you run SIMIBM.
5. The maximum integer value is 2↑31-1 = 2 147 483 467 on IBM.
6. Radix constants with base not equal 16 is not supported
   in IBM SIMULA. The format for hexadecimal constants is different.

See also SIMULA Language Handbook, Part 2, Chapter 4.

The SIMIBM program makes the following conversions:-

1. All lower case letters are translated to upper case.
2. Long real constants are converted according to IBM
   standard.
3. All calls to standard procedure BREAKOUTIMAGE are
   replaced with OUTIMAGE.
4. The special COMMENT symbol '!' is converted to COMMENT.
5. The exponentiation symbol '↑' is converted to **.
6. All square brackets '[' ']' are converted to parenthesises ( ).
7. All lines longer than 72 characters are cut at an appropriate position.
   However, numerical constants containing blanks or tabs could
   occasionally be improperly cut.
8. The NOT symbol '\' and the NOT-EQUAL symbol '\=' are converted
   to NOT and NE respectively.
9. All TABs are converted to blank(s).
10.All OPTIONS statements are converted to COMMENTs.

The program needs the following information from the user:-

1. The name of the file containing the program to be converted.
2. The name of the output file.

		[End of SIMIBM.HLP 76-02-27]
                           SIMULA information
                           ==================


     SIMULA version 3 (compiler  and  run  time  system)  is  now
     available.
     About 20 bugs, mostly  infrequent  or  harmless,  have  been
     corrected.
     The HIDDEN PROTECTED feature has been implemented.
     New facilities  have  been  added  to  SIMDDT.   It  is  now
     possible  to  continue  processing  after  some errors.  The
     CLOSE, NOPROCEED  and  @  commands  have  been  added.   The
     NOARRAY  command  has been removed but the switches /-ARRAY,
     /-TEXT and /-GC may be used to reduce the output.  THIS  and
     QUA  are accepted in an identification.  Complete blocks can
     be output with the *  feature.   ↑C  REENTER  will  end  the
     processing  of  the  current  SIMDDT command.  The VARIABLES
     command will also output TYPE PROCEDURE values.  All special
     characters  in a TEXT variable are replaced by ↑ letter when
     SIMDDT outputs the variable value.
     At end of execution only the  SYSIN  and  SYSOUT  files  are
     closed automatically.  An error will be given if other files
     are open and the new SIMDDT command close  may  be  used  to
     close them.

     Changed syntax of text constants:  Long text  constants  can
     now  be  written in several parts, which may be separated by
     spaces, tabs or line control characters.  Example:
         t:-Copy("first part" "second part"
          "third part");
     Release 2 information:
     ATR-files as well as REL-files generated by the new  version
     can  be  members  of a library (see /FUDGE switch to COMPIL,
     FUDGE  command  and  FUDGE2  program).   Loading  of  SIMULA
     programs  has  been  simplified.   If  some  conventions are
     observed, only the main program name need be mentioned  once
     external  classes  and/or  procedures have been compiled and
     possibly put into libraries.
     LIBSIM.REL and  LIBSIM.ATR  on  SYS:   will  contain  useful
     classes  and procedures.  ATR-files are automatically looked
     up in SYS:LIBSIM.ATR if  not  found  on  your  own  area  as
     separate   files  or  in  a  library  (default  LIBSIM.ATR).
     LINK-10  is  directed  to  look  up  the  REL-file  in   the
     corresponding place (extension ATR replaced by REL).
     See /SEARCH switch in SIMCOM.HLP.
     Old SIMULA files referring to ATR  files  on  SYS:   ([1,4])
     should  be  edited  not to contain any such reference, since
     SYS:libsim.atr will be searched in the normal case.
     Warning!  Old REL files are still valid, but old  SAV  files
     can  only  be run as long as the old runtime system segments
     SIMRT1.SHR and SIMRT2.SHR are available  on  the  SYS  area.
     SIMDD1.ABS may also be needed by such programs.
     The new runtime system segments are  called  SIMR21.SHR  and
     SIMR22.SHR.
     New facilities  have  been  added  to  SIMDDT.   It  is  now
     possible   to   display  lines  in  the  source  code  while
     debugging.
     New SIMDDT commands:   DISPLAY  and  INSPECT.   For  further
     information do .HELP SIMDDT.
     End of release 2 information.

     This help file (HLP:SIMULA.HLP) contains general information
     on  the  SIMULA system.  More specific information about the
     SIMULA  system  can  be  obtained  by  issuing  the  monitor
     commands
     HELP SIMCOM (compiler information),
     HELP SIMDDT (debugging system),
     HELP SIMRTS (object time system),
     HELP SIMDIR (utility program for separate compilation).
     SIMULA Language Handbook, parts I, II are  available.   They
     can   be   ordered  from  FOA  He1  Report  Center,  S-10450
     Stockholm, SWEDEN.

     -  The SIMULA system uses some of  the  Fortran  subroutines
        and  these are taken from the SYS:FORLIB library.  Errors
        have been discovered in the  DATAN.,  the  EXP3  and  the
        DEXP.3 routines.
        The results  from  the  functions  for  double  precision
        arctangent  and for a single precision number raised to a
        floating point power can not be trusted.
     Reported errors (see below) will  be  changed  in  the  next
     maintenance releases of the system.

     SIMULA is a general purpose language which contains Algol 60
     as  a  subset.   In  addition  to  the facilities offered by
     Algol, SIMULA is especially suited for list-processing, text
     handling   and   simulation,   through  the  class  concept,
     reference and text variables and the system  classes  SIMSET
     and  SIMULATION.   Input/output  is  efficient  and  closely
     linked to the text handling facilities.  The  class  concept
     is  unique  to SIMULA.  Through a class declaration, one can
     define a data structure and operations on the  data  as  one
     entity.   With  suitable  class  declarations, SIMULA can be
     turned into  a  special  purpose  language  for  almost  any
     application field.  SIMULA also contains a powerful facility
     for separate compilation of  classes  and  procedures.   For
     applications  where  useful  subroutines  are  available  in
     FORTRAN or in assembly code (MACRO-10), it is easy  to  call
     external  procedures  in  those languages.  DEC-10 SIMULA is
     closely compatible with IBM 360/370 and  UNIVAC  1100-series
     SIMULA.   SIMULA  programs  written for these systems can be
     run almost unchanged.  For SIMULA programs written for other
     systems,  conversion  programs are available (CDCSIM for CDC
     and UNIVAC SIMULA, IBMSIM for IBM SIMULA).

     SIMULA programs should have file name extension  SIM,  which
     is  recognized  by the COMPIL cusp and by LINK-10.  A SIMULA
     program is compiled, linked and run in the same way  as  any
     standard  language  processor,  e  g  FORTRAN,  by using the
     commands COMPILE, DEBUG, LOAD or EXECUTE.  The SIMULA system
     has a powerful debugging system, SIMDDT, which is loaded via
     the DEBUG command at program  start,  on  errors  or  via  a
     ↑C-REENTER  sequence  at any point during a program run.  No
     special statements have to be  introduced  into  the  SIMULA
     text to use SIMDDT.

     Errors  should  be  reported  in  writing  to   the   SIMULA
     maintenance  group, FOA He1, 104 50 Stockholm 80, tel 631500
     (08-631800), using the error report form shown in the SIMULA
     Language Handbook, Part II.
     The failing program and its data should  be  kept  available
     without  change  and  its  protection  code  should  make it
     possible to read from any ppn, unless it is secret.  If  the
     error  can be isolated in a smaller and simpler program, the
     smaller program should be submitted.


                          [END OF SIMULA.HLP]
                                 SQHELP
                                 ======


SQHELP is an external  procedure  to  be  used  by  SIMULA  applications
programs  to  provide  a  conversational help facility.  SQHELP reads an
ordinary sequential .HLP file  and  presents  it  to  the  user  at  the
conversational terminal.

By giving a search word as input to SQHELP, SQHELP is directed  to  list
only those lines in the .HLP file which either contain this search word,
or are close to a line containing this search word.

The search word can either be input by the user himself at the terminal,
or  it  can  be given in the applications program, e.g. to get different
help messages in different program contexts.

You declare SQHELP in your program as
EXTERNAL BOOLEAN PROCEDURE SQHELP;

Description of the parameters to SQHELP:

BOOLEAN PROCEDURE sqhelp(helpfile,selector,height,width);
VALUE helpfile, selector;
TEXT helpfile, selector; INTEGER height, width;

HELPFILE is a text containing a file specification.  If no extension  is
given,  .HLP is assumed.  First SQHELP will try to find the file in your
own area.  If not there, SQHELP will search for the file  on  the  HLP:,
DOC: and SYS: areas (in this order) on your computer.

SELECTOR is a search word.  Only lines surrounding lines containing this
search  word  will be displayed to the user.  If SELECTOR is NOTEXT, the
user will be asked to provide a search word.  If  he  does  not  provide
any, the whole help file will be displayed to him.

HEIGHT is the number of lines in each chunk of text which will be  shown
to  the  user.  If a page (segment of input file between succeeding form
feed characters) is longer than this, it will be  divided  into  smaller
chunks.   After  each  chunk,  the  user  will  be  given  the option to
discontinue typing of the help file.  If pages contain more than  HEIGHT
lines,  then  only  lines  less than HEIGHT/2 lines above or below lines
containing the search word will be displayed to the user.

With display terminals, HEIGHT should be one less  than  the  number  of
lines on the screen.

WIDTH, the line length, must be at least as long as the longest line  in
the help file, otherwise you may get an error interrupt.

Example of use (assuming that you are using SAFEIO):

     request("Enter speed",nodefault,realinput(x,TRUE),"",
     sqhelp("Racing","Speed",19,80));

This example means that if the user types ? on his terminal,
sqhelp will search for pages containing the word SPEED
in the file RACE.HLP.

The following EXTERNAL declarations are necessary in programs
using SQHELP:

     EXTERNAL TEXT PROCEDURE conc, rest, scanto, from, upcase;
     EXTERNAL REF (infile) PROCEDURE findinfile;
     EXTERNAL BOOLEAN PROCEDURE dotypeout, sqhelp;
     EXTERNAL INTEGER PROCEDURE search;

                          [END OF SQHELP.HLP]





STORE - A SIMPLE TEXT ORIENTED DATA BASE HANDLER

     By Jacob Palme, Swedish National Defense Research Institute.

ABSTRACT

     STORE is a simple data base handler written in SIMULA.
     STORE is primarily used through two procedures, PUTMESSAGE
     and GETMESSAGE.  PUTMESSAGE stores a message under a key in
     the data base, GETMESSAGE retrieves a message for a given
     key from the data base.  Both message and key can be
     variable length text strings.  Any structuring of key and
     message into fields is up to the user, not done by the STORE
     program.

     The strings are stored in a direct access file on secondary
     storage.  The system uses a combination of hashing and
     binary trees to find the place of a message in the data
     base.  Hashing to get high efficiency, binary trees to allow
     unlimited growth of the data base.

     The system is designed with the goal of being easy to use
     for a programmer and having as few restrictions as possible.

PUTTING AND GETTING MESSAGES

     You store a message into the data base by calling the
     BOOLEAN PROCEDURE PUTMESSAGE(KEY, MESSAGE);
     TEXT KEY, MESSAGE;

     KEY and MESSAGE should both be TEXT variables of arbitrary
     contents and length.  The length of KEY should however not
     be larger than 400.

     The value of PUTMESSAGE will be TRUE if the message could be
     stored in the data base, FALSE if this was not possible
     because of a too long key or because there already was a
     message in the data base under the same key.

     If you want to overwrite a previous message with the same
     key in the data base, you should set the switch REMOVE to
     TRUE.  If REMOVE is TRUE, PUTMESSAGE will overwrite previous
     messages with the same key, if REMOVE is FALSE, PUTMESSAGE
     will not overwrite previous messages and will return FALSE
     if a message with the same key was already in the data base.

     To get a message back from the data base, you use the
     TEXT PROCEDURE GETMESSAGE(KEY); TEXT KEY;

STORE - A SIMPLE TEXT ORIENTED DATA BASE HANDLER         PAGE   2



     This procedure will look for a message stored under the
     given key in the data base.  If no such message can be
     found, the value NOTEXT is returned.

CONVERTING KEYS TO UPPER CASE

     If you want a key to refer to the same message regardless of
     upper or lower case characters in the key, then you should
     apply the TEXT PROCEDURE UPCASE(KEY); TEXT(KEY); to the key.
     This procedure changes all lower case characters in the key
     to upper case.  So if you put a message under a key "GooD"
     you can later get the same message through the key "GOOD" or
     "good".

PRODUCING A DIRECTORY OF A FILE

     The STORE package has a built-in procedure for producing a
     directory of a file, that is for listing all the keys in the
     file.

     The procedure is 
     PROCEDURE DIRECT(KEYPROCESSOR); PROCEDURE KEYPROCESSOR;

     Where KEYPROCESSOR is a procedure supplied by you with two
     parameters KEY and LOCATION.  Example:

     PROCEDURE KEYPROCESSOR(KEY,LOCATION);
     TEXT KEY; INTEGER LOCATION;
     BEGIN OUTTEXT(KEY); OUTINT(LOCATION,5); OUTIMAGE;
     END;

     The procedure KEYPROCESSOR will be called once for each KEY
     in the data base.  LOCATION is the number of the block in
     the file where the MESSAGE for that KEY ends.

PUTTING STORE INTO YOUR APPLICATION PROGRAM

     In the outermost block of your main program write:
     EXTERNAL CLASS STORE;
     Also put the same statement in front of any separately
     compiled modules which are to be able to use the facilities
     of STORE.

     Where you need a STORE in your data base you write the
     statements:
     REF(STORE) MYSTORE;
     MYSTORE:- NEW STORE(VIRTUALSIZE, INITIALSTORESIZE);

     VIRTUALSIZE is the size of the storage area in which lines
     from the data base are kept in core.  A large virtualsize

STORE - A SIMPLE TEXT ORIENTED DATA BASE HANDLER         PAGE   3



     will thus reduce the number of disk reads but increase core
     usage.  For most applications, VIRTUALSIZE=0 is best.
     However, if you call GETMESSAGE to do long searches in the
     data base, a higher value may be good.  Try for yourself.

     INITIALSTORESIZE is the size of the area on disk into which
     the key is initially hashed.  If this area is full, further
     messages are stored in binary trees.  A large
     INITIALSTORESIZE will thus give a larger disk file in the
     beginning, but will reduce disk accesses and CPU-time.  In a
     test case, CPU time had increased 20% and disk accesses 30%
     when the actual store was allowed to grow to four times the
     INITIALSTORESIZE, as compared with starting from the
     beginning with a four times larger INITIALSTORESIZE.

     A simple rule is to choose INITIALSTORESIZE as about half
     the total size into which you expect your data base to grow.

     Once a data base has been started, the INITIALSTORESIZE
     cannot be changed.  A new value of INITIALSTORESIZE is
     ignored by the STORE program for old data bases.

     Both VIRTUALSIZE and INITIALSTORESIZE are measured in disk
     blocks, that is 128 36-bit words or 640 ASCII-7-bit
     characters.

     Before you can use the data base, you must call the
     procedure
     MYSTORE.OPEN(FILENAME);
     where FILENAME is a text of 1-6 letters or digits.  No
     extension, STORE will add the extension ".DAF".  If FILENAME
     is read in from a conversational terminal, you should first
     check it with the
     BOOLEAN PROCEDURE SIXLETTERSORDIGITS(FILENAME);
     TEXT FILENAME;
     which will return TRUE only if the FILENAME is really 1-6
     letters or digits.

     Before stopping the execution of your program, you must call
     the procedure CLOSE.  If you leave your program by CTRL-C or
     by a system crash, you may lose information newly stored
     into the data base.  You can ensure against this by calling
     CLOSE before each interaction with the terminal user and
     calling OPEN again when you need to use STORE.  But this
     will double the CPU time and cost of your run in cases where
     you only make one single call to PUTMESSAGE or GETMESSAGE
     between each OPEN and CLOSE.

RESTRICTIONS

STORE - A SIMPLE TEXT ORIENTED DATA BASE HANDLER         PAGE   4



     The length of the KEY must not exceed 400.  The total size
     of one data base should not be larger than 9999 disk blocks.
     There is no program yet available to reorganize a data base.
     Reorganisation will however in many applications never be
     needed, since the program automatically frees storage when
     messages are removed.

     The parameter texts key and message may contain any ASCII
     characters except the following:
     OCTAL        DECIMAL DESCRIPTION
     000           0 Null
     012          10 Line Feed
     013          11 Vertical Tab
     014          12 Form Feed
     015          13 Carriage Return
     033          27 Altmode

     The program does not check against these characters, and
     their occurence may render further entries into the data
     base unreadable.

     If, however, you need to use these characters in key and/or
     message, you can apply the transfer functions PUTSAFE and
     GETSAFE.  These functions transfer a given string into an
     encoded string without the forbidden characters, and returns
     the string back into pre-encoded form again.  Thus, instead
     of

     PUTMESSAGE(key,message)
     GETMESSAGE(key)

     you could write

     PUTMESSAGE(PUTSAFE(key),PUTSAFE(message))
     GETSAFE(GETMESSAGE(PUTSAFE(key)))

     Do this if there is any risk that the strings may contain
     the forbidden characters(e.g.  if the strings are read in
     from a user terminal).

     If however the input strings are taken directly from
     sysin.image.strip or read using safeio.txtinput, then the
     forbidden characters will only occur as last characters in
     the key and message and can thus faster be checked against
     by writing "if key.length = 0 then true else
     key.sub(key.length,1).getchar < ' '".  This condition will
     be true if the input line ended with such a forbidden
     character and is in this special case safeguard enough.

STORE - A SIMPLE TEXT ORIENTED DATA BASE HANDLER         PAGE   5



EXAMPLE OF USE

     This very simple example only illustrates how to use the
     procedures in the package in the simplest case:

     BEGIN
        EXTERNAL CLASS STORE;
        REF (STORE) MYSTORE;
        TEXT KEY, MESSAGE;

        PROCEDURE KEYPROCESSOR(KEY, LOCATION);
        TEXT KEY; INTEGER LOCATION;
        BEGIN OUTTEXT(KEY); OUTIMAGE;
        END;

        MYSTORE:- NEW STORE(0,8); MYSTORE.OPEN("TEST");
        KEY:- COPY("KEYTEXT"); MESSAGE:- COPY("MESSAGETEXT");
        MYSTORE.PUTMESSAGE(KEY,MESSAGE);
        OUTTEXT(MYSTORE.GETMESSAGE(KEY)); OUTIMAGE; COMMENT WILL
         PRINT "MESSAGETEXT";
        MYSTORE.DIRECT(KEYPROCESSOR); COMMENT WILL PRINT
         "KEYTEXT";
        MYSTORE.REMOVE:= TRUE; COMMENT TO ALLOW CHANGING MESSAGES
         FOR THE SAME KEY;
        MESSAGE:= "NEWMESSAGE";
        MYSTORE.PUTMESSAGE(KEY,MESSAGE); COMMENT THE NEW MESSAGE
         REPLACES THE OLD;
        MYSTORE.CLOSE;
     END;

FILES DELIVERED

     The delivery of the STORE system consists of the following
     files:
     STORE.SIM    Source program of the CLASS store
     STOREU.SIM   Source program of a demonstration example using
      store
     STOREU.SAV   Executable core image of demonstration example
     STORE.RNO    The text you are reading now in RUNOFF format
     STORE.HLP   The text you are reading now in reading format

     The demonstration program STOREU also uses the SAFEIO
     package for terminal interaction.

     At the QZ data center in Stockholm, you will find the files
     on the DEC-tape H39I04.

INTERNAL STRUCTURE OF THE DIRECT ACCESS FILE

STORE - A SIMPLE TEXT ORIENTED DATA BASE HANDLER         PAGE   6



     The following sections are not necessary to use the STORE
     package, only if you want to know how it works internally or
     if you need to modify the program.

     The data base consists of disk blocks.  Each disk block is
     128 words or 640 characters.  The last two of these
     characters are always <CR><LF> to mark the end of the disk
     block.

     The messages are stored in the data base in STORE UNITS.
     Each STORE UNIT consists of
     5 characters = s = length of store unit as a decimal number
     3 characters = k = length of key as a decimal unit
     k characters = text of key
     s-k-8 characters = text of message

     The disk block for a STORE UNIT is chosen in the following
     way:
   > Compute a hash number from the text in the KEY.  See program
     for hashing algoritm.
   > The number of the first disk block to look at is computed as
     (((hash number) modulo INITIALSTORESIZE)+1).  At the same
     time the hash number is divided by INITIALSTORESIZE and the
     remainder kept.
   > If that disk block is too full(while putting) or does not
     contain the message(while getting) then the next disk block
     is taken from a binary tree started at the first disk block.
     The first four characters of each disk block contains a
     pointer to the left continuation of the tree, and the next
     four characters a pointer to the right continuation.  Both
     as decimal integers.  Left is chosen if the remainder of the
     hash number is even, right if the remainder is odd.  After
     this, the remainder is again divided by 2 and the remainder
     of this kept for going further down the tree.

     When the total length of a STORE UNIT is larger than the
     storage part of a disk block(630 characters) then the first
     part of the STORE UNIT is put into one disk block, the
     continuation into later disk blocks.  Each succesive STORE
     UNIT has as its length the remainder of the total STORE
     UNIT.  For example, for a message which has a total STORE
     UNIT of 1500 characters and the key "KEYVALUE", the first
     disk block will contain
     " 1500 8KEYVALUE...  first 614 characters of message..."
     and the second disk block will contain
     " 886 8KEYVALUE...  the next 614 characters of message..."
     and the third and last disk block will contain
     " 272 8KEYVALUE...  the last 256 characters of message..."

STORE - A SIMPLE TEXT ORIENTED DATA BASE HANDLER         PAGE   7



     Further information about the internal organisation of the
     program is given by comments in the text of the program
     itself.
VISTA - FOR FULL CONTROL OF TEXT DISPLAY TERMINALS

VISTA is a program package for controlling the input and  output  to  an
alphanumeric  display terminal from a SIMULA program on the DECsystem-10
computer.  VISTA allows full program control over the  contents  of  the
display  screen.  The package can for example be used to produce "moving
pictures" on part or whole of  the  display  screen,  or  to  allow  the
terminal user to move around the screen inputting data in various screen
fields.  A special subpackage FORM allows data input by letting the user
fill in fields in a "form" displayed on the screen.  Full validity check
is done immediately for each field input from the user.

move←the←cursor←to(horiz, vertic);
home←the←cursor;                    outchar(setchar);
set←char←on←screen(setchar,horiz,vertic);
synchronize(horiz, vertic);
outtext(t);                         outfix(a,i,j);
outreal(a,i,j);                     outint(i,j);
outimage;                           blank←line(vertic);
blank←the←screen;                   restore←the←whole←screen;
restore←one←char(horiz, vertic);
cause←real←time←delay(number←of←fillers);
cancel←display;                     resume←display;
echon;                              echoff;
CHARACTER PROCEDURE insingle(echo);
inimage;                            INTEGER PROCEDURE inint;
REAL PROCEDURE inreal;              TEXT PROCEDURE inword;
BOOLEAN PROCEDURE inyes;
CHARACTER PROCEDURE get←char←from←screen(horiz, vertic);

.run CAT[106,346]                   .run SHIP[106,346]
.run FORMT[106,346]                 .run TABLE[106,346]

Files: VISTA.SIM, FORM.SIM, VISTA.RNM, VISTA.RNH,
CAT.SIM, SHIP.SIM, FORMT.SIM, TABLE.SIM.
On DEC-tape H40I48. VISTA.REL, VISTA.ATR, FORM.REL, FORM.ATR
in LIBSIM on [106,346].

VISTA.MAN[106,346] contains a manual.