Using the RemoteCall Feature

This section provides an overview of RemoteCall components and discusses how to:

  • Decide between RemoteCall and PeopleSoft Process Scheduler.

  • Modify PeopleSoft Process Scheduler programs to run with RemoteCall.

RemoteCall is a PeopleTools feature that enables executing a COBOL program remotely from within a PeopleSoft application. Remote calls are made using the RemoteCall PeopleCode function.

The purpose of the RemoteCall PeopleCode function is to allow PeopleCode programs to invoke PeopleSoft application COBOL programs.

In the application server configuration file, you can specify where the COBOL executables are located.

See Remote Call Options.

The RemoteCall function is a synchronous call. The PeopleSoft system passes parameters to the remote program, and then waits while the program runs. When the remote program is done, it returns any results or status information to the invoking program, which then resumes execution. This means that RemoteCall is a think-time function. RemoteCall is designed for fast response time, and has an application programming interface (API) that provides programs with the response time needed for transaction processing. However, RemoteCall has no scheduling or multistep job capabilities. Each execution of RemoteCall is independent.

Note: As of PeopleTools 8, you can no longer use RemoteCall to execute an Application Engine program. Use the CallAppEngine function instead.

The RemoteCall PeopleTools feature consists of the following components:

  • PeopleCode programs.

    This interface consists of the RemoteCall PeopleCode function, which is used from within PeopleCode programs to start a remote program and process results.

    Note: The PeopleCode program does not include any special code to specify where the remote program is executed.

  • Remote program API.

    This is used by the remote COBOL program to receive or pass parameters and return status information.

  • PeopleSoft RemoteCall service.

    The PeopleSoft application server, PSAPPSRV, advertises the RemoteCall service. The service receives requests from PeopleCode programs and starts the requested remote program. When the remote program is completed, PSAPPSRV passes the parameters and status code back to the PeopleCode program.

  • Oracle Tuxedo.

    Oracle Tuxedo is a message-based transaction monitor for distributed applications. No direct Oracle Tuxedo calls need to be implemented in PeopleCode or remote programs.

PeopleCode Programs

You can execute the RemoteCall function from PeopleCode associated with any Component Processor event except SavePostChange, SavePreChange, Workflow, RowSelect, or in any PeopleCode event resulting from a ScrollSelect or related function call. However, remote programs that change data should not be run as part of a SaveEdit process, because the remote program may complete successfully even though an error occurs later in the save process.

To call a remote program that changes data, use FieldChange PeopleCode in a record field associated with a command button, or from a pop-up menu item.

Do not use RemoteCall if you expect the remote program to return a large amount of data to the client, because data is passed back only through the parameters of the PeopleCode API.

Authorization to run a remote program is like authorization to run a PeopleCode program. Because a remote program is started from PeopleCode, the user has authorization to use the page that executes the PeopleCode.

The remote program runs in a different unit of work from the page. A commit is issued by PeopleTools if needed on the client before RemoteCall is called. This means that, by default, the remote program does not know about any database changes unless the page is saved before the program is called. After the remote program starts, it runs to completion and commits or ends before returning to the page. In this way, the remote program and the page do not have locking contention. To ensure that the save has actually been done, use the DoSaveNow built-in function.

When using RemoteCall to execute a COBOL program, two types of errors can occur:

  • PeopleTools errors.

    An error might occur in in the application server domain while processing the remote call. These are treated as hard errors by PeopleCode. An error message box appears, and that PeopleCode program is terminated. In the case of a PeopleTools error, the remote program always either returns a code of zero or terminates with a message due to a system error.

  • Application-specific errors.

    Any error information specific to the remote application must be passed back in regular data variables, and the application can process these in an application-specific way. If you have a status code on which the application depends, you should initialize it to an invalid value to be sure the COBOL program does return the status code.

Because the remote program is executed synchronously, users receive an hourglass icon and cannot do anything in the current window until the remote program completes. They could move to another window and do processing there, or they could open another PeopleSoft window. They cannot cancel the remote program after it starts. If the program does not terminate in a timely fashion (as determined by the RemoteCall timeout set with PeopleSoft Configuration Manager), RemoteCall attempts to terminate the process and returns an error indicating that the program was terminated.

Remote Program API

The remote program API provides the functions to get and put data between the network and the COBOL program. These functions are implemented in C, but are callable from COBOL through the PTPNETRT program. For an example, see the PTPNTEST.CBL program.

Note: If these APIs are called when the program is not running as a remote program, ACTION-GET and ACTION-PUT return an error. All other actions return without doing anything.

If an unexpected error is found, call PTPNETRT with ACTION-RESET, then with ACTION-PUT to send back any error status variables, then with ACTION-DONE to send the buffer.

PeopleSoft RemoteCall Service

The RemoteCall service serves as a bridge between the PeopleCode API and remote COBOL programs. RemoteCall is one of many services advertised by the application server domain, and can be configured as part of the standard domain setup and administration.

The client sends the RemoteCall service request, consisting of the connect information and the program name, as well as any other parameters for the program, to the application server. The RemoteCall service then executes the program and passes it the connect string.

RemoteCall Programming Guidelines

Keep the following points in mind when using RemoteCall:

  • Do not use RemoteCall for long-running batch jobs.

    As a general rule, if you think execution will take more than 15 seconds, you should not be using RemoteCall, but should instead use PeopleSoft Process Scheduler.

  • RemoteCall is meant for running jobs on the application server.

    It should not be used to invoke client-only programs. Support for local calling with RemoteCall is provided solely as a debugging and development aid. For client-only programs, use Declare Function, then call the external function from a library.

  • If you do not want to modify an existing program, then pass only the program name and run control, and do not return any parameters.

    This way, the program requires few changes to run as a remote function.

COBOL application programs initiated by the RemoteCall service use the same COBOL application architecture used by PeopleSoft Process Scheduler. After being initiated by the dispatcher, COBOL application programs call the COBOL SQL API program, PTPSQLRT, to connect to the relational database management system to compile and execute SQL statements. You can design and implement COBOL programs to be understood by both PeopleSoft Process Scheduler and RemoteCall.

Follow these guidelines to select the optimal method for running a particular COBOL program:

  • Use PeopleSoft Process Scheduler for asynchronous processes, or for processes that can be scheduled, are multistep, are long-running, or that require printed output.

  • Use RemoteCall for synchronous processes that complete quickly (transaction processing types of processes).

To enable an existing program that runs under PeopleSoft Process Scheduler to run under RemoteCall as well, make the following changes:

  • Include the PTCNETRT copy member.

  • Include the PTCNCHEK member before the connection call to PTPSQLRT.

  • Add the call to PTPNETRT ACTION-DONE just before the program terminates (after the call to disconnect from the database).

    This should be conditional on whether you are RUNNING-REMOTE-CALL.

  • If you are running as a remote call, ensure that PROCESS-INSTANCE OF PRUNSTATUS is not set.

    Otherwise your calls to PTCPSTAT try to update the PSPRCSRQST table. This does not cause an error, but it is unnecessary processing.

This program can now run from PeopleSoft Process Scheduler or from RemoteCall. If a program has to pass parameters, it must have RemoteCall-specific ACTION-GET and ACTION-PUT calls.