Calling a Program or Service Program

ProgramCall API

class ProgramCall(program, options)

Creates a new ProgramCall object.

Arguments

  • program (string) – The program or service program name.

  • options (programCallConfig) –

ProgramCall.addParam(parmeter)

Adds a parameter to the program XML.

Arguments
Throws

Will throw an error when the first parameter is not an object.

Throws

Will throw an error when the object does set the type key.

ProgramCall.addReturn(data)

Specifies the type of the return value for the service program function.

Arguments
Throws

Will throw an error when the first parameter is not an object.

Throws

Will throw an error when the object does set the type key.

ProgramCall.toXML()
Returns

string – the generated program XML

programCallConfig()

ProgramCall Configuration

Arguments

  • lib (string) – The library where the program exists.

  • error (string) – Determines action when an error is encountered. Valid options are on, off, or fast. Default is fast. Using on will cause the script execution to stop and log a full error report. Using off or fast continues executing the script. The Difference is that fast will log a brief error report and off will not.

  • func (string) – The target function of the service program.

parameterConfig()

Parameter Config Object

Arguments

  • type (string) – The XMLSERVICE data type or ds for a data structure.

  • value (string) – The value of the data.

  • name (string) – The name of the parameter.

  • fields (Array.<data>) – The array of data objects for a ds.

  • io (string) – Whether the parameter is used for input, output, both, or *OMIT. Valid values are in, out, both, and omit.

  • by (string) – Whether to pass the parameter by reference or value. Valid values are ref or val. NOTE: Pass by value requires XMLSERVICE >= 1.9.9.3.

  • dim (string) – Sets ds array dimension value.

  • dou (string) – Marks ds with do until label.

  • len (string) – Marks ds with len label.

  • varying (string) – Marks data as a varying length character type (ie. varchar) and specifies the size of the length prefix. Valid values are ‘on’, off, 2, or 4 (on is equivalent to 2). NOTE: This is only valid for character types.

  • enddo (string) – The label that marks the end of the dou (do until) label.

  • setlen (string) – The label to set the length of the data based on the matching len label.

  • hex (string) – Whether to interpret the data as hex. Valid values are on or off. Default is off.

  • trim (string) – Whether to allow trim. Valid values are on or off. Default is on.

returnConfig()

Return Config Object

Arguments

  • type (string) – The XMLSERVICE data type or ds for a data structure.

  • value (string) – The value of the data node.

  • name (string) – The name of the return data.

  • fields (Array.<data>) – The array of data objects for a ds.

  • dim (string) – Sets ds array dimension value.

  • dou (string) – Marks ds with do until label.

  • len (string) – Marks ds with len label.

  • varying (string) – Marks data as a varying length character type (ie. varchar) and specifies the size of the length prefix. Valid values are on, off, 2, or 4 (on is equivalent to 2). NOTE: This is only valid for character types.

  • enddo (string) – The label that marks the end of the dou (do until) label.

  • setlen (string) – The label to set the length of the data based on the matching len label.

  • hex (string) – Whether to interpret the input as hex. Valid values are on or off. Default is off.

  • trim (string) – Whether to allow trim. Valid values are on or off. Default is on.

data()

Data Object Within DS

Arguments

  • type (string) – The XMLSERVICE data type.

  • value (string) – The value of the data.

  • name (string) – The name of the data.

  • varying (string) – Marks data as a varying length character type (ie. varchar) and specifies the size of the length prefix. Valid values are on, off, 2, or ‘4’ (on is equivalent to 2). NOTE: This is only valid for character types.

  • enddo (string) – The label that marks the end of the dou` (do until) label.

  • setlen (string) – The label to set the length of the data based on the matching len label.

  • hex (string) – Whether to interpret the data as hex. Valid values are on or off. Default is off.

  • trim (string) – Whether to allow trim. Valid values are on or off. Default is on.

Examples

Call the QUSROBJD Program

const { Connection, ProgramCall } = require('itoolkit');
const { XMLParser } = require('fast-xml-parser');

const conn = new Connection({
  transport: 'ssh',
  transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' },
});

const receiver = {
  name: 'receiver',
  type: 'ds',
  io: 'out',
  len: 'rec1',
  fields: [
    { name: 'bytes_returned', type: '10i0', value: '0' },
    { name: 'bytes_available', type: '10i0', value: '0' },
    { name: 'object_name', type: '10A', value: '' },
    { name: 'object_library_name', type: '10A', value: '' },
    { name: 'object_type', type: '10A', value: '' },
    { name: 'return_library', type: '10A', value: '0' },
    { name: 'storage_pool_number', type: '10i0', value: '0' },
    { name: 'object_owner', type: '10A', value: '' },
    { name: 'object_domain', type: '2A', value: '' },
    { name: 'creation_datetime', type: '13A', value: '' },
    { name: 'object_change_datetime', type: '13A', value: '' },
  ],
};

const errno = {
  name: 'error_code',
  type: 'ds',
  io: 'both',
  len: 'rec2',
  fields: [
    {
      name: 'bytes_provided',
      type: '10i0',
      value: 0,
      setlen: 'rec2',
    },
    { name: 'bytes_available', type: '10i0', value: 0 },
    { name: 'msgid', type: '7A', value: '' },
    { type: '1A', value: '' },
  ],
};

const objectAndLibrary = {
  type: 'ds',
  fields: [
    { name: 'object', type: '10A', value: 'QCSRC' },
    { name: 'lib', type: '10A', value: '*LIBL' },
  ],
};

const program = new ProgramCall('QUSROBJD', { lib: 'QSYS' });
program.addParam(receiver);
program.addParam({
  name: 'length_of_receiver',
  type: '10i0',
  setlen: 'rec1',
  value: '0',
});
program.addParam({ name: 'format_name', type: '8A', value: 'OBJD0100' });
program.addParam(objectAndLibrary);
program.addParam({ name: 'object_type', type: '10A', value: '*FILE' });
program.addParam(errno);

conn.add(program);

conn.run((error, xmlOutput) => {
  if (error) {
    throw error;
  }

  const Parser = new XMLParser();
  const result = Parser.parse(result);

  console.log(JSON.stringify(result));
});

Retrieve the Return Value From a Service Program

const { Connection, ProgramCall } = require('itoolkit');
const { XMLParser } = require('fast-xml-parser');

const conn = new Connection({
  transport: 'ssh',
  transportOptions: { host: 'myhost', username: 'myuser', password: 'mypassword' },
});

const program = new ProgramCall('QC2UTIL2', { lib: 'QSYS', func: 'cos' });

program.addParam({ type: '8f', value: '0', by: 'val' });
program.addReturn({ type: '8f', value: '' });

conn.add(program);
conn.debug(true);

conn.run((error, xmlOutput) => {
  if (error) {
    throw error;
  }

  const Parser = new XMLParser();
  const result = Parser.parse(xmlOutput);

  console.log(result.myscript.pgm.return.data); // 1
});