Calling QA Build Programs

The facilities for calling QA Build programs can be used for your menu options. However, they can also be useful when your program size exceeds the size limit and you need to split the program into smaller programs which call each other. The QA Build program you call must belong to the same database.

If you are considering how to split up a large program, you should be aware that calling a program takes longer than continuing to the next procedure. Hence, you should split your program where the program flow is minimum.

There are several options you can use that control the degree of interaction between the calling and the called programs. For example if a program is called as part of a menu system it will probably be fairly independent of the calling program, and it should not unduly affect the caller, while if for reasons of size you have had to convert a call to another procedure to a call to another QAB program with that procedure as its topmost procedure, you will want to be able to call the QAB program in such a way that the behaviour is unchanged.

This command calls a QA Build program on the system called CREDIT. It is called as an overlay: %CALL CREDIT %OVERLAY

Although QA Programs can read options specified on the command line, this applies only to programs called directly by the operating system. You cannot pass a command tail into a called QAB program using the %CALL facility. If it is imperative that you pass a command line option to another QAB program it must be called as though it were a non QAB program, for example:
progrun -db %db% -prog another -my_tail value

Commands

There are two methods of calling one QAB program from another, depending on whether you want to resume execution of the first program when the second has finished.

%CALL

Call the QA Build program which follows this command and return when it has terminated.

If the called program performs a %LOGON, the original user will be restored when the called program terminates.

%CHAIN

Call a QA Build program but do not return.

If program 1 calls program 2 and that chains to program 3 control will still return to program 1 when program 3 terminates.

Use this option with caution; repeated use may eventually cause your program to run out of memory. In particular avoid repeatedly chaining round a loop of programs.

Command Tails

The following command tails can be used with %CALL and %CHAIN to control the interaction between the caller and called programs.

%field_name%

Substitute into the command the contents of the named character field.

For example, your program may define a local character field called NEXT_PROGRAM. The command for the procedure is %CHAIN %NEXT_PROGRAM%. If the contents of NEXT_PROGRAM is "SALESREP", the command executed by the procedure will be %CHAIN SALESREP.

The substitution is made for %CALL and %CHAIN commands, and for passing parameters to non QA Build programs. As the substituted value is not parsed, you cannot substitute a %command or %command tail.

%NOLOG

Suppress a line being written to the system log.

When a program is called from a DP4 menu, an entry is made in the system log, SYSLOG.PRN (not for programs called using %OVERLAY).

%NOSAVE

Do not save data in calling program (for %CALL only).

If you do not use %RECEIVE, the data in the calling program will be recovered when the called program terminates. Avoiding this saving and recovering routine may give a minor performance improvement.

%OVERLAY

Force called program to behave as part of the calling program (for %CALL only).

The effect of the two programs behaving as one includes the following:

• Data is completely shared.
• A logon in the called program is not lost on return to the calling program.
• A logoff in the called program restarts the calling program.
• The called program inherits the caller's current print device, unless the calling program does not have a print device and the called program's program summary does initialise a print device.
• The screen layout map, if there is one, is not displayed unless the %SAVESCRN option is specified. In general an overlay program should specify the same layout map as the calling program in the program summary.
• There is normally an implied decommit whenever a QAB program terminates to through away any uncommited transactions. This is supressed for programs called with %overlay allowing a single transaction to be split over overlays.
• A program termination (caused by %SYSTEM command, an error or through the user terminating the program with <Ctrl+S> <Ctrl+C>, <Alt+F4> etc) in the called program terminates the caller

This option includes the effect of %SEND, %RECEIVE and %NOLOG.

%RECEIVE

Receive data back from the called program (for %CALL only).

This data includes data in tables which have the same role names in both programs and local fields which have the same names in both programs.

%SAVESCRN

Saves the state of the screen and restores it when the called program has terminated. The maps already displayed by the calling program will not be accessible to the called program.

%SEND

Send data in the calling program to the called program.

This data includes data in tables which have the same role names in both programs and local fields which have the same names in both programs.