About Procedures

Any set of valid commands may be placed in a file---called a `procedure'---and executed as though they were being entered from the keyboard. (There is one important difference. When a command is being read from a procedure, a blank line in the middle of a command does not cancel the command.)

The procedure is executed with the START command,

   START THIS.PER;

The procedure stack

Procedures can execute other procedures. Each new START command suspends the current procedure (placing it on a push-down stack) and begins executing commands from the new procedure. As many as seven procedures can be suspended at any one time.

When the final command in a procedure has been executed, the procedure on the top of the stack is re-activated and the first unread command from that procedure is executed.

When no procedures are on the stack, the program reads commands from the keyboard.

An example should make this clearer. Let FILEA, FILEB, and FILEC be the following procedures. Let A1, B1, and so on, be generic commands.

   (FILEA)        (FILEB)         (FILEC)
    A1;            B1;             C1;
    A2;            START FILEC;    C2;
    A3;            B2;             C3;
    START FILEB;   B3;
    A4;            B4;
    A5;

   START FILEA;

   A1;
   A2;
   A3;
    B1;
     C1;
     C2;
     C3;
    B2;
    B3;
    B4;
   A4;
   A5;

EXIT and STOP

The EXIT and STOP commands may be used to alter the flow of procedures. The EXIT command, when read from a procedure, stops the reading of the current procedure, and pops the previous procedure off the file stack. If no procedures remain on the stack, the prompt reappears, and Percy waits for the next command to be entered from the keyboard.

The STOP command clears the procedure stack immediately.

An example should make this clearer. Let procedures FILEA, FILEB, and FILEC contain the following commands.

   (FILEA)        (FILEB)         (FILEC)
    A1;            B1;             C1;
    A2;            START FILEC;    C2;
    A3;            B2;             EXIT;
    START FILEB;   B3;             C3;
    A4;            STOP;
    A5;            B4;

   START FILEA;

   A1;
   A2;
   A3;
    B1;
     C1;
     C2;
    B2;
    B3;

Batch procedures

When executing a program, if you may start a procedure by specifying it on the command line,

   $ percy -start this.per

Using procedures

Procedures may be used to implement any set of commands that needs to be entered more than once. The most obvious uses are for commonly used definitions and sequences of commands. However, they may be used to implement any sequence of commands, large or small, that needs to be repeated from time to time. The following tips are intended to help you to make the fullest possible use of procedures.

-- Always comment procedures. Use semicolons to construct blocks of comments for explanations, and to offset groups of related commands. It is tempting, but wrong, to think that comments aren't needed, or that it's possible to put too many comments in a procedure.

-- Submit long jobs to the batch queue. But test them first with short search intervals. (Often, a one-day search interval won't turn up anything interesting. But it is enough to let you know that a procedure is syntactically correct.) And use the STORE command to save useful schedules as soon as they are created. (That way, if a long batch run crashes, you will be able to recover at least some of the results.)

-- Procedures should clean up after themselves. Use the FORGET command to delete temporary schedules. Use the UNDEFINE command to delete temporary symbols. (Better that a later procedure should fail because a symbol is not defined, than that it should succeed with the wrong definition.)

Errors within procedures

If an error occurs during the execution of a procedure, the procedure stack is cleared immediately, and an error message is printed out. The error message is prefaced by a traceback, giving the names of the procedures remaining on the stack at the time the error occurred, in the order in which they were started.

Related Topics

1. Start
   
2. Stop
   
3. Exit
   
4. Inquire
   
5. Tailoring The Command Language
   
6. The Percy Help System