Setting Toolkit Options

The Toolkit Options

Toolkit options provide additional control over the execution of program calls and commands. All of these options can be set with the setOptions() method on a valid toolkit connection. Many can also be set globally in toolkit.ini.

Note:

In Zend Server 2019.x, the ZENDSVR6 library becomes ZENDPHP7.

// setOptions() in v1.4.0+ is an alias for setToolkitServiceParams().

$ToolkitServiceObj->setOptions(array('stateless'=>true, 'plugSize'=>'1M'));

// retrieve an option with getOption(). Example:

$isItStateless = $ToolkitServiceObj->getOption('stateless');

var_dump($isItStateless); // bool(true)

Option

Tollkit.ini

Value

Description

Section

Key

arrayIntegrity

[system]

arrayIntegrity

true (ZS 6.x default)

false (ZS 5.x default)

Introduced in 1.4.0. Specify 'true' to preserve integrity of arrays (to create true named arrays, not merely sequentially numbered elements)

ccsidAfter

[system]

ccsidAfter

If specified, something like “37/819”

Optional.

Advanced CCSID option. Generally used with ccsidBefore and useHex. Details at http://174.79.32.155/wiki/index.php/XMLSERVICE/XMLSERVICECCSID under the heading "CCSID user override - xmlservice options (hex/before/after)."

ccsidBefore

[system]

ccsidBefore

If specified, something like “819/37”

Optional

Advanced CCSID option. Generally used with ccsidAfter and useHex.

cdata

-

-

true (default)

false

Whether to ask XMLSERVICE to wrap its output in CDATA tags to protect reserved XML characters. Recommended value: 'true'.

customControl

-

-

blank (default), or a string containing one or more control strings

Specify a space-delimited string of XMLSERVICE control words to supply control words that are not otherwise “wrapped” by the PHP toolkit. Will be concatenated to the existing control key string after a single space.

Learn more about control words under the heading “XMLSERVICE Control words” here: http://174.79.32.155/wiki/index.php/XMLSERVICE/XMLSERVICEQuick

dataStructureIntegrity

[system]

dataStructureIntegrity

true (ZS 6.x default)

false (ZS 5.x default)

Introduced in 1.4.0. Specify 'true' to preserve integrity of data structures. If false, explode inner values out of the ds.

debug

[system]

debug

true

false (default)

Sets the PHP toolkit's debug mode on or off (true/false)

debugLogFile

[system]

debugLogFile

location of text debug log file, relative to file system of server running PHP

Default locations:

Zend Server 6.x: /usr/local/zendsvr6/var/log/debug.log

Zend Server 9.1 and later: /usr/local/zendphp7/var/log/debug.log

encoding

[system]

encoding

“ISO-8859-1” (default)

“UTF-8”

Encoding for XML sent to XMLSERVICE. Some languages, such as Japanese, work well with UTF-8.

httpTransportUrl

[transport]

httpTransportUrl

A URL of the form: “http://exampleIBM-i.com/cgi-bin/xmlcgi.pgm”

If 'http' was specified for the transportType, provide the URL here. To configure the http transport on your IBM i, see “Optional XMLSERVICE REST interface via RPG CGI (xmlcgi.pgm)” here: http://www.youngiprofessionals.com/wiki/XMLSERVICE

idleTimeout

-

-

blank (default)

number of seconds

If specified, will cause stateful toolkit jobs to end after a period of inactivity: the number of seconds given here. For example, '3600' would specify one hour.

internalKey or InternalKey

-

-

blank (default)

A directory such as /tmp/fred1, which need not exist

Unique directory for IPC internal key, which allows a stateful, private job to handle toolkit requests. The internalKey, which will be unique on the system, allows a PHP script to return to the same toolkit job over many requests. If internalKey is not specified, and stateless mode is false, the default internalKey will be /tmp/Toolkit. This is not recommended. Please specify either an internalKey or stateless=>true.

license

-

-

true

false (default)

For internal use (mostly).

Set to true to receive license/version information from XMLSERVICE.

parseDebugLevel

[testing]

parse_debug_level

null (default)

A number from 1-9

If parseOnly is true, supply a number from 1 to 9 to determine how much detail will return in the XML debug log. Go ahead and use 9 if you want to see fully expanded 'dim' and array structures.

parseOnly

[testing]

parse_only

true

false (default)

A useful testing flag. If true, do not run any program. Simply parse the XML, expand any 'dim' if necessary, and return. Handy for testing program calls without having the program itself. See also parseDebugLevel.

