Public Programs

Program Calling (Public Programs)

Although program overlaying provides the basic necessities for managing large applications, it still has some drawbacks. If an overlay runs a second overlay, it is assumed the first overlay is finished. If control eventually returns to the first overlay it will start executing at the beginning. Sometimes it is desirable for an overlay to resume at the point where it left off. While that may be accomplished with the use of status variables and conditionals, it is cumbersome and prone to error.

A more efficient overlaying method would use a CALL instead of a RUN to overlay programs. For example:

CALL "aprogram"

A CALL statement allows a program to execute another program and then resume after the other program completes. This is analogous to a subroutine where an entire program segment acts as a subroutine to another program segment.

Any PRO/5 program may be either RUN or CALLed, however, if a program is executing via a CALL statement, it is referred to as a "public program." There are some restrictions placed on public programs. Certain verbs are not executable while in a called mode. These are verbs that are unlikely to be used in an application program, (e.g., the DELETE verb). Any restrictions concerning commands in public programs will be listed in the Commands Manual.

Adding and Dropping Public Programs

When a public program is called, PRO/5 reads the program from a disk and loads it into main memory. The program is not loaded into the workspace. It is loaded into any available system memory outside of the workspace. This process is called "adding" the public program. When the public program is finished executing and exits, it is "dropped" from memory and that memory is made available for re-use. If a particular public program is to be called frequently, it can be loaded memory resident with the ADDR verb. The calling process is much quicker if the program does not have to be loaded from disk each time it is used. When a memory resident public program is no longer needed the DROP command may be used to remove the program from main memory.

Anytime a public program is called, PRO/5 checks to see if it is already in main memory. If so, it executes immediately. For each public program in memory PRO/5 remembers the name it was CALLed (or ADDRed) with, not counting any prefix or drive search that may have been performed by the filesystem.

Public Program Data

Unlike overlaying, each call to a public program creates a new set of variables. Although public programs are loaded outside the workspace their variables are kept within the workspace. Data can be passed back and forth between a caller and a callee by using an argument list in the CALL statement. The callee uses a corresponding ENTER statement to access the argument list. This is a great time saver for programmers since they can create public programs that may be called anywhere without the possibility of conflicting variable names. When a public program exits, its variables disappear. A public program may call itself recursively, creating a new set of variables each time.

A public program may also share all of its variables with the caller if the programmer so chooses.

As a general rule, a called program executes just as any main program executes in the workspace. However, for historical reasons, some language features do not work the same way in a called mode. For example, the PGM() function returns information about the program currently loaded in the main workspace. A public program cannot examine itself with the PGM() function (with the exception of PGM(-2)). A LIST statement in a public program will list lines from the main workspace program (note: a LIST statement in a program is highly unusual).

Normally, a public program cannot be interrupted and resumed. An ESCAPE or BREAK during public program execution must be trapped or the public program will exit to its caller with an !ERROR=39. See Error Trapping Rules for more information. This makes it impossible to interactively debug and modify a public program during execution. It is best to test and debug a public program in the main workspace before placing it into service. In an emergency, SETTRACE and DUMP are used to help diagnose bugs in executing public programs.

Interactive Editing of Public Programs

PRO/5 allows console mode within an active public program. This feature must be explicitly enabled with the SETOPTS statement:

SETOPTS $08$

Once enabled, any attempt to drop out of execution mode in a public program will cause the program to enter console mode. The name of the currently executing program will be indicated in the console mode prompt:

READY
pgmname>

The programmer may edit the program and examine or modify data just as with the main workspace with one exception. If the currently executing program has more than one activation, that is a program that has directly or indirectly called itself via recursion, then editing is not permitted.

NOTE: Public program console mode should only be enabled for development and debugging. Once software is in use in the field, customers should not see public programs drop into console mode.

Normally, when a public program is added to memory, PRO/5 allocates just enough memory for that program. If public program console mode is enabled then PRO/5 will allocate more memory pending possible edits. As the programmer edits a public program, PRO/5 will dynamically allocate more memory as needed if the program gets larger. In rare cases, this could cause memory fragmentation and generate !ERROR=33.

Some PRO/5 statements behave differently when in public program console mode as compared to public program execution mode. For example, in execution mode the END statement in a public program acts as an EXIT statement. However, in console mode, END works as it would in the main workspace. The LIST statement lists lines from the current program instead of the main workspace program.

When editing is complete the programmer may resume execution of a public program with the RUN command. While in console mode, the programmer may exit the public program by simply typing EXIT. This causes the calling program to continue execution in the usual manner.

Performing a SAVE While in a Public Program

After making edits from console mode in a public program it is usually desirable to save the changes. The SAVE command works as expected. It is also legal to save it under a new name:

SAVE "newname"

This causes the current memory copy to also inherit the new name. Care should be taken when doing this since existing ADDR's and DROP's could have unintended results.

NOTE: Executing a SAVE command while in a running Public Program will save the WORKSPACE program.

Performing a LOAD While in a Public Program

A LOAD command may be issued to load another program in place of the current program. Conceptually this works like an ordinary overlay. In actuality, the current public program is dropped and a new one is added. (If the old program is ADDRed it will remain in memory).

Performing a RUN While in a Public Program

Traditionally, a RUN statement was among the short list of "illegal" statements in a public program because public programs could only CALL other programs. PRO/5 allows a public program to RUN another public program. The new program executes at the same level as the old program. The original caller remains unaffected.

Performing an EXIT While in a Public Program

When a public program is in console mode, typing EXIT will cause the public program to be exited, and console mode to be re-entered.

Tracing in a Public Program

Whether or not public program console mode is enabled, public program execution with SETTRACE outputs complete line listings. In addition, the name of the program being traced is output on ENTER and after an EXIT. Earlier versions of PRO/5 only traced line numbers in public programs.