This API is used to execute an IBM i CL command.
Note: In Profound.js release 7.10.0, API pjs.runCommand() was improved to work very similar to the C library function system() as called by RPG programs, with the following additions:
2nd optional parameter
ignoreError3rd optional parameter
msgId.return value of -1, 1, or 0.
These changes are backward-compatible with earlier releases of Profound.js; i.e. any current Profound.js modules that do NOT use these new features will behave as before.
Parameters
Command - A string containing a CL command to execute.
ignoreError - optional boolean value: “true” = ignore error if command fails; “false” = throw error if command fails. Default is “false”.
msgId - optional strongly-defined char(7) field to be updated with the error MsgId if the command fails.
Return value
-1 : null is passed for command
1: command fails
0: command is successful
Exception Handling
An Error instance will be thrown with the following properties, if the 2nd optional parameter ignoreError is not specified or “false”.
message - The IBM i message text.
statusCode - The message id.
RPG Equivalent
QCMDEXC System API
Examples
Example 1: Check for existence of an object
var command = "CHKOBJ OBJ(QTEMP/WORKFILE) OBJTYPE(*FILE)";
var exists = true;
try {
pjs.runCommand(command);
}
catch(e) {
exists = false;
}
Example 2: Create a duplicate file in QTEMP
var command = "CRTDUPOBJ OBJ(ORDERSP) FROMLIB(DATALIB) OBJTYPE(*FILE) TOLIB(QTEMP) NEWOBJ(WORKFILE) DATA(*NO)"; pjs.runCommand(command);
Example 3: Run a command with parameters with return value (this feature is available since Profound.js 6.0.0)
CL code:
DCL VAR(&NBRRCD) TYPE(*DEC) LEN(10 0)
RTVMBRD FILE(PJSTEST/PRODUCTSP) NBRCURRCD(&NBRRCD)
PJS code:
pjs.define("nbrRcd", { type: 'packed', length: 10, decimals: 0});
pjs.runCommand(`RTVMBRD FILE(PJSTEST/PRODUCTSP) NBRCURRCD(&nbrRcd)`);
console.log(`nbrRcd = ${nbrRcd}`);
Examples for error-handling
Example 4: No error-handling: run-time error is thrown if command has error
pjs.runCommand(`CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE)`);
Error thrown:
Profound.js Error: Object MYFILE in library MYLIB not found. : CPF9801 - Cause . . . . . : The object MYFILE in library MYLIB type *FILE not found. The object name, library name, or the object type is not correct. If the library name is not specified, the object may be in a library that is not contained in the library list. Recovery . . . : Correct the object name, library name, or object type. If the library name was not specified, specify the library name and try the request again.
at profound.runCommand (c:\dev\profoundjs\profoundjs\api\runCommand.js:73:29)
at process.processTicksAndRejections (c:\dev\profoundjs\lib\internal\process\task_queues.js:95:5)
at async Object.app (c:\dev\profoundjs\modules\ado12345\mypgm_01.js:3:5)
at async profound.call (c:\dev\profoundjs\profoundjs\api\call.js:162:25)
at async profound.utils.<computed> [as handleExternalCall] (c:\dev\profoundjs\profoundjs\dat\bdba69cb3be3b6c.js:1:23224)
at async Strand._fn (c:\dev\profoundjs\profoundjs\server\controller.js:221:11)
at async C:\dev\profoundjs\node_modules\profoundjs-strands\index.js:29:18
at async Strand.run (C:\dev\profoundjs\node_modules\profoundjs-strands\index.js:28:16) {statusCode: 'CPF9801', name: 'Profound.js Error', appJob: undefined, currUser: undefined, stack: 'Profound.js Error: Object MYFILE in library M…_modules\\profoundjs-strands\\index.js:28:16)', …}
Example 5: Use try/catch
CL code:
CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE)
MONMSG MSGID(CPF0000)
PJS code:
try {
pjs.runCommand(`CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE)`);
} catch (error) {
console.log(`handle error here if needed`);
}
Example 6: Specify 2nd optional parameter ignoreError as “true”
CL code: CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE) MONMSG MSGID(CPF0000) PJS code: pjs.runCommand(`CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE)`, true);
Example 7: Specify 2nd optional parameter ignoreError as “true”, and specify a MsgId field to get error MsgId
CL code:
DCL VAR(&MSGID) TYPE(*CHAR) LEN(7)
CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE)
MONMSG MSGID(CPF0000) EXEC(DO)
RCVMSG MSGID(&MSGID)
/* handle error based on MsgId here */
ENDDO
PJS code:
pjs.define("msgId", {type: 'char', length: 7});
pjs.runCommand(`CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE)`, true, msgId);
if (msgId != "") {
console.log(`msgId = ${msgId}`);
// handle error based on msgId here
}
Example 8: Specify 2nd optional parameter ignoreError as “true”, specify a MsgId field to get error MsgId, and check return value
CL code:
DCL VAR(&MSGID) TYPE(*CHAR) LEN(7)
CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE)
MONMSG MSGID(CPF0000) EXEC(DO)
RCVMSG MSGID(&MSGID)
/* handle error based on MsgId here */
ENDDO
PJS code:
pjs.define("msgId", { type: 'char', length: 7});
if (pjs.runCommand(`CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE)`, true, msgId) != 0) {
console.log(`msgId = ${msgId}`);
// handle error based on msgId here
}
Example 9: MONMSG for a specific error MsgId
CL code:
DCL VAR(&MSGID) TYPE(*CHAR) LEN(7)
CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE) MBR(MYMBR)
MONMSG MSGID(CPF9815) EXEC(DO)
RCVMSG MSGID(&MSGID)
/* handle error member-not-found here */
ENDDO
PJS code:
try {
pjs.runCommand(`CHKOBJ OBJ(MYLIB/MYFILE) OBJTYPE(*FILE) MBR(MYMBR)`);
} catch (error) {
if (error.statusCode == "CPF9815")
console.log(`handle error member-not-found here`);
else
throw (error); // throw other errors
}
Requirements
This API requires the Profound.js Connector module.