Making External Calls

When you call one Application Engine program from another, the assignment of dedicated tables for the called, or child, program occurs only if the calling, or parent, program is in a state where a commit can occur immediately.

PeopleTools enables you to commit immediately so that Application Engine can commit the update it performs to lock the temporary table instance. Otherwise, no other parallel process could perform any assignments. In general, you should issue a commit just before the Call Section action.

While making external program calls, note that:

  • If the situation is suitable for a commit, then the temporary table assignment and the appropriate truncates occur.

  • If the situation is not suitable for a commit and the called program is set to continue if dedicated tables cannot be allocated, then the base tables are used instead and a delete by process instance is performed.

  • If the situation is not suitable for a commit and the called program is set to terminate if dedicated tables cannot be allocated, then the program run terminates.

    This situation reflects an implementation flaw that you need to correct.

  • The called Application Engine program is allowed to share temporary tables with the calling program.

    Common temporary tables are the way you share data between the calling and called programs. Application Engine locks only instances of temporary tables that have not already been used during the current program run. Temporary tables that already have an assigned instance continue to use that instance.

External Calls in Batch Mode

For batch runs, list in the program properties of the root program all of the temporary tables that any called programs or sections use to ensure that the tables are locked sooner and as a single unit. This approach can improve performance, and it ensures that all the tables required by the program are ready before a run starts.

External Calls in Online Mode

If the online program run is designed to use any temporary tables at any point during the CallAppEngine unit of work, then the root program must have at least one temporary table specified in the Application Engine program properties. This statement is true even if the root program does not use temporary tables. Having at least one temporary table specified is required so that the system locks the instance number early so as to avoid an instance assignment failure after the process has already started processing.

All temporary tables used by a specific program, library, or external section must be specified in that program to ensure that the system issues truncates (deletes) for the tables being used.

If no temporary tables appear in the root program properties and if Application Engine encounters a %Table reference for a temporary table record, then an error appears.

Sample Implementation

The following scenario describes the runtime behavior of Application Engine and temporary tables.

Assume you have Program A and Program B and three temporary table definitions: PS_TMPA, PS_TMPB, and PS_TMPC. Values on the Temporary Tables tab in the Program Properties dialog box for each program are:

  • Program A: PS_TMPA and PS_TMPB are specified as the dedicated temporary tables, and the instance count is 4.

  • Program B: PS_TMPB and PS_TMPC are specified as the dedicated temporary tables, and the instance count is 3.

After you run the SQL Build process in Application Designer, the following inventory of temporary tables appears in the database.

For PS_TMPA:

  • PS_TMPA1

  • PS_TMPA2

  • PS_TMPA3

  • PS_TMPA4

For PS_TMPB:

  • PS_TMPB1

  • PS_TMPB2

  • PS_TMPB3

  • PS_TMPB4

  • PS_TMPB5

  • PS_TMPB6

  • PS_TMPB7

For PS_TMPC:

  • PS_TMPC1

  • PS_TMPC2

  • PS_TMPC3

Because the instance count for Program A is 4, the system builds four instances of PS_TMPA and PS_TMPB for Program A to use. Because the instance count for Program B is 3, the system builds an additional three instances of PS_TMPB and three instances of PS_TMPC for Program B to use.

Notice that because Program A and Program B are sharing PS_TMPB, seven instances were built. The system derives this total by adding the instance count value from all the programs that share a particular temporary table instance. In this case, the four from Program A and the three from Program B combine to require a total of seven instances of PS_TMPB to be built.

Given that this collection of temporary tables exists in your database, assume that you start Program A. At runtime, Application Engine examines the list of temporary tables dedicated to Program A and assigns the first available instances to Program A. Then, assuming that no other programs are running, Application Engine assigns PS_TMPA1 and PS_TMPB1 to Program A.

Suppose that shortly after you started Program A, another user starts Program B. Again, Application Engine examines the list of temporary tables dedicated to Program B and assigns the first available instances. In this scenario, Application Engine assigns PS_TMPB2 and PS_TMPC1 to Program B. Because Program A is already using PS_TMPB1, the system assigns PS_TMPB2 to Program B.

The system assigns records, such as TMPA, to programs. The base tables, such as PS_TMPA, are also built, by default, in addition to the dedicated temporary instances. If the Program Properties dialog box setting for the Temp Tables tab is set to Continue when no instances are available, then the system uses the base table instead of the dedicated instance.