paseCcsid

[system]

paseCcsid

if specified: '819' (default)

'1208'

or another valid PASE CCSID value

For proper PASE operation with <sh> commands such as WRKACTJOB. Single byte character sets may be OK with 819, but Japanese testers have recommended 1208.

performance

-

-

true

false (default)

Not available yet. Specifies whether to enable performance collection in XMLSERVICE (experimental; Should be false unless directed by support personnel.)

plugSize

[transport]

plugSize

'4K' (4,096 bytes)

'32K' (32,000)

'65K' (65,000)

'512K' (512,000)

'1M' (1,000000)

'5M' (5,000000)

'10M' (10,000,000)

'15M' (15,000,000)

Size, in bytes, of the XML that can be sent by the toolkit as input and as output. Smaller plug sizes will improve performance. Larger plug sizes may be needed for large data payloads, such as spool files. Default: '512K'

plug

-

-

A transport-specific “plug” name, starting with either 'iPLUG' (db2) or 'iPLUGR' (odbc), plus the plugSize.

Example: iPLUG512K

Deprecated.

Instead of providing a specific plug name, we recommend providing plugSize, which will work with any transport. When you supply plugSize, the toolkit will calculate the plug automatically. Note: This is the “plug name,” or the stored procedure name, that the toolkit will use to run XMLSERVICE.

plugPrefix

-

-

'iPLUG' (default)

'iPLUGR'

For internal use.

Prefix for stored procedure name. iPLUG is ibm_db2, iPLUGR is for ODBC. We recommend using a combination of transportType and plugSize instead. The toolkit will then calculate the plugPrefix automatically.

prestart

-

-

true

false (default)

Not yet implemented. For future use. Will be able to prevent new toolkit jobs from being submitted.

sbmjobCommand

[system]

-

user-defined

Optional.

Complete override of SBMJOB command when new stateful toolkit job is submitted (experimental)

sbmjobParams

[system]

sbmjob_params

'ZENDPHP7/ZSVR_JOBD/XTOOLKIT' (default) 'QSYS/QSRVJOB/XTOOLKIT' or user-defined

Optional.

Allows partial customization of stateful toolkit job attributes.

Format: JOBDLIB/JOBD/JOBNAME

Use to customize the submit options for stateful jobs. Also see PLUGCONF1 and PLUGCONF2 members in XMLSERVICE for default values.

schemaSep

-

-

“.” (default)

“/”

For internal use.

Set automatically, in most cases, by the i5 naming flag, if supplied, to determine whether the toolkit's internal stored procedure is called with a dot or slash.

stateless

-

-

true

false (default)

We recommend that beginning toolkit users set stateless to true ('stateless'=>true). Stateless means that the toolkit's program calls will run within the database transport jobs rather than submitting additional jobs. If stateless is false or not specified, additional toolkit jobs will be submitted and you should specify an internalKey to identify them.

trace

[system]

trace

true

false (default)

Whether to enable XMLSERVICE internal log. Leave false unless directed by support personnel.

transport

-

-

true

false (default)

When true, do not actually parse XML or call any programs. Used for timing the round-trip latency of the transport itself.

transportType

[transport]

transportType

blank

'ibm_db2' (default)

'odbc'

'http' (experimental)

Optional.

PHP extension name or other transport used for connection.

The 'odbc' and 'http' transports are useful in a 2 tier environment. For example, Zend Server installed on Windows/Linux may access programs/commands on an IBM i server

useHex

[system]

useHex

true

false (default)

Optional.

Advanced CCSID option. Used with ccsidBefore and ccsidAfter to convert data to hex before sending it to XMLSERVICE, and to convert back from hex when the data returns to PHP.

v5r4

[system]

v5r4

true

false (default)

Set to true only if connecting to an v5r4 IBM i system. Not needed for 6.1 and up. When true, the toolkit will optimize program calls for v5r4, needed when calling non-ILE programs on v5r4.

XMLServiceLib

[system]

XMLServiceLib

'ZENDPHP7' (default) 'XMLSERVICE' 'QXMLSERV'

Library for XMLSERVICE programs

Usage Example

include_once 'authorization.php';
include_once '../API/ToolkitService.php';
$ToolkitServiceObj->setToolkitServiceParams(array('InternalKey'=>"/tmp/$user",
                                        'debug'=>true,
                                        'plug' => "iPLUG32K"));