Calling IBM i APIs and Running IBM i CL Commands

Is it really mysterious to call IBM i APIs? Maybe not. A large portion of IBM i APIs are program objects in library QSYS, you can call these APIs just the same way calling a common user-written program object.

Also since most CL commands can be executed via the QCMDEXC (Execute Command) API, you can execute a CL command by calling QCMDEXC and passing the command string to be executed.

t005.as is an example of calling IBM i APIs and running CL commands in AS3 using AS-400. It's also an example of using a single reusable program-call object during multiple program-calls. (The key point of reusing a program-call object is setting the reuse:Boolean arguemnt of class RemoteCommand's constructor to true.) Now let's have a quit view of the sample code of call IBM i APIs and running CL commands in this example program.

Calling the QUSCRTUS (Create User Space) API to a create a *USRSPC (User Space) object

The QUSCRTUS (Create User Space) API is an user domain/system state OPM program object resides in library QSYS. In t005.as, it's called to create a *USRSPC object called QGPL/AS3. See the following sample code extracted from t005.as.

// private properties of class t005
private var pgm_call:RemoteCommand;
private var argl:Vector.<ProgramArgument>;
// ...

            // construct the program-call object
            pgm_call
                = new RemoteCommand(host,
                                    user,
                                    pwd,
                                    "QSYS",
                                    "QUSCRTUS",
                                    true);  // reuse this program-call object

            // compose the argument list to pass to QUSCRTUS
            argl
                = new <ProgramArgument>[new ProgramArgument(new EBCDIC(20),
                                                            ProgramArgument.INPUT,
                                                            "AS3       QGPL"),
                                        new ProgramArgument(new EBCDIC(10),
                                                            ProgramArgument.INPUT,
                                                            "AS3SPC"),
                                        new ProgramArgument(new Bin4(),
                                                            ProgramArgument.INPUT,
                                                            4096),
                                        new ProgramArgument(new EBCDIC(1),
                                                            ProgramArgument.INPUT,
                                                            String.fromCharCode(0)),
                                        new ProgramArgument(new EBCDIC(10),
                                                            ProgramArgument.INPUT,
                                                            "*CHANGE"),
                                        new ProgramArgument(new EBCDIC(50),
                                                            ProgramArgument.INPUT,
                                                            "Created by ...") ];
            // call QUSCRTUS to create *USRSPC AS3 in QGPL
            pgm_call.callx(this, cb_usrspc, argl);

Running a CL command by call the QCMDEXC (Execute Command) API

In t005.as, two CL commands are run, CHGUSRSPC to change the content of *USRSPC QGPL/AS3 and DMPOBJ to dump the content of *USRSPC QGPL/AS3.

In IBM i, most, but NOT all, CL commands can be run from an HLL program via the QCMDEXC (Execute Command) and QCAPCMD (Process Commands) APIs. When creating or changing a CL command, the ALLOW parameter controls where the CL command is allowed to run. For example, a CL command created with parameter ALLOW(*INTERACT) can only be run interactively (or in other words, with an interactive job); a CL command created with parameter ALLOW(*EXEC *INTERACT *BATCH) can be run either interactively or from a HLL program by calls QCMDEXC or QCAPCMD. Since server jobs that server calling IBM i programs instead of Flash clients using the program-call classes are batch jobs, a CL command can be called by Flash clients must contain values *EXEC and *BATCH in its ALLOW parameter. This rule also applies to all the other clients of the IBM i remote command and distributed call server.

Most IBM i shipped CL commands have the *EXEC and *BATCH values in their ALLOW parameter. You can check the ALLOW parameter by issuing the DSPCMD command on a specific CL command and check the 'Where allowed to run' attribute. Those CL commands that cannot be call by QCMDEXC in a batch job always just has no reason to be run in that manner. For example, the DFU commands. The DFU utiliteis are built to help the user to work with data in database files interactively; they surely should not be run in a batch job.

// cmd_argl is an private property of class t005
private var cmd_argl:Vector.<ProgramArgument>;
// ...

            pgm_call.pgm = "QCMDEXC";
            // change the content of *USRSPC via the CHGUSRSPC command from i5/OS Programmer's Toolkit
            cmd_argl
                = new <ProgramArgument>[new ProgramArgument(new EBCDIC(100),
                                                            ProgramArgument.INPUT,
                                                            "CHGUSRSPC USRSPC(QGPL/AS3) DTA('So nice to meet you!') DTALEN(*CALC)"),
                                        new ProgramArgument(new Packed(15, 5),
                                                            ProgramArgument.INPUT,
                                                            new Number(100)) ];
            pgm_call.callx(this, cb_usrspc, cmd_argl);

            // dump *USRSPC QGPL/AS3
            cmd_argl[0].value = "DMPOBJ QGPL/AS3 *USRSPC";
            pgm_call.callx(this, cb_usrspc, cmd_argl);