Description

This API defines a JavaScript function that maps to an external procedure in an IBM i service program, similar to a prototype in an ILE program.

If a function by the same name is already exported by the pjs.requireServiceProgram() or pjs.requireModule() API, the call to pjs.defineProc() will have no effect, and the exported function will be used instead of the external procedure specified by pjs.defineProc().

Parameters

Function name - A String that specifies the name of the JavaScript function to create within the current scope.
Configuration - An object with the following properties:

srvpgm (optional) - A String containing the name of the service program to use. The service program name can be qualified with a library; otherwise, the library list will be used to resolve the service program. If the service program is not specified, the API will attempt to resolve the procedure automatically.
extProc (optional) - A String containing the name of the external procedure in the service program. If not specified, the procedure name is assumed to be the same as the function name.
parms - An array of parameter definitions. Each parameter definition is a configuration object of the format used by pjs.define(). Optionally, you can attach a name property to the configuration objects to identify parameter names; however, the name is for informational purposes only and is not used internally by the API. Each configuration object may also contain a byRef true/false property, which specifies whether the parameter is passed by reference. The default value for byRef is false. Reference parameters can have an optional const true/false property. When const is true, a copy of the parameter value will be passed by reference to the procedure, and the original parameter value will not be modified. The default value for const is false. pjs.refParm() must be used when calling the function and passing parameters by reference, unless const is true or unless you are using external definitions.

Parameter definitions for pointer type can have additional options:
- string (Boolean) - Set to true to allow passing a String in place of the pointer. A pointer to a temporary memory area with a null-terminated copy of the string will be passed.
- dataLen (Number) - Set to a positive integer to limit the amount of data sent to the backend for the pointer parameter. If the buffer pointed to by the pointer is longer than this number, it will be truncated. This option is ignored if string is specified.

result (optional) - A configuration object of the format used by pjs.define(), which defines the procedure’s return value. This property should only be specified if the procedure has a return value.

Examples

Calling a System API

// Prototype the C runtime function sqrt() from QSYS/QC2UTIL1 as a plain
// JavaScript function. pjs.defineProc() is the high-level equivalent of an ILE
// prototype -- Profound.js converts the arguments and the result for you.

pjs.defineProc("sqrt", {
  srvpgm: "QSYS/QC2UTIL1",
  parms: [
    { type: "float", length: 8 }        // one 8-byte float, passed by value
  ],
  result: { type: "float", length: 8 }
});

// Use the external procedure as a simple function.
console.log(sqrt(16));   // 4 (the square root of 16)

Calling a Procedure in Your Own Service Program

// The JavaScript function name and the ILE export name do not have to match:
// "extProc" names the procedure that the service program actually exports.

pjs.defineProc("getItemPrice", {
  srvpgm: "PGMLIB/SALESORDER",
  extProc: "GETPRICE",                                  // RPG export names are usually uppercase
  parms: [
    { type: "packed decimal", length: 7, decimals: 0 }   // item number, passed by value
  ],
  result: { type: "packed decimal", length: 9, decimals: 2 }
});

pjs.define("itemNumber", { type: "packed decimal", length: 7, decimals: 0, initValue: 1234 });
pjs.define("price",      { type: "packed decimal", length: 9, decimals: 2 });

// Use the external procedure as a simple function.
price = getItemPrice(itemNumber);
console.log(price);

Passing Parameters by Reference

// Every parameter is marked "byRef", so the procedure updates the caller's
// fields in place rather than returning a value.

pjs.defineProc("addressAutoCorrect", {
  srvpgm: "PGMLIB/SALESORDER",
  extProc: "FIXADDR",
  parms: [
    { name: "addressLine1", type: "char", length: 30, byRef: true },
    { name: "addressLine2", type: "char", length: 30, byRef: true },
    { name: "city",  type: "char", length: 20, byRef: true },
    { name: "state", type: "char", length: 2,  byRef: true },
    { name: "zip",   type: "decimal", length: 5, decimals: 0, byRef: true }
  ]
});

// Define the caller's fields and seed them with the address to correct.
pjs.define("line1", { type: "char", length: 30 });
pjs.define("line2", { type: "char", length: 30 });
pjs.define("city",  { type: "char", length: 20 });
pjs.define("state", { type: "char", length: 2 });
pjs.define("zip",   { type: "decimal", length: 5, decimals: 0 });

line1 = "562 CONGRESS PRK";
city  = "CENTERVILLE";
state = "OH";
zip   = 45458;

// pjs.refParm() must be used for by-reference parameters, so the procedure's
// corrected values are written back into line1, line2, city, state and zip.
addressAutoCorrect(pjs.refParm("line1"), pjs.refParm("line2"),
                   pjs.refParm("city"), pjs.refParm("state"), pjs.refParm("zip"));

console.log(line1, line2, city, state, zip);

Requirements

This API requires the Profound.js Connector module.