Typical use of iSeries Access for Windows Remote Command/Distributed Program Call APIs

An application that uses the iSeries™ Access for Windows^® Remote Command/Distributed Program Call function uses objects.

Each of these objects are identified to the application through a handle:

System object: This represents an iSeries system. The handle to the system object is provided to the StartSysEx function to identify the system on which the commands or APIs will be run.
Command request object: This represents the request to the iSeries system. Commands can be run and programs can be called on this object.
Note: The Command Request object previously was known as the "system object" in iSeries Access for Windows.
Program object: This represents the iSeries program. Parameters can be added, and the program can be sent to the system to run the program.

There is not a separate object for commands. The command string is sent directly to the command request.

An application that uses the Remote Command/Distributed Program Call APIs first creates a system object by calling the cwbCO_CreateSystem function. This function returns a handle to the system object. This handle then is used with the cwbRC_StartSysEx function to start a conversation with the iSeries system. The cwbRC_StartSysEx function returns a handle to the command request. Use the command request handle to call programs or to run commands. The APIs that are associated with the command request object are:

A command is a character string that is to be run on the iSeries system. Because it is a simple object (a character string) no additional object will need to be created in order to run a command. The command string simply is a parameter on the cwbRC_RunCmd API.

A program is a complex object that is created with the cwbRC_CreatePgm API, which requires the program name and the library name as parameters. The handle that is returned by this function can have 0 to 35 parameters associated with it. Parameters are added with the cwbRC_AddParm function. Parameters types can be input, output, or input/output. These parameters need to be in a format with which the iSeries program can work (that is, one for which no data transform or data conversion will occur). When all of the parameters have been added, the program handle is used with the cwbRC_CallPgm API on the command request object. The APIs that are associated with the program object are: