TOPS-20 User's Guide

Chapter 8 Running system programs and other users' programs

This chapter describes:

  1. Running system programs
  2. Giving commands to system programs
  3. Getting information about system features
  4. Running user programs
  5. Controlling programs
  6. Running programs without destroying memory
  7. Running multiple programs

top

8.1 Running system programs

The TOPS-20 system has many system programs. To get a complete list of the programs available, contact your system manager. The HELP ? command prints a list of the programs explained by the HELP program.

In general, a system program produces an output file by performing some operation on an input file. Some programs perform different functions, depending on the file type of the input file; however, unless you specifically request it, the program does not destroy your input file. You can give a particular name to your output file or let it take a default name. The program creates default names by keeping the name of the input file and changing the file type. For instance, the default output name used by the RUNOFF program is the input filename with the file type .MEM.

To run any of the system programs provided with TOPS-20, type the name of the program, and press RETURN. The following example shows how to start the DUMPER program:

        @DUMPER                  !Type DUMPER and press RETURN.
        DUMPER>                  !DUMPER starts
                                 !And waits for a command

top

8.2 Giving commands to system programs

Once the system program responds with its prompt, you can give the program a command. There are two types of prompts from the system program.

Some programs respond by printing an asterisk on the terminal. You can then type a command in the following format:

        desination-filespec = source-filespec

        destination file  specification  =  source  file specification(s)
        /switch(es)

You cannot use recognition on file specifications or switches when you run any of the programs listed in Table 4-2, Special System Programs.

Other system programs respond by printing a prompt that identifies the program, such as the prompt for the DUMPER program.

        @DUMPER
        DUMPER>

You can use recognition on commands and arguments to these programs.

top

8.2.1 Example: Using a System Program

The FILCOM (for FILe COMparison) program which compares two files and indicates the differences between them, works as follows:

  1. Create two files that are similar but not identical. You may create two files of your own or use the files created in the following example:
                @CREATE (FILE) FIRST.FIL
                Input:  FIRST.FIL.1
                00100           TYPE 101
                00200   101     FORMAT ('THIS PROGRAM WAS WRITTEN FIRST.')
                00300           TYPE 102
                00400   102     FORMAT ('BUT THE TWO PROGRAMS ARE SIMILAR.')
                00500           END
                ^E
    
                [FIRST.FIL.1]
                @
    
                @CREATE (FILE) SECOND.FIL
                Input:  SECOND.FIL.1
                00100           TYPE 101
                00200   101     FORMAT ('THIS PROGRAM WAS WRITTEN SECOND.')
                00300           TYPE 102
                00400   102     FORMAT ('BUT THE TWO PROGRAMS ARE SIMILAR.')
                00500           END
                *E
    
                [SECOND.FIL.1]
                @
    
  2. Start the FILCOM program by typing FILCOM and pressing the RETURN key. When FILCOM is ready, it prints an asterisk on your terminal:
                     @FILCOM
    
                     *
    

    Tell FILCOM which files to compare and what to do with the results of the comparison. For this example, type the line: *TTY:=FIRST.FIL,SECOND.FIL

    This line tells FILCOM to compare the two files and print the results on your terminal (TTY stands for terminal.) If, instead, you want to store the results in the file PROG.DIF, type the line:

                     *PROG.DIF=FIRST.FIL,SECOND.FIL
    

    4. Press RETURN at the end of the line to execute the command

                *TTY:=FIRST.FIL,SECOND.FIL
                File 1) DSK:FIRST.FIL[4,16]     created: 0837 10-Jun-1988
                File 2) DSK:SECOND.FIL[4,16]    created: 0839 10-Jun-1988
    
                1)1   00200   101 FORMAT ('THIS PROGRAM WAS WRITTEN FIRST.')
                1)    00300    TYPE 102
                ****
                2)1   00200   101 FORMAT ('THIS PROGRAM WAS WRITTEN SECOND.')
                2)    00300    TYPE 102
                **************
    
                %files are different
    
                *
    

In the comparison, lines preceded by a 1) are from the first file, FIRST.FIL. Lines preceded by a 2) are from the second file, SECOND.FIL. FILCOM puts an extra number beside the lines that differ, and then prints the line. After each of the differing lines, FILCOM prints the next line (for example, TYPE 102), so that you can easily find your place in the files.

