PHP Toolkit Testing

(click to open)

Quick Page Table of Contents


PHP Toolkit front-end new enhancements and testing of fixes

Goto Main Page
Goto PHP page
Goto Documents

Scroll down for new PHP Toolkit testing versions or go to related XMLSERVICE back-end testing versions

About PHP toolkit testing page

This page contains new versions of the PHP Toolkit front end (back end is XMLSERVICE) for testing. We recommend you try it in a testing folder. The default production location of the PHP front-end is /usr/local/zendsvr/share/ToolkitApi.

Here’s an easy way to test a new version of the PHP Toolkit front end:

1. Unzip the distribution .zip file that you download from this site.
2. Extract the contents of the ToolkitAPI subfolder of the zip file.
3. Copy the contents of ToolkitAPI to a new folder that you create on your IFS, preferably in the “share” folder.
Example: /usr/local/zendsvr6/share/ToolkitApiDev-1.6.1

4. Override the default toolkit path in your PHP script. Point to the directory where you copied the toolkit files in step 3. Example:


// set the location of your test toolkit files in front of path
$path = '/usr/local/zendsvr/share/ToolkitApiDev-1.4.0-beta1';
set_include_path($path . PATH_SEPARATOR .get_include_path() );
require_once 'ToolkitService.php';
// or: require_once 'CW/cw.php' if you're using the Compatibility Wrapper
// Connect and do everything you normally do
$conn = ToolkitService::getInstance(....);
// or if CW $conn = i5_connect(...); 

// ...more of your own code...

New, active test versions

Zip file from Github:

Older test versions (archive)

Updates since 1.4.0-beta2

1. Unnamed fields are assigned sequential names (var0, var1, var2...). Before, the numbering sometimes skipped (var0, var3, var5...)

