CallAppEngine function

Syntax

CallAppEngine(applid[, statereclist, processinstance, allowcommit])

Where statereclist is list of record objects in the form: 

&staterecord1 [, &staterecord2] .  .  .

There can be only as many record objects in statereclist as there are state records for the Application Engine program. Additional record objects are ignored.

Description

Use the CallAppEngine function to start the Application Engine program named applid. This is how to start your Application Engine programs synchronously from a page. (Prior to PeopleTools 8, you could do only this using the RemoteCall function.) Normally, you won’t run Application Engine programs from PeopleCode in this manner. Rather, the bulk of your Application Engine execution will be run using the Process Scheduler, and the exception would be done using CallAppEngine.

The staterecord can be the hard-coded name of a record, but generally you use a record object to pass in values to seed particular state fields. The record name must match the state record name exactly.

The processinstance allows you to specify the process instance used by the Application Engine runtime. In your PeopleCode program this parameter must be declared of type integer since that is the only way the runtime can tell whether the last parameter is to be interpreted as a process instance. For more details see the Application Engine documentation.

After you use CallAppEngine, you may want to refresh your page. The Refresh method, on a rowset object, reloads the rowset (scroll) using the current page keys. This causes the page to be redrawn. GetLevel0().Refresh() refreshes the entire page. If you want only a particular scroll to be redrawn, you can refresh just that part.

Note:

If you supply a non-zero process instance, all message logging is done under the process instance. You must build your own PeopleSoft Pure Internet Architecture page to access or delete the messages, since there is no Process Monitor entry for the process instance you used.

Parameters

Parameter Description

applid

Specify the name of the Application Engine program you want to start.

statereclist

Specify an optional record object that provides initial values for a state record.

processinstance

This parameter is not used.

allowcommit

Specify an optional Boolean value indicating whether intermediate commits are allowed. If omitted, allowcommit defaults to False.

Intermediate commits of only the transactions that are related to the Application Engine program use a secondary connection to the database. Before invoking CallAppEngine with intermediate commits, the secondary connection to the database for that application server domain must be enabled using the database flags (DbFlags) in the application server configuration file. Note that the secondary connections are enabled by default. If the secondary connection to the database is disabled and CallAppEngine is invoked with allowcommit set to True, the functionality will fall back to the default where all transactions are committed only at the end of an Application Engine program.

See System and Server Administration: PSTOOLS Options

Returns

None.

Example

The following calls the Application Engine program named MYAPPID, and passes initialization values.

&REC = CreateRecord(RECORD.INIT_VALUES); 
&REC.FIELD1.Value = "XYZ";   
   /* set the initial value for INIT_VALUES.FIELD1 */ 
CallAppEngine("MYAPPID", &REC);

PeopleCode Event Considerations

You must include the CallAppEngine PeopleCode function within events that allow database updates because generally, if you’re calling Application Engine, you’re intending to perform database updates. This includes the following PeopleCode events:

  • SavePreChange (Page)

  • SavePostChange (Page)

  • Workflow

  • FieldChange

If CallAppEngine results in a failure, all database updates is rolled back. All information the user entered into the component is lost, as if the user pressed ESC.

Application Engine Considerations

You can also use the CallAppEngine function in a Application Engine program, either directly (in a PeopleCode action) or indirectly (using a Component Interface). This functionality must be used carefully, and you should only do this once you have a clear understanding of the following rules and restrictions.

  • Dedicated cursors are not supported inside a "nested application engine instance" (meaning an application engine program invoked using CallAppEngine from within another application engine program). If a nested application engine instance has any SQL actions with ReUse set to Yes or Bulk Insert, those settings are ignored.

  • As in any other type of PeopleCode event, no commits are performed within the called application engine program. This is an important consideration. If a batch application engine program called another program using CallAppEngine, and that child program updated many rows of data, the unit-of-work might become too large, resulting in contention with other processes. A batch application engine program should invoke such child programs using a Call Section action, not CallAppEngine.

  • Temp tables are not shared between a batch application engine program and child program invoked using CallAppEngine. Instead, the child program is assigned an "online" temporary table instance, which is used for all temp tables in that program. In addition, if that child program invokes another program using CallAppEngine, that grandchild shares the online temp instance with the caller. In other words, only one online temp instance is allocated to a process at any one time, no matter how many nested CallAppEngine's there might be.

  • The lock on an online temp instance persists until the next commit. If the processing time of the called program is significant (greater than a few seconds), this would be unacceptable. As a general rule, application engine programs that make use of temp tables and have a significant processing time should be called from other application engine programs using a Call Section action, not CallAppEngine.

See Application Engine: Using PeopleCode in Application Engine Programs.

Save Events Considerations

To execute the Application Engine program based on an end user Save, use the CallAppEngine function within a Save event. When you use CallAppEngine, you should keep the following items in mind:

  • No commits occur during the entire program run.

  • During SavePreChange, any modified rows in the page have not been written to the database.

  • During SavePostChange, the modified rows have been written to the database. The Page Process issues one commit at the end of the Save cycle.

FieldChange Considerations

If you don’t want the CallAppEngine call to depend on a Save event, you can also initiate CallAppEngine from a FieldChange event. When having a FieldChange event initiate CallAppEngine, keep the following items in mind:

  • No commits occur within the program called by CallAppEngine. The called program remains a synchronous execution in the same unit of work.

  • The Component Processor commits all updates done in a FieldChange at the end of the event, which frees any locks that the Application Engine program might have acquired.

  • Do not include a DoSave function in the same FieldChange event. Not only is this not allowed, but it also indicates that you should be including the CallAppEngine within a Save event.

  • You can use the DoSaveNow function in the same FieldChange event, but it must be called prior to the first CallAppEngine function, but not afterward.

Related Topics