After the first comparison, FILCOM prints another asterisk to show that it is ready to do more work. This time, let FILCOM compare the files but print only the second file. If there are any differences between the second file and the first, request FILCOM to put a vertical bar in the left column beside any such line. The switch /U does this.

        *TTY:=FIRST.FIL,SECOND.FIL/U

            00100         TYPE 101
        :   00200 101     FORMAT ('THIS PROGRAM WAS WRITTEN SECOND')
            00300         TYPE 102
            00400 102     FORMAT ('BUT THE TWO PROGRAMS ARE SIMILAR.')
            00500         END

        %files are different

        *

Now, to exit FILCOM, type a CTRL/C. The system prints the @.

        *^C
        @

You can run many system programs in this manner. Some programs behave differently. For help, type HELP and the program name. If you cannot obtain any information, contact your system manager.

top

8.3 Getting information about system features

The HELP program gives you useful information about the commands for various programs of the TOPS-20 system. The simplest way to run the HELP program is to type HELP and press the RETURN key. TOPS-20 then responds with the general instructions for obtaining information.

        @HELP

        HELP Command ====
        The HELP command prints helpful documentation on  various  system
        features, The command

         @HELP
        will print this message on your terminal.

         @HELP NAME
        will look for, and print out information about the system feature
        names in "NAME".  For example,

         @HELP EDIT
        will print out information about the EDIT program.

         @HELP ?
        will give a list of features for  which  HELP  is  available  and
        retype to wait for any additional input.

        [End of HELP.HLP]
        @

To get information about a system feature, type HELP, followed by a space and a question mark. The system prints a list of features for which it has information.

        @HELP ? one of the following:
         68274     8700       ACCT20  ACL     ACTGEN  ADJPSX  ALGDDT
         ALGOL     APL        APLSF   ASTROL  BLAST   BLIS10  BLIS11
         BLISS     BLSCRF     BOX     CALC    CALMNT  CALN    CBL74
         CHANGE    CHECKD     CHESS   CHKPNT  CMPTXT  CMS     CN
         CNVDSK    COBDDT     COBOL   CONGEN  CONTEN  CONTNT  CONV20
            .
            .
            .
         SNOBOL    SORT       SOUP    STEP    SYSERR  SYSJOB  TAR
         TCX       TERMINAL   TGHA    TMSTAP  TOC     TRAK20  TRANSF
         TRANSL    TTYINI     TUTIO   TV      TYPVF7  ULIST   UNITS
         US        USAG20     USAH20  VAXTAP  VTECO   WATCH   WATCH-NEW
         XEROX     XOUT
          or confirm with carriage return

