pjs.callProcedure()

This API calls an ILE subprocedure in a service program on IBM i. Also, see pjs.callProc() and pjs.defineProc() for simplified Profound.js API for calling procedures.

Parameters

A single Object with the following key/value pairs:

srvpgm - A String containing the service program name in LIBRARY/NAME notation. If the library is omitted, the library list will be used to resolve the service program.
procedure - A String containing the procedure name. This should match the exported procedure name (exactly, including case) as shown on the DSPSRVPGM command *PROCEXP detail screen.
result_type (optional) - A Number indicating the procedure result type. Can be omitted if the procedure does not return a value. Must be one of the following values:
- profound.RESULT_VOID (no result)
- profound.RESULT_INT8 (8-bit signed integer)
- profound.RESULT_UINT8 (8-bit unsigned integer)
- profound.RESULT_INT16 (16-bit signed integer)
- profound.RESULT_UINT16 (16-bit unsigned integer)
- profound.RESULT_INT32 (32-bit signed integer)
- profound.RESULT_UINT32 (32-bit unsigned integer)
- profound.RESULT_INT64 (64-bit signed integer)
- profound.RESULT_UINT64 (64-bit unsigned integer)
- profound.RESULT_FLOAT64 (64-bit floating point)
- profound.RESULT_FLOAT128 (128-bit floating point)
- profound.RESULT_PACKED15 (15-digit packed decimal)
- profound.RESULT_PACKED31 (31-digit packed decimal)
- An integer > 0. An aggregate (data structure or array) result of the given byte length.
arguments (optional) - An array of argument definitions. The array can be omitted if the procedure has no arguments. Each array element is an Object with the following properties:
1. type - A Number indicating the argument type. Must be one of the following values:
- - profound.ARG_INT8 (8-bit signed integer)
  - profound.ARG_UINT8 (8-bit unsigned integer)
  - profound.ARG_INT16 (16-bit signed integer)
  - profound.ARG_UINT16 (16-bit unsigned integer)
  - profound.ARG_INT32 (32-bit signed integer)
  - profound.ARG_UINT32 (32-bit unsigned integer)
  - profound.ARG_INT64 (64-bit signed integer)
  - profound.ARG_UINT64 (64-bit unsigned integer)
  - profound.ARG_FLOAT32 (32-bit floating point)
  - profound.ARG_FLOAT64 (64-bit floating point)
  - profound.ARG_FLOAT128 (128-bit floating point)
  - profound.ARG_SPCPTR (16-byte tagged space pointer or null pointer)
  - profound.ARG_OPENPTR (16-byte pointer of any type, or null pointer)
  - An integer > 0. An aggregate (data structure or array) argument of the given byte length
1. buffer - A Buffer instance containing the argument data in internal IBM i format (i.e. integer in correct byte order, packed/zoned decimal, EBCDIC-encoded character, etc.)
2. byRef (optional) - Set to Boolean true if the argument is to be passed by reference. Otherwise the argument is passed by value.
descriptors (optional) - An array of operational descriptor definitions sequenced as per the arguments array. If an an operational descriptor is not provided for an argument the API will automatically pass an element descriptor of type 'escape' (1). Each array element is an Object with the following properties:
- desctype (Number)
- datatype (Number)
- descinf1 (Number)
- descinf2 (Number)
- datalen (Number)
  
  See the CEEDOD (Retrieve Operational Descriptor Information) API documentation for descriptions of these values and the available settings.

Return Value

A buffer instance containing the procedure result, if any. No value is returned if the procedure does not return a value.

Exception Handling

If there is a problem calling the procedure, an Error will be thrown with the following properties:

message - The IBM i message text.
error - The message id.
help - The message help text.

Examples

Pass an argument by value and get a result

try {
 
  pjs.define("square", { type: "float", length: 8, initValue: 16 });
  pjs.define("root", { type: "float", length: 8 });
  pjs.callProcedure({
    srvpgm: "QSYS/QC2UTIL1",
    procedure: "sqrt",
    result_type: profound.RESULT_FLOAT64,
    arguments: [{
      type: profound.ARG_FLOAT64,
      buffer: pjs.getBuffer(square)
    }]
  }).copy(pjs.getBuffer(root));
  console.log(root);
 
}
catch (error) {
 
  // Call failed.
 
}

Pass an argument by reference

try {
 
  pjs.define("timeval", { type: "data structure", qualified: true, elements: {
    "sec": { type: "integer", length: 10},
    "usec": { type: "integer", length: 10}
  }});
  
  pjs.define("timezone", { type: "data structure", qualified: true, elements: {
    "minuteswest": { type: "integer", length: 10},
    "tz_dsttime": { type: "integer", length: 10}
  }});  
  
  pjs.callProcedure({
    srvpgm: "QSYS/QWCTZUTC",
    procedure: "gettimeofday",
    result_type: profound.RESULT_INT32,
    arguments: [
    {
      type: 8,
      buffer: pjs.getBuffer(timeval),
      byRef: true
    },
    {
      type: 8,
      buffer: pjs.getBuffer(timezone),
      byRef: true
    }    
    ]
  });
  console.log("Seconds: %d, microseconds: %d", timeval.sec, timeval.usec);
 
}
catch (e) {
 
  // Call failed.
 
}

RPG Equivalent

CALLP

Requirements

This API requires the Profound.js Connector module.