CallProgram

Use the CallProgram activity to invoke an application program running on an IBM i system.

General

You can invoke an AS/400 application program, compiled using the compiler option as PGMINFO(*PCML), in either of the following ways:
  • By parsing the program source
  • By using the PCML file

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 program object (*PGM object). The format of the program object name is library_name/program_name.

You can type the program object name, 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 program (*PGM) objects.

Note: The plug-in supports the wildcard queries, you can also use the *LIBL/program_name format to specify a program object.
Enable PCML Yes Yes

Select this option to process a PCML file to acquire program schema. It disables the Source File and Source Member fields and makes the PCML File and PCML Program Name fields editable. The plug-in parses the PCML file instead of parsing the source member.

Note: You can invoke an AS/400 program, compiled using compiler option as PGMINFO(*PCML), in either of the following ways: :
  • By parsing the program source
  • By using PCML file
This provides an additional option to import schema when the PCML file is available.
Source File Yes Yes The name of the source file that contains the program source member. The format of the source file name is library_name/source_file_name.

Type the source file name, or click to open the Fetch Object dialog. All libraries are listed in the dialog, you can expand each library to view a list of available 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 member contains the message schema.
Wait Time (seconds) Yes Yes Specify a time interval (in seconds) to wait for the completion of a program object invocation.

For example, if you set the value to 500, the activity waits 500 seconds before timing out and moving onto the next activity. In this 500 seconds, the 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.

PCML File Yes Yes Specify the path to the PCML file that contains program parameters.

Click to navigate to the location of the PCML file. You can load parameters from the PCML file to invoke PGM objects.

Note: Ensure that the file extension is in lower case.
Example: ...\...\PCMLTest.pcml
PCML Program Name Yes Yes Enter the name of a specific program contained in the PCML file.
Note: The program name is case sensitive and must exactly match the name in the PCML file.

Description

A short description of the CallProgram activity.

Advanced

In the Advanced tab, you can load the message schema from the 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. 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 a parameter.
IBM i Type The data type of a 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 in this field. This value indicates the maximum number of times this attribute can appear in the Input tab.

For example, if you enter 3 as the sequence value for an item or schemaNode, you can create the NAME parameters two more times in the Input tab. This is in addition to the one created by default.

To create an additional copy of a NAME parameter, right-click the NAME parameter and click Duplicate.

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 for the CallProgram activity vary depending on the message schema in the Advanced tab.

Output

The following is the output for the CallProgram 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 parameter names and their values are filled in under the Results node. If the operation failed, only the parameter names are filled in under the Results node.
  • 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 CallProgram 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.