RemoteCall function

Syntax

RemoteCall(dispatcher_name [, service_paramlist] [, user_paramlist])

where service_paramlist and user_paramlist are arbitrary-length lists of parameters in the form: 

var1, val1 [, var2, val2]. . .

Description

Use the RemoteCall function to call a Tuxedo service from a PeopleSoft application. A typical use of Remote Call is to run data-intensive, performance-sensitive programs near or on the database server.

Note:

After PeopleTools 8 you can no longer use RemoteCall to start an Application Engine program. You must use CallAppEngine instead.

Because complex PeopleCode processes can now be run on the application server in three-tier mode, the RemoteCall PeopleCode function has more limited utility. However, RemoteCall can still be very useful, because it provides a way to take advantage of existing COBOL processes.

  • In three-tier mode, RemoteCall always runs on the application server.

  • In two-tier mode, RemoteCall always runs on the client.

This means that it is no longer necessary to set a location for the remote call in PeopleSoft Configuration Manager.

Each RemoteCall service can have zero or more standard parameters and any number of user parameters. The standard parameters are determined by the RemoteCall dispatcher, the user parameters by the COBOL program being run.

There is only one RemoteCall dispatcher delivered with PeopleTools 7, PSRCCBL, which executes a COBOL program using the connect information of the current end user.

In the application server configuration file, you can specify where RemoteCall can find the COBOL executables

RemoteCall can be used from any type of PeopleCode except SavePostChange, SavePreChange, Workflow, and RowSelect. However, remote programs that change data should not be run as part of the SaveEdit process, because the remote program may complete successfully even though an error occurs in a later part of the save process. For remote programs that change data, the normal place for them would be in the FieldChange PeopleCode behind a command push button, or in a pop-up menu item.

After you use RemoteCall, 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. The following code refreshes the entire page:

GetLevel0().Refresh()

If you only want a particular scroll to be redrawn, you can refresh just that part.

Parameters

The parameters passed to RemoteCall can be broken into three parts: the RemoteCall Dispatcher Name, the standard Parameter Lists for the service, and the User Parameter Lists for the program being called on the service.

Returns

None.

Example

You could use the following PeopleCode to execute the program "CBLPROG1":

Rem Set the return code so we are sure it is sent back.
&Returncode = -1;
Rem Set the parameters that will be sent across.
&param1 = "John";
&param2 = "Smith";
Rem Set the standard parameters that indicate program name and run-control.
&RemoteCobolPgm = "CBLPROG1";
/* call the remote function */
RemoteCall ("PSRCCBL", 
"PSCOBOLPROG", &RemoteCobolPgm, 
"PSRUNCTL", workrec.runctl,
"FirstName", &param1,
"LastName", &param2,
"Returncode", &Returncode,
"MessageSet", &msgset,
"MessageID", &msgid,
"MessageText1", &msgtext1,
"MessageText2", &msgtext2);
if &Returncode <> 0
   WinMessage(MsgGet(&msgset, &msgid, "default message", &msgtext1, &msgtext2));
end-if;

Dispatcher Name

The dispatcher_name parameter is a string value that specifies the type of RemoteCall performed. For PeopleTools 7 there is only one RemoteCall dispatcher delivered, PSRCCBL, which executes a COBOL program using the connect information of the current end user, so the value you pass to this parameter should always be "PSRCCBL". Future versions of PeopleTools may provide support for Red Pepper, SQR, or customer supplied remote calls.

Parameter Lists

Both the standard parameter list and user parameter list have the same form. Think of the parameters passed to the service as being passed as pairs of variable names and values of input and output parameters:


                  variable_name, value

Where:

  • variable_name is a string literal or string variable that contains the name of the input or output variable as referenced in the remote program. For example, if the remote program expects a variable named "USERNAME", then the PeopleCode should use "USERNAME" or &VARIABLE (which had been assigned the value "USERNAME").

  • For input variables, value is the value to be passed to the remote program with the variable name. It can be either a variable or literal with a data type that corresponds to the variable_name variable. For output variables, value is the value returned to the PeopleCode program from the remote program. It must be a variable in this case, representing the buffer into which the value is returned.

An arbitrary number of parameters can be passed to the service. There is, however, a limitation on the number of variables that can be passed in PeopleCode, which is limited by the size of the PeopleCode parameter stack, currently 128.

In the case of the PSRCCBL dispatcher, there are three standard parameters, listed in the following table:

Dispatcher Parameter Required Description

PSRCCBL

PSCOBOLPROG

Y

Name of the COBOL program to run.

PSRCCBL

PSRUNCTL

N

Run-control parameter to pass to the COBOL program.

PSRCCBL

INSTANCE

N

Process instance parameter to pass to the COBOL program.

User Parameter List

For PSRCCBL, the remote COBOL program must match the user parameters to the usage of its application. The names of the parameters are sent to the server and can be used by the COBOL program. The COBOL program returns any modified (output) parameters by name. Parameters which are not returned are not modified, and any extra returned parameters (that is, parameters beyond the number passed or of different names) are discarded with no effect.

Related Topics