2. The method PgmCall()‘s $returnParam parameter (param #4) can now be either an array of ProgramParameter objects or one ProgramParameter object.

3. Corrected naming of data structure subfields when the DS is repeated in an array (dimension). Before, the subfield names were discarded. 

4. Improved error reporting when program is not found ("cannot resolve" error). User $conn->getErrorCode() and $conn->getErrorMsg to access the error information.
Updates since 1.4.0-beta1

1. Program calls that return no data will now return empty arrays, rather than null values, for 'io_param' and 'retvals'.

This is a major release with significant new functionality for the new toolkit API.

Note: this release is designed to work with XMLSERVICE v1.7.5 or higher.

Updates since 1.3.3

1. New method, paseCommand(), to allow any PASE command or utility to be run from the toolkit.Sample Usage:require_once 'ToolkitService.php';

// connect
$conn = ToolkitService::getInstance('', '', '');
// stateless or InternalKey
$conn->setToolkitServiceParams(array('stateless' => true));

// directory command is good example
$cmd = "ls /www/zendsvr";

echo "Running command in PASE: $cmd<BR><BR>";

$rows = $conn->paseCommand($cmd);

if(!$rows ) {
// error
echo $conn->getLastError();
} else {
// output results, which will be a list of folders, assuming the user has authority to the folders.
echo "Output: <BR><pre>" . var_export($rows, true) . "</pre>";

2. When connecting to db2, a blank password now results in an authentication error from the toolkit. Before, the db2 driver was left to handle this. But old versions of the db2 driver sometimes interpreted a blank password as the same as a blank user profile, i.e. to use the default user, QTMHHTTP. Now a blank password is always an authorization failure, even with an older db2 driver.

3. Deprecated method: ParametersToArray(), in ToolkitServiceParameter.php, is no longer used by the toolkit. This method may be removed altogether in the future.

4. Corrected a bug introduced in 1.3.1 with the naming of array elements when ‘dim’ was used in arrays of scalar fields (individual fields, not data structures).

5. Ability in new toolkit API to efficiently send/receive arrays of fields or data structures, where an output counter can be set. Also added the ability to specify unlimited nested data structures and arrays of data structures. These could be documented more fully, and will be, but here’s an example:
// specify that we will handle DSes and arrays the modern way; that is, DS variable names are retained; arrays keep their structure
// Also may set in toolkit.ini
$conn->setOptions(array(‘dataStructureIntegrity’ => true,
‘arrayIntegrity‘ => true));

// free-standing array of character fields with maximum count of 5
$param[] = $conn->AddParameterChar('both', 21,'Part Number', 'PART', $partnum)  ->setParamDimension(5);

// DSCOUNT is a counter field, whose value that's set by RPG/COBOL program, will control the number of MULTDS fields that return (see data structure MULTDS below)
$param[] = $conn->AddParameterZoned('both', 5, 0, 'DS Counter', 'DSCOUNT', 6)
 ->setParamLabelCounter('DSCOUNT'); // note the word "Counter"
// Create array of subfields for data structure
// an character field array, size 3, that's part of the DS
$ds[] = $conn->AddParameterChar('both', 21,'Part', 'PTPRT', ‘’) 
->setParamDimension(3); // three records

$ds[] = $conn->AddParameterChar('both', 3,'Vendor', 'PTVEN', ‘’);
$ds[] = $conn->AddParameterChar('both', 20,'Description', 'PTDES', ‘’);
$ds[] = $conn->AddParameterZoned('both', 9, 2, 'Price', 'PTPRC', ‘’);

// Add data structure to param list.
// This is a multi-occurrence data structure with maximum dimension set to 100 but whose final output count will be determined by DSCOUNT.
// Note: field names are totally arbitrary. Name them whatever you wish
$param[] = $conn->AddDataStruct($ds, 'MULTDS')
->setParamDimension(100) // max of 100 records
->setParamLabelCounted('DSCOUNT'); // points to counter field that will contain actual count

6. Added ability to specify a return value (i.e. from a subprocedure) of any parameter type, even complex data structures.
Quick example:
// regular io params
$ioParams[] = $conn->AddParameterChar(......);
$ioParams[] = $conn->AddParameterZoned(......);

// return param (in this case, a data structure)
$ds[] = $conn->AddParameterPackDec(......);
$ds[] = $conn->AddParameterFloat(......);
$returnParam = $conn->AddDataStruct($ds, 'MY_DS');

// ***** look here **** fourth parameter is the return param definition
$output = $conn->pgmCall('MYPGM', 'MYLIB', $ioParams, $returnParam, array('func'=>'myfunc'));

if (!$output) {
   echo 'error running subprocedure: ' . $conn->getErrorCode() . ' ' . $conn->getErrorMsg();
} else {
  // should be an array with assoc indexes 'io_param' and 'retvals'. The return param is in retvals
    echo 'regular output params: ' . var_export($output['io_param'], true) . '<BR>';  
    echo 'return param: ' . var_export($output['retvals'], true);

7. New alias methods to make code easier to understand:
getOption() is the same as getToolkitServiceParam()
setOptions() is the same as setToolkitServiceParams()

8. Fix for CCSID override bug so that ccsidBefore and ccsidAfter work properly with RTV*-type commands. The bug occurred because SimpleXML converts all output to UTF-8. This fix requires XMLSERVICE 1.7.4 to work properly.

9. PHP toolkit version number now stored in ToolkitService.php rather than in the CW. Get it with getFrontEndVersion(), a static method, like so:
$myVersion = ToolkitService::getFrontEndVersion();
echo “PHP toolkit front-end version: ‘$myVersion’”; // 1.4.0

10. The back-end XMLSERVICE’s version number is now also accessible easily using getBackEndVersion(). It’s a regular public method, not static, and can be used after connecting to the toolkit. Example of use:
$conn = ...... ;
// connect to toolkit$conn->setToolkitServiceParams(....);
// stateless or InternalKey
$myVersion = $conn->getBackEndVersion();
echo “back-end (XMLSERVICE) version: ‘$myVersion’”; // 1.7.4

11. Retrieve diagnostics about current job with new method, getDiagnostics(), which returns an array of job information. Usage:
// assume connection already created
$diagnostics = $conn->getDiagnostics();
echo ‘<PRE>’ . print_r($diagnostics, true) . ‘</PRE>’;
// returns array containing [jobinfo][jobnbr], [jobinfo][jobuser], [joblog], [version], more. 

12. Empty content no longer causes an XML parsing error. (Eliminated the single space sometimes returned from XMLSERVICE)

13. Custom XML control keys can now be passed using the option ‘customControl’. Custom control keys are handy when testing new or “unwrappered” XMLSERVICE features. Usage:
$options = array('customControl' => '*anything *call(10/kill/server)’); // the string *anything is fake but *call can be useful to set timeouts.

14. For efficiency, the toolkit now reads toolkit.ini file only once per request. Previously, each INI key caused the file to be read repeatedly.

15. For testing toolkit functionality, we can now test XML parsing without actually running a program. In toolkit.ini:


; parse_only means do not run your program. Only parse the XML and return debug info. Useful for testing dim/dou/counters
; This setting is equivalent to the following PHP code: $conn->setToolkitServiceParams(array('parseOnly'=>true)); The default is false.
;parse_only = false

; parse_debug_level determines the amount of parsing detail to be logged in debug log (1-9: 1=none, 9=all)
; This setting is equivalent to the following PHP code: $conn->setToolkitServiceParams(array('parseDebugLevel'=>1)); // any number 1-9 
; The default is null.
;parse_debug_level = 1

This can also be done programmatically:
$conn->setOptions(‘parseOnly‘ => true, ‘parseDebugLevel => ‘1’);

16. When debug=true, and writing to debug log, Include version number of toolkit’s front end in the debug log 

17. Corrected the reporting of error codes/messages. A reliable way to get the most recent error is:
echo $conn->getErrorCode(); // output CPF or SQL error 
echo $conn->getErrorMsg(); // output error text