CallServiceProgram

Use the CallServiceProgram activity to invoke a service program running on an IBM i system.

General

The General tab contains the following fields:

Field Process Property? Module Property? Description
Name No No The name to be displayed as the label for the activity in the process.
IBM i Connection No Yes Click to select an IBM i shared resource.

If no matching IBM i shared resources are found, click Create Shared Resource to create one. See Creating an IBM i Shared Resource for more details.

Program Object Yes Yes The name of the service program object (*SRVPGM object). The format of the service program object name is library_name/service_program_name.

Type the service program object name manually, or click to open the Fetch Object dialog. All libraries are listed in the dialog, you can expand the library to view the list of available service program (*SRVPGM) objects.

Note: The plug-in supports the wildcard queries, you can also use the *LIBL/service_program_name format to specify a service program object.
Procedure Name Yes Yes The name of the procedure in the service program object.
Return Type No No The data type of the value that is returned from a service program call. Two types are available:
  • Numeric: A 4-byte signed integer is returned.
  • Void: The value 0 is returned.
Source File Yes Yes The name of the source file that contains the service program source member. The format of the source file name is library_name/source_file_name. Source files are used when generating the input and output schemas on the Advanced tab.

You can type the service program object name manually, or click to open the Fetch Object dialog. All libraries are listed in the dialog, you can expand the library to view the list of available service file (*FILE) objects.

Note: The plug-in supports the wildcard queries, you can also use the *LIBL/source_file_name format to specify a source file.
Source Member Yes Yes The name of the program source member. The source contains the message schema.
Wait Time (seconds) Yes Yes Specify a time interval to wait for the completion of a service program object invocation.

For example, if you set value to 500, the activity waits 500 seconds before timing out and moving onto the next activity. In this 500 seconds, the service program object invocation can succeed or fail.

The default value of Wait Time is 300 seconds. You can choose any value from a range of 300 seconds to 99999 seconds.

Description

A short description of the CallServiceProgram activity.

Advanced

In the Advanced tab, you can load parameters from an IBM i system in real time. Also, you can customize a message schema, see Creating a Message Schema for more information.

Click Initialize Schema to load the message schema from the IBM i system. A maximum of 7 parameters may be specified for a service program. This is a limitation imposed by the IBM i API QZRUCLSP used to load and invoke unbound service programs. Click Copy to copy the message schema to another activity. Click Paste to overwrite the current schema with a schema copied from another activity.
Column Name Description
Schema The schema of the object which is defined on the IBM i system.
Description A short description of the parameter.
IBM i Type The data type of the parameter that is defined on an IBM i system.
Plugin Type The data type used in this plug-in corresponding to the data type on the IBM i system.
Sequence

Enter an integer for the corresponding item or schemaNode.

The entered value indicates the maximum occurrences of the attribute in the Input tab.

For example, if you enter 3 as the sequence value for a NAME parameter, then in the Input tab, you can right-click the NAME parameter and click Duplicate to create a same NAME parameter. You can create two NAME parameters at most because the specified sequence is 3.

Directionality This field can be one of three values: "inout", "in" or "out." These values control whether the field will fall on the input, output, or both schema tabs for mapping purposes. It is only applicable for the base node of a parameter and is disabled for other fields.

Input

The input elements for CallServiceProgram activity vary depending on the message schema in the Advanced tab.

Output

The following is the output for the CallServiceProgram activity:

Output Item Data Type Description
Success Boolean A value of true indicates the operation succeeded.

A value of false indicates the operation failed.

Results Complex If the operation is successful, all parameters under the Results node have their values filled in.
  • JobID: The ID of a job. Each unit of work that is processed by the IBM i system is called a job. A job is uniquely identified by a job ID assigned by the system when the job is started.
  • Messages: The error message occurs at run time.

Fault

The Fault tab lists exceptions that are thrown by the CallServiceProgram activity:

Fault Thrown When...
IBMiPluginException The plug-in fails to get a status response due to a plug-in error.
ActivityTimedOutException The plug-in fails to get a status response due to a timeout error.
IBMiParameterConvertException The plug-in fails to convert the schema parameters.
IBMiRemoteException The plug-in fails to communicate with an IBM i system.