Creating a Connection

Transports

The Connection Class uses ODBC, SSH, idb, and REST transports to access XMLSERVICE. Some transports require prerequisite setup. Learn morre about each transport below.

ODBC

The ODBC transport establishes a database connection and calls XMLSERVICE stored procedure. Refer to the odbc guide for setup instructions.

SSH

The SSH transport executes xmlservice-cli program via ssh. Install xmlservice-cli before using the SSH transport.

$ yum install itoolkit-utils

idb

The idb transport establishes a database connection and calls the XMLSERVICE stored procedure.

NOTE the idb transport is only supported on an IBM i system.

REST

The REST transport makes an HTTP request to an endpoint that process the XML input and returns XML output.

Initial configuration is required for the endpoint.

A quick example is to add the following to /www/apachedft/conf/httpd.conf.

ScriptAlias /cgi-bin/ /QSYS.LIB/XMLSERVICE.LIB/
<Directory /QSYS.LIB/XMLSERVICE.LIB/>
AllowOverride None
Require all granted
SetHandler cgi-script
Options +ExecCGI
</Directory>

Connection API

class Connection(options)

Creates a new Connection object.

Arguments

options (connectionConfig) –

Throws

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

Throws

Will throw an error when an invalid transport is set.

Connection.add(xml)

Adds xml to the command list. When an instance of CommandCall, ProgramCall, or iSql is passed .toXML() is invoked to return the underlying xml.

Arguments

xml (string|object) – The xml to add to the command list.

Connection.debug(flag)

Enables or disables the verbose output for debugging.

Arguments

flag (boolean) – Whether to enable verbose output.

Returns

boolean – The current state of the debug flag.

Connection.getTransportOptions()

Returns: object – The transportOptions property from the Connection object.

Connection.run(callback)

Invokes transport with xml generated from joining the command list. Note the command list is cleared after calling this function. Once the transport is complete the user provided callback function is called. Note If returnError is false the first callback paramter will be the xml output. This is a compatabilty feature with the deprecated iConn Class which did not return errors.

Arguments

callback (runCallback) – the callback function.

connectionConfig()

Connection Config Object

Arguments

transport (string) – The transport to use.
transportOptions (odbcOptions|sshOptions|idbOptions|restOptions) – The transport options.
verbose (boolean) – The flag for verbose output.
returnError (boolean) – The flag to disable error first callback for Connection.run().

odbcOptions()

ODBC Transport Options Object

Arguments

dsn (string) – The dsn to use.
host (string) – The hostname of the server. Default is localhost.
username (string) – The user to connect as.
password (string) – The user’s password.
ipc (string) – The key name/security route to XMLSERVICE job. Default is *NA.
ctl (string) – The control options for XMLSERVICE jobs. Default is *here.
xslib (string) – The XMLSERVICE library. Default is QXMLSERV.

sshOptions()

SSH Transport Options Object

Arguments

host (string) – The hostname of the server.
username (string) – The user to connect as.
password (string) – The user’s password.
privateKey (string) – The user’s privateKey.
passphrase (string) – The user’s passphrase to decrypt the private key.

idbOptions()

idb Transport Options Object

Arguments

database (string) – The database to connect to. Default is *LOCAL.
username (string) – The user to connect as.
password (string) – The user’s password.
ipc (string) – The key name/security route to XMLSERVICE job. Default is *NA.
ctl (string) – The control options for XMLSERVICE jobs. Default is *here.
xslib (string) – The XMLSERVICE library. Default is QXMLSERV.

restOptions()

REST Transport Options Object

Arguments

database (string) – The database to connect to. Default is *LOCAL.
username (string) – The user to connect as.
password (string) – The user’s password.
ipc (string) – The key name/security route to XMLSERVICE job. Default is *NA.
ctl (string) – The control options for XMLSERVICE jobs. Default is *here.
url (string) – The url to the xmlcgi endpoint. E.g. http://localhost:80/cgi-bin/xmlcgi.pgm

runCallback(transportError, xmlOutput)

Arguments

transportError (Error|null) – The error object if a transport error occured or null.
xmlOutput (string|null) – The xml output or null if an error occured.

Examples

Creating a Connection using the ODBC tranport.

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

Creating a Connection using the ODBC tranport with a DSN.

const connection = new Connection({
  transport: 'odbc',
  transportOptions: { dsn: '*LOCAL'}
});

Creating a Connection with ssh tranport using private key to authenticate.

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

Creating a Connection using the ssh tranport with a private key to authenticate.

const { readFileSync } = require('fs');

const privateKey = readFileSync('path/to/privateKey', 'utf-8');

// NOTE if your privateKey also requires a passphrase provide it

const connection = new Connection({
transport: 'ssh',
transportOptions: { host: 'myhost', username: 'myuser', privateKey, passphrase: 'myphrase' }
});

Creating a Connection using the idb tranport.

const connection = new Connection({
  transport: 'idb',
  transportOptions: { database: '*LOCAL', username: 'myuser', password: 'mypass' }
});

Creating a Connection using the REST tranport.

const connection = new Connection({
  transport: 'rest',
  transportOptions: {
     database: '*LOCAL',
     username: 'myuser',
     password: 'mypass',
     url: 'http://myhost.example.com/cgi-bin/xmlcgi.pgm',
   }
});