pjs.runCommand()

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 ignoreError
3rd 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 or Array of message id’s: true means ignore error if command fails; false means throw error if command fails; Array means only ignore errors matching the message id’s in the Array. 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

If the command fails, 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 or C library function system() .

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.