To get help on a specific feature, type HELP and the name of a system program as an argument. TOPS-20 then responds with the information available about that program.

        @HELP FILCOM
        FILCOM V21B(60)

        FILCOM compares two files in either ASCII mode
        or binary depending upon switches or file name extensions.
        All standard binary extensions are recognized as binary by
        default.
        Switches are :-
        /A  compare in ASCII mode
        /B  allow compare of Blank lines
        /C  ignore Comments and spacing
        /E  file is in .EXE format
        /S  ignore Spacing
        /H  type this Help text
        /#L Lower limit for partial compare
                 or number of Lines to be matched
                 ( # represents an octal number)
        /#U Upper limit for partial compare
        /Q  quick compare only, give error message if files differ
        /U  compare in ASCII Update mode
        /W  compare in Word mode but don't expand files
        /X  expand files before word mode compare

        @

Note that many programs also have a HELP command. /H is the help command for programs that have an * prompt, while HELP is the command for programs using the program name and > prompt; for example, DUMPER.

top

8.4 Running user programs

To run your own executable program in your connected directory, give the RUN command. In the following example, run the program LESTSQ:

        @RUN (PROGRAM) LESTSQ

Files with the file type .EXE contain executable programs. An executable program is a program that has already been compiled, loaded, and saved. (Refer to Section 9.1.)

To run another user's program, give the file specification with the RUN command:

        @RUN (PROGRAM) <HOLLAND>TEST

You must have read and/or execute access to the file and access to the directory.

top

8.5 Controlling programs

You can control programs by using three control characters: CTRL/C, CTRL/O and CTRL/T. CTRL/C halts the execution of a program; CTRL/O controls output to your terminal; CTRL/T checks the status of a running program.

top

8.5.1 Typing CTRL/C to Halt Execution

You may want to stop your program for several reasons.

To stop an executing program or command, type two CTRL/Cs. Only one CTRL/C echoes on the terminal. The program (or command) stops and returns you to command level. In the following example, you decide to stop your program.

        @EXECUTE (FROM) SQRT.ALG
        ALGOL:  SQRT
        LINK:  Loading

            ALGOL  Running at 701105 Used 0:00:04.5 in 0:01:49
        ^C
        @

You can now give any command that does not change the contents of memory; for example, the TERMINAL command. (You can give commands that change memory if you have "kept" forks in memory. Refer to Section 8.7 Running Multiple Programs). When you are finished, give the CONTINUE command and the program resumes where it left off. (The CONTINUE command will not continue a TOPS-20 command that you interrupted.)

Some programs (such as APL, BASIC, and EDIT) intercept the CTRL/C and do not return you to TOPS-20 command level. In these special cases, refer to the description of the particular program to return to TOPS-20 command level.

The system does not respond immediately to a single CTRL/C, but waits for the time when you would normally give input to the program. However, the system processes two CTRL/Cs immediately.

top

8.5.2 Typing CTRL/O to Stop Output to Your Terminal

To stop terminal output but not execution, type CTRL/O. The system prints:

        ^O...
and stops all output to the terminal. The program (or command) still executes, but no output appears on the terminal. When the program (or command) finishes, the system prints the TOPS-20 prompt.
        @DIRECTORY (OF FILES) *.FOR

           PS:<MILLER>
         ARDVRK.FOR.1
         BASTST.FOR.3
         ^O...

If you stop output on the terminal and want to resume printing later during the execution of the same program or command, type another CTRL/O.

        @DIRECTORY (OF FILES) *.CBL

           PS:<MILLER>
         ANDTST.CBL.6
         BEHIND.CBL.2
         DEVCHR.CBL.4
         ^O...
         WOBBLE.CBL.3
         XTMP.CBL.9
         Total of 34 files

Each successive pair of CTRL/Os stops and resumes terminal output.

The effect of CTRL/O is cancelled when the program requests terminal input.

top

8.5.3 Typing CTRL/T to Print the Run Status

You can check the progress of your program even while it is running. To do this, type CTRL/T.

The response from CTRL/T shows:

  1. The current time
  2. The status of your program
  3. The amount of computer time used
  4. The time elapsed since you logged in

In the example below, you type a CTRL/T immediately after the computer prints ALGOL:SQRT. At that time, the program is executing the instruction stored in memory location 540016. Up to this point, you have used 15.9 seconds of computer time while being logged in for 17 minutes and 2 seconds.

        @EXECUTE (FROM) SQRT.ALG
        ALGOL:  SQRT<CTRL/T>
        09:36:35 SQRT Running at 540016  Used 00:00:15.9  in 0:17:02,
        Load  2.08
        LINK:  Loading
        [LNKXCT SQRT Execution]

         TYPE THE VALUE OF X:  4

         THE SQUAREROOT OF     4.000  IS     2.000

        End of execution.
        @

Depending on when you press CTRL/T, other possible responses are:

IO WAIT AT location
This means that your program is probably waiting for you to type something.
HALT AT location
This means that your program has finished.

The symbol "location" is a 6-digit octal number that tells you which instruction in computer memory is currently being executed.

Typing a CTRL/T does not interfere with the running of your program in any way. However, if your program is printing information on your terminal at the same time that you type a CTRL/T, the response from CTRL/T is mixed with the information from your program.

The information is in the form:

        time name status Used CPU-time in logged-in-time, Load average

The status message tells you the status of the program. Table 8-1 lists some of the common status messages.

   Table 8-1:  CTRL/T Status Messages


   _______________________________________________________________________

     Message             Means the Process is:
   _______________________________________________________________________

     RUNNING AT pc       Running
     IO WAIT AT pc       Doing input or output
     HALT AT pc          Stopped
     FORK WAIT AT pc     Waiting for a process to terminate
     SLEEP AT pc         Temporarily suspended

     pc is  the  memory  location  of  the  current  instruction  being
     executed.  You can cause this location to be displayed as either a
     symbol or an octal address by using the SET TYPEOUT MODE  command.
     Refer  to the TOPS-20 Commands Reference Manual for information on
     SET TYPEOUT MODE.
   ________________________________________________________________________

The load average gives a rough indication of current system use, and thus helps you estimate the length of time your program will take to run. Higher load averages tend to indicate heavy use and slow system response. Refer to the TOPS-20 WATCH document for further information on load averages.

If you stop the program by typing a CTRL/C, the system may precede any of the messages in Table 8-1 with ^C FROM. If a process terminates unexpectedly, the CTRL/T message prints in the form:

        HALT:  reason
where reason can be one of the messages listed in Table 8-2.
   Table 8-2:  Unexpected Process Termination Messages


   __________________________________________________________________

        CHANNEL n INTERRUPT AT pc
                  There is a software interrupt on  channel  n  when
                  executing the instruction located at pc.

        OVERFLOW AT pc
                  There is an integer overflow  when  executing  the
                  instruction at location pc.


        FLOATING OVERFLOW AT pc
                  There is a floating point overflow when performing
                  a floating point operation at location pc.

        PUSHDOWN OVERFLOW AT pc
                  There is  an  overflow  during  a  pushdown  stack
                  operation at location pc.

        END-OF-FILE AT pc
                  There is  an  unexpected  end-of-file  encountered
                  while executing the instruction at location pc.

        IO DATA ERROR AT pc
                  There is  an  input  or  output  data  error  when
                  executing the instruction at location pc.

        FILE ERROR 3 INTERRUPT AT pc
        FILE ERROR 4 INTERRUPT AT pc
                  There  is  a  file  error  while   executing   the
                  instruction at location pc.

        ILLEGAL MEMORY READ AT pc
        ILLEGAL MEMORY WRITE AT pc
        ILLEGAL EXECUTE AT pc
                  There is an illegal attempt to  access  memory  at
                  location pc.

        FORK TERMINATION INTERRUPT AT pc
                  There is  a  software  interrupt  that  terminated
                  another   fork   (process)   while  executing  the
                  instruction at location pc.

        FILE OR SWAPPING SPACE EXCEEDED AT pc
                  There is no more room in the system memory or disk
                  storage   while   executing   the  instruction  at
                  location pc.
   _______________________________________________________________________

top

8.6 Running programs without destroying memory

If you are executing a long-running program and find a file missing, you can stop the program without destroying the contents of memory, run another program (such as an editor) to create the missing file, and return to continue your original program. Before running another program to create the file, type two CTRL/Cs to halt the program and then give a PUSH command. The PUSH command creates a new, inferior TOPS-20 command level and a fresh copy of memory. You can now run a program without affecting the program in the superior TOPS-20 command level. When you finish, give the POP command to return to the previous memory and command level. Finally, give the CONTINUE command to resume the execution of your program.

NOTE

If you run another program without giving the PUSH command, the new program will replace the old program in memory, and you will not be able to continue the old program.

The following example illustrates how to run a FORTRAN program. As it nears completion, the program requires a file you forgot to create. Stop the program; give the PUSH command; create the file; give the POP command; and continue the program.

        @EXECUTE (FROM) RANK.FOR      !Execute the program
        FORTRAN: RANK
        LINK:   Loading
        [LNKXCT RANK Execution]

        %FRSOPN File was not found    !The file was not found
        Unit=1 DSK:NUMBER.DAT/ACCESS=SEQIN/MODE:ASCII

        Enter new file specs. End with $(ALT)
        *^C                           !type CTRL/C to stop
        @PUSH (COMMAND LEVEL)         !Save the program and set up
                                       a new copy of memory
         TOPS-20 Command processor 6.1(7)
        @CREATE (FILE) NUMBER.DAT
             .
             .
             .
        @POP (COMMAND LEVEL)          !Return to the last command level
        @CONTINUE                     !Resume execution
        NUMBER.DAT                    !Type the name of the file
        STOP                          !The program finishes

        END OF EXECUTION
        CPU TIME: 0.38  ELAPSED TIME: 3.87:49
        EXIT

When you need to run a program and do not want to destroy the current contents of memory, give the PUSH command, run the appropriate program, give the POP command and continue the first program. The POP command returns you to the preceding level. You can give as many pairs of the PUSH and POP commands as you need. If the system temporarily does not have enough resources to give you a new level of TOPS-20, it cancels the PUSH command and prints the message:

        ?Insufficient resources available

Reissue the command, and if you still get errors, you may have given too many PUSH commands without any intervening POP commands. Give a POP command. If the system cannot execute a POP command, it cancels the command and prints the message:

        ?No higher command level

When you give a PUSH command, the contents of memory are preserved in their exact state and cannot be changed until you give a POP command to return to that level.

top

8.7 Running multiple programs

In addition to the PUSH and POP commands, TOPS-20 provides another method of running multiple programs without destroying memory. This feature, called "Multiforking," allows you to have multiple programs at the same TOPS-20 command level (EXEC). Each program resides in its own address space. This space is called a "fork" or a "process." Multiforking allows you to go from an editing program to a compiler and back again without reloading either program. Furthermore, you can run multiple programs and leave your terminal free for other work.

Figure 8-1 illustrates the structure of multiple forks created with the PUSH command. Note that the forks are organized in a hierarchy. Each PUSH command creates an inferior EXEC. To address a higher fork, you must POP back up the hierarchy. Each time you POP, you erase the inferior EXEC and its forks.

     1.Using PUSH and POP

                      --------------------
                      |       EXEC       |
                      |                  |
                      --------------------
                      |       EDT        |
                      --------------------
                               |
                               | @PUSH
                               v
                      --------------------
                      |       EXEC       |
                      |                  |
                      --------------------
                      |       BLISS      |
                      --------------------
                               |
                               | @PUSH
                               v
                      --------------------
    ---TTY----        |       EXEC       |
    |        |--------|                  | @INFORMATION FORK-STATUS
    |        |        --------------------  =>LINK(3):
    ----------        |       LINK       |  ^C from Running at 700304,
                      --------------------  0:00:02.8


     2.Using Multiforking

                      --------------------
    ---TTY----        |       EXEC       | @INFORMATION FORK-STATUS
    |        |--------|                  |    EDT(1):Kept,HALT at 460015,
    |        |        --------------------    0:00:01.7
    ----------        | EDT | BLISS| LINK|    BLISS(2):Kept,Background,
                      --------------------    IO wait at 404426,0:00:02.1
                                           => LINK(3):^C from Running
                                              at 700304, 0:00:00.8


   Figure 8-1:  Methods of Running Multiple Programs

Now look at the structure of multiple forks created with multiforking in Figure 8-1. Note that there is only one EXEC command level, and the forks are organized parallel to each other. Because of this structure, any fork can be addressed without erasing any existing forks. Since all the forks belong to the same EXEC, the INFORMATION FORK-STATUS command displays the status of all forks. With the PUSH and POP method, you can only see the status of the "current" fork. The current fork is the fork that TOPS-20 commands refer to when you do not give a fork name as a command argument. In the fork status display, an arrow (=>) points to the current fork.

You can control forks with the multiforking-class commands discussed in the following sections.

top

8.7.1 Saving Forks

Normally, any time you load a program, the new program takes the place of or "resets" the program in the current fork. You can preserve the contents of a fork with the KEEP command. The KEEP command gives a fork a "kept" status. A kept fork is not cleared from memory when you run another program. Instead, a new fork is created for the new program.

In the following example, you have the EDIT program loaded, and you need to run the BLISS program while preserving the state of EDIT. First, display the fork status with the INFORMATION FORK-STATUS command. Then, make the EDIT fork a kept fork to protect it from being reset by BLISS. Next, redisplay the fork status:

        @INFORMATION FORK-STATUS
         => EDIT (1): HALT at 6254, 0:00:22.8
        @KEEP (FORK)
        @INFORMATION FORK-STATUS
         => EDIT (1): Kept, HALT at 6254, 0:00:22.8

Now, load the BLISS program and exit BLISS to check the fork status:

        @BLISS
        BLISS>/EXIT
        @INFORMATION FORK-STATUS
            EDIT (1): Kept, HALT at 6254, 0:00:22.8
         => BLISS (2): HALT at 6065, 0:00:00.2
Note that the arrow indicates that BLISS is now the current fork.

Forks are named after the program they contain and numbered in the order they were created. In the multiforking class commands, the fork name and number are interchangeable.

You can execute a program in a kept fork by typing only the fork name or enough letters of the fork name to distinguish it from any other fork name or TOPS-20 command. For information on automatically KEEPing forks, see the SET PROGRAM command in the TOPS-20 Commands Reference Manual.

top

8.7.2 Changing the Current Fork

Multiforking-class commands always refer to the current fork unless you specify a fork name as a command argument. Other EXEC commands always refer to the current fork and do not accept a fork name argument. The FORK command changes the current fork so that the EXEC commands refer to a new current fork. Use the FORK command before any EXEC command that only refers to the current fork, such as EXAMINE, DEPOSIT, and INFORMATION MEMORY-USAGE.

In the next example, you need to know how many pages are being used by the EDIT program. Since the command INFORMATION MEMORY-USAGE provides memory information about the current fork, which is now BLISS, you must first make EDIT the current fork. Give the command FORK EDIT, and check the fork status to note that EDIT is the new current fork. Then give the INFORMATION MEMORY-USAGE command.

        @FORK (IS) EDIT 
        @INFORMATION FORK-STATUS
         => EDIT (1): Kept, ^C from IO wait at 2476, 0:00:00.5
            BLISS (2): HALT at 3744, 0:00:00.9
        @INFORMATION MEMORY-USAGE

top

8.7.3 Creating Background Forks

A fork that is running while your terminal is at EXEC command level or at another program command level is called a "background" fork. To place the BLISS program in a background fork, type the command CONTINUE BLISS to make BLISS the current fork, and enter BLISS command level. (Note that if BLISS was a kept fork, typing only BLISS would invoke the BLISS fork.)

At the BLISS> prompt, enter a filename to start the BLISS program. Then, type two CTRL/Cs (the first CTRL/C does not appear on your terminal) to halt BLISS and bring you back to EXEC command level. Check the status of BLISS with the INFORMATION FORK-STATUS command.

        @CONTINUE BLISS
        BLISS>PROBE.BLI
        ;File: PUBLIC:<DBONIN.FORK>PROBE.BLI.3
        ^C
        @INFORMATION FORK-STATUS
            EDIT (1): Kept, HALT at 6254, 0:00:22.8
         => BLISS (2): ^C from Running at 155471, 0:00:54.2

Now, continue BLISS with the CONTINUE command and the /BACKGROUND switch. The /BACKGROUND switch places the program in the background and lets you stay at EXEC command level.

        @CONTINUE /BACKGROUND
        @INFORMATION FORK-STATUS
            EDIT (1): Kept, HALT at 6254, 0:00:22.8
         => BLISS (2): Background, Running at 6065, 0:00:54.2

With BLISS running in a background fork, your terminal is now free for other work. You can give other EXEC commands, run EDIT or a new program. A new program does not clear the unkept BLISS fork while BLISS is in the background. The system notifies you when BLISS wants input by ringing the terminal bell and printing the message [BLISS: wants the TTY].

Because EDIT is in a kept fork, you can continue EDIT at its start address by typing EDIT.

        @EDIT
        [Starting]
        Edit: CHECK.TXT
        *

The [Starting] message indicates that the kept fork was continued at its start address. You can set kept forks to continue at their continue, reenter, or start address with the command, SET PROGRAM. (For more information on the SET PROGRAM command, see the TOPS-20 Commands Reference Manual).

top

8.7.4 Deleting Forks

Forks are valuable system resources. The maximum number available on any system is usually 512. When all the system's forks are in use, new users cannot log in and the system displays the message ?Full No more forks. Also, when users already on the system attempt to create new forks the system displays the message ?Insufficient system resources.

Therefore, you should always return your idle forks to the system. The RESET command clears forks from memory and makes them available to other users.

        @INFORMATION FORK-STATUS
         => EDIT (1): Kept, HALT at 6254, 0:00:22.8
            BLISS (2): Background, Running at 6065, 0:02:54.2
        @RESET EDIT
        @INFORMATION FORK-STATUS
            BLISS (2): Background, Running at 6065, 0:02:54.2

Your system manager can restrict the number of forks allowed to each job. Attempting to exceed this limit also results in the message ?Insufficient system resources.

top