From YiPs Wiki (i powered)


Goto Main Page
Goto PHP page
Goto Documents

Changelog for CW
Release What has changed?
1.5.0 (new 19-Mar-2013)
Updates since 1.4.0:

1. Data areas:

1a. The default library when handling unqualified (no library given) data area names will now, for most operations, be *LIBL instead of *CURLIB. Before, *CURLIB was used all the time. *LIBL is in keeping with the usual, expected command defaults (CHGDTAARA, DSPDTAARA, et al.). The one exception, where *CURLIB will still be the default, is for the method createDataArea() and the CW function i5_data_area_create().  

Affected functions/methods: setDataAreaName() and the CW functions i5_data_area_read(), i5_data_area_write(), and i5_data_area_delete().

If your code relies on *CURLIB behavior, please specify *CURLIB explicitly rather than relying on the toolkit, because the toolkit has changed to use *LIBL most of the time. Users have told us that this is the expected behavior (and we agree).

1b. Fixed a bug where special data areas *LDA, *GDA, *PDA were getting a blank library (manifesting as an unwanted "/"). These should not have a library at all.

1c. Improved performance of readDataArea().

2. Data queues

2a. receiveDataQueue: correct spelling of method name
2b. receiveDataQueue: allow receive from non-keyed data queues
2c. several more more bug fixes

3. Transports

3a. Three new options under the new [transport] section in toolkit.ini:
; transport type allows configuration of transport from this INI. 
;transportType = "http" ; ibm_db2 is default. Other choices: "odbc", "http"
; for http transport only
;httpTransportUrl = ""
 ; default plug size, which is the expected output size. 4K, 32K, 512K (default), 65K, 512K, 1M, 5M, 10M, 15M
 ; can also change in code with $conn->setOptions(array('plugSize' => '4K')); or desired size
;plugSize = "512K" 

These three can also be set via $conn->setOptions() in code. Example:
$conn->setOptions(array('transportType'    => 'http',
                        'httpTransportUrl' => '',
                        'plugSize'         => '4K'));

Explanation of these settings:
* transportType: an easier way to specify the transport than the previously used fourth parameter of getInstance(). The default is 'ibm_db2'. Also available are 'odbc' and the new, experimental (mostly works but not officially supported) 'http'.

* httpTransportUrl: if 'http' is the chosen transport, this is the place to specify the URL. 
To set up your server for HTTP/CGI look here:
 and read the section: "Optional XMLSERVICE REST interface via RPG CGI (xmlcgi.pgm)" 

* plugSize: an easy way to change the default plug size, which is normally '512K'. If your data is basically small, try 4K. If you get an error that you suspect is because your data is bigger thank 512K, try a larger plug size. Then you can fine-tune it in your code with ->setOptions(array('plugSize'=>...whatever...));

3b. A note about the 'http' transport: if you use 'http' along with the compatibility wrapper (CW) and private connections, a bug will cause your connection to be disconnected at the end of every request unless you use the line: $conn->isPersistent(true). 

4. The debug log (when debug=true) now logs the database connection date/time and the amount of time needed to make the connection, if applicable. It also logs the transport type and related information.

5. Plug size is validated now. An exception will be thrown if an invalid plug size is supplied. 

6. Fixed a bug introduced in 1.4.0 that caused an error when reading spool files, job logs, and the system values list. The bug was related to a hard-coded plug size. 

7. New method: changeCurrentUser($user, $password), that "adopts authority" to a new user. It only works in 'stateless' mode at this time.

// must be in stateless mode to adopt authority
$conn->setOptions(array('stateless' => true));
echo Job attributes before the change: <PRE>" . print_r($conn->getJobAttributes(), true) . '</PRE>';   
$success = $conn->changeCurrentUser('NEWUSR', 'NEWPW'); // ('*NOPWD' also allowed if job user has *USE rights to new user profile)
if ($success) {
    echo Job attributes AFTER the change: <PRE>" . print_r($conn->getJobAttributes(), true) . '</PRE>';
} else {
    echo 'Failed to change user: ' . $conn->getErrorCode() . ' ' . $conn->getErrorMsg();

8. Better error reporting. For example, a specific error will be shown if the user is missing the "LOB" PTF. More specific codes are also available for command and program errors.

9. New option: 'paseCcsid', which can be set both in toolkit.ini (under [system]) and  via setOptions().
; paseCcsid controls CCSID for <sh> type of functions such as WRKACTJOB ('system' command in PASE)
; Default is 819. Another practical value is 1208 (UTF-8).
;paseCcsid = 819	

1.4.0 (new 17-Dec-2012)
Updates since 1.3.3:

The most important update in this release is probably #10, improvements to data structures and arrays.

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.

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

6. 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>";

7. 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.

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

9. 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).

10. 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)  

// 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

11. 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);

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

13. 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.

14. 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

15. 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

16. 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. 

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

18. 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.

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

20. 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’);

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

22. 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

1.3.3 (new 11-Oct-2012)
Updates since 1.3.2:

1. Fixed bug in AddParameterUInt32() in ToolkitService.php. This bug affected program calls that passed unsigned 32 bit integers. 

Thanks to Bruno for reporting the UInt32 bug:

2. Changed behavior of bin2str() method in ToolkitServiceParameter.php in order to resolve an issue with the 5250 Bridge. Before, characters such as 0D or 0A (anything hex 00-0F) would cause the returned XML to be terminated prematurely by the 5250 Bridge. This behavior caused XML parsing errors with a customer's Hebrew language IBM i system. Now, such characters are replaced with a space. 

1.3.2 (new 10–02–2012)
Updates since 1.3.1:

1. New ability to control all SBMJOB parameters when using stateful/privatejob/IPC/InternalKey mode, using new parameter sbmjobCommand. Users had partial control before; now the user has complete control. 

$user = 'FREDFLIN';
$pw = 'MYPW';

$conn = ToolkitService::getInstance('*LOCAL', $user, $pw);

if (!$conn) {
	die('no toolkit connection');

$ipc = "/tmp/$user";

// Get library of toolkit for SBMJOB command
$toolkitLib = $conn->getToolkitServiceParam('XMLServiceLib');

// build complete SBMJOB command for full customization

    'stateless'     => false,
    'InternalKey'   => $ipc,
    'sbmjobCommand' => $sbmjobCommand));

// Now if the job labeled with the requested InternalKey hasn't started yet, it will be submitted with the attributes indicated instead of the defaults from XMLSERVICE's plugconf1 or plugconf2.

2. Improved CCSID support: toolkit.ini now uses double quotes ("") instead of single quotes ('') in ccsidBefore = "819/37" and ccsidAfter = "37/819" (or whatever settings you choose), for people who need those settings. Single quotes caused a problem with Japanese. Double quotes work more reliably with PHP's INI parsing functions. (Note: these settings, along with useHex, should remain commented out unless you know that you need extra CCSID capabilities.)

3. Improved error display/logging if a database transport problem occurs.

4. Bug fixed in CW when COUNTREF is used. Before, the maximum number of records retrieved was 999. Now, if the COUNTREF reference field has a value in input, that value will be used as the maximum record count, to be potentially reduced by the actual value of the COUNTREF-referenced field in RPG/COBOL.

5. Improved data area reading to use pure PHP rather than an external service program.
require_once('iToolkitService.php'); // note the 'i'
$dataAreaObj = new DataArea($connection);
$dataAreaObj->setDataAreaName('FREDDTA', 'MYLIB');
$offset = 5; // 1-based offset. leave params blank to read all 
$lengthToUse = 2; // '*ALL' for all 
$value = $dataAreaObj->readDataArea($offset, $lengthToUse);
// if dtaara contains 'WILMAFLIN', the code above will return 'AF'.

6. In CW, allow special values such as *NOPWDCHK. Use carefully. Proper authority is required for these.

7. Improved comments and organization for easier future development.

1.3.1 (new 08–16–2012)
Updates since 1.3.0:

Note: this release works best wtih XMLSERVICE v1.7.1 or higher.

1. Improved backward compatibility with pre-1.6.8 releases of XMLSERVICE. The PHP toolkit 1.3.0 release used a program XML structure <pgm><name><lib><func>, useful for CCSID options, that is only supported by XMLSERVICE 1.6.8+. In 1.3.1 we also support the older <pgm name='xyz' lib='abc' func='doremi'> style when advanced CCSID options are not requested. 

2. New option in toolkit.ini: 
trace = false;

Set trace=true; if you want XMLSERVICE to trace low-level information to a special DB2 table. By setting trace=true, the control key *log will be sent to XMLSERVICE, signalling that XMLSERVICE should do a trace.

trace=true; causes a trace of every operation.

To trace only particular operations, do something like:
$conn->setToolkitServiceParams(array('trace'=>true)); // start internal trace
$conn->PgmCall(......); // whatever parameters you normally use here
$conn->setToolkitServiceParams(array('trace'=>false)); // end internal trace

This feature is experimental and subject to change.

1.3.0 (new 07–23–2012)
Updates since 1.2.6:

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

1. Added advanced CCSID conversion capabilities that should help execute programs and commands on systems with difficult-to-translate CCSID encoding schemes. 

Users with simple CCSID 37 won't need to use these. They may help for languages with more complex needs such as Hebrew or Japanese, or when individual pieces of data are encoded differently (such as 819 and 1208). 

Details of how XMLSERVICE implements advanced CCSID are documented at the following URL, under the heading: "CCSID user override - xmlservice options (hex/before/after)":

The easiest way to try these CCSID settings is with three new settings in toolkit.ini:
; advanced CCSID options. Use all three options together.
;ccsidBefore = '819/37'
;ccsidAfter = '37/819'
;useHex = true

Uncomment the three settings and then adjust the ccsidBefore and ccsidAfter values according to your needs. 

Another way to set these global CCSID settings is with the method setToolkitServiceParams(). In your code, after connecting with $conn::getInstance(''' etc.), set the parameters with this statement:
$conn->setToolkitServiceParams(array('ccsidBefore'=>'819/37', 'ccsidAfter'=>'37/819', 'useHex'=>true));
This technique works identically to changing INI values, except that this coding technique can be re-done over and over with different settings before each program/command call.

These "global" CCSID techniques work with both the new API and the CW, and will convert not only data/commands and command output, but the names of programs, libraries, and functions. You may notice that your data will be converted to hex inside the toolkit and then converted back to readable text by the toolkit.

For more fine-grained control over parameter data--that is, the ability to use a different CCSID conversion for each parameter, if desired--chain several new methods to AddParameterChar() like  so: (new API only--not in CW):
$param[] = $conn->AddParameterChar('both', 10,'CODE', 'CODE', $code)

These parameters can also be passed as AddParameterChar() function parameters directly but it's easier to use the setParam… methods above.

Note: these advanced CCSID settings do not affect some of the handmade API calls in the CW such as getting object lists. Helping those may be a future enhancement.

2. the "varying" attribute, allowing alphanumeric/char data to be defined as varchar, now allows '2' and '4' as well as 'on' and 'off.'  The '2' and '4' explicitly set the number of bytes set aside to denote the length of the field. 'on' implies '2'. The number '4' is needed when the length of the data is 64k or more. Thanks to Stephanie Rabbani of ExcelSystems for telling us about this need.
Example of usage:
$param[] = $conn->AddParameterChar('both', 10,'CODE', 'CODE', $code, '4')

3. Minor updates such as changing "private" methods to "protected" to allow them to be extended, additional comments in code, spelling corrections

1.2.6 (new 06–18–2012)
Updates since 1.2.5:

1. In the CW, added much more efficient handling of data structures in arrays. We now support XMLSERVICE’s ‘dim’, ‘dou,’ and ‘enddo’ so that when an array is to be output by RPG or COBOL or the like, we can specify the maximum array size (dim), and specify a field that will provide the eventual count, limiting the actual number of records that return in XML. For input, only one record to provide the structure is required. This technique will reduce the amount of XML and the time taken for program calls.

This feature will soon also be implemented in the new API as well. We encourage new development with the new API when possible.

CW example:

$progname = "XMLSERVICE/zzsrv(ZZARRAY2)";

echo "<b>About to call $progname with data structure parameters, dim, dou, enddo.</b>";

/*Call a program with parameters that include a DS */

$desc = array (
array ("Name"=>"myName", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>10),
array ("Name"=>"myMax", "IO"=>I5_INOUT,"Type"=>I5_TYPE_LONG, "Length"=>4),
array ("Name"=>"myCount", "IO"=>I5_INOUT,"Type"=>I5_TYPE_LONG, "Length"=>4),
array ("DSName"=>"findMe", "CountRef"=>"myCount", "DSParm"=>array (
         array ("Name"=>"dcMyName", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>10),
         array ("Name"=>"dcMyJob", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>4096),
         array ("Name"=>"dcMyRank", "IO"=>I5_INOUT, "Type"=>I5_TYPE_LONG, "Length"=>4),
         array ("Name"=>"dcMyPay", "IO"=>I5_INOUT, "Type"=>I5_TYPE_PACKED, "Length"=>"12.2"),

$prog = i5_program_prepare($progname, $desc);
if ($prog === FALSE) {
	$errorTab = i5_error();
	echo "Program prepare failed <br>\n";
/* Execute Program */

// The nameless elements in array.
$params = array("myName"=>"FredFlin", "myMax"=>200, "myCount"=>0);

$retvals = array("myName"=>"myName", "myMax"=>"myMax", "myCount"=>"myCount", "findMe"=>"findMe");

// make plug big enough
$conn = $prog->getConnection();

$ret = i5_program_call($prog, $params, $retvals) ;
if (function_exists('i5_output')) extract(i5_output()); // i5_output() required if called in a function

$conn->setToolkitServiceParams(array('plugSize'=>'512K')); // back to default
if ($ret === FALSE)
$errorTab = i5_error();
echo "FAIL : i5_program_call failure message: " . $conn->getLastError() . " with code <br>";
}else {
    // success
    echo "<BR><BR>Success! The return values are: <br>";
    echo "myName : " . $myName . "<BR>";
    echo "myMax : " . $myMax . "<BR>";
    echo "myCount : " . myCount . "<BR>";
    echo "findMe: " . printArray($findMe) . "<BR>";
$close_val = i5_program_close ($prog);

Updates since 1.2.4:

1. New example of sbmjob_params  in toolkit.ini, useful in 2-tier configurations where XMLSERVICE is running on a different system (or LPAR) than PHP:
; Specify an alternate sbmjob setting if ZENDSVR library isn't present on the system or LPAR. This is useful when running in 2-tier mode where XMLSERVICE and PHP run on different systems or LPARs.
;sbmjob_params = "QSYS/QSRVJOB/XTOOLKIT"

2. Fixed bug in UpdateParameterValues(). 
For usage, see /www/zendsvr/htdocs/Samples/Toolkit/CallSrvPgmFunc.php for full example
// update program parameter values for another call
ProgramParameter::UpdateParameterValues($existingParamObjArray, $newKeyValuePairs);

3. Reduced size of XML (increasing speed) by eliminating elements that reiterate XMLSERVICE defaults; and other places that XML can be reduced (thanks to Martin Hieden)
a.Omit 'io' when = 'both' (default)
b. Omit 'varying' when not specified or not 'on' (no need to reiterate default
c. Remove unneeded whitespace in XML
d. Reduce size of XML by omitting the comment=’’ element when not in debug mode.
e. Omit </data> tag when no data passed; use /> instead

4. Fixed bug in AddParameterChar() in ToolkitService.php that prevented arrays of character data from being passed.

5. Allow PCML to be parsed with user-specified encodings, according to the ‘encoding’ setting from toolkit.ini. The default is ISO-8859-1. (Thanks to Martin Hieden.)
1.2.4 (new 03–15–2012)
Note: This update works best with XMLSERVICE 1.6.8 and higher.

Updates since 1.2.3 (users of v5r4, see #4):

1. Improved ODBC support for CW
1a.To more easily manage different sized payloads over both ODBC and DB2, added an option to specify a plug size rather than the transport-dependent stored procedure name. Useful when using both ODBC and DB2 because the actual plug/procedure name will be calculated automatically based on the size and transport type. (Note: valid plug sizes at this time are 4K, 32K, 512K, 65K, 512K, 1M, 5M, 10M, 15M)

// DSPJOBLOG, a command that may generate a large amount of output, could need a large plug
$conn->setToolkitServiceParams(array('plugSize'=>'5M')); // big plug to handle large joblog
$cmdString ="DSPJOBLOG";
$interactiveOutput = $conn->CLInteractiveCommand($cmdString); // run command
$conn->setToolkitServiceParams(array('plugSize'=>'512K')); // put back to default

2. Fixed bug in CW’s i5_command() where a failing command would sometimes cause a fatal PHP error rather than return gracefully with "false" and i5_error() values

3. The disconnect() method now properly ends toolkit job (restored *IMMED keyword in getControlKey())

4. Added  v5r4 mode to help calling non-ILE (OPM) programs on v5r4 (works with XMLSERVICE 1.6.8 and up)
v5r4 mode Can be specified in two ways:
in  toolkit.ini, as v5r4=true under [system]:
in your PHP code, as needed:

5. I5_OPTIONS_JOBNAME no longer requires a toolkit.ini entry for 'sbmjob_params'
1.2.3 (new 02–17–2012)
1. Fixed a bug in CW’s i5_dtaq_receive() that interfered with multiple send/receives.
2. In CW, provide error reporting (via i5_error() and i5_errormsg()) for data queue send/receive errors and certain user space operations.
3. Default user space temporary library for Zend API is now QTEMP rather than QGPL.
4. Allow the creation of persistent database connections in Zend API (was available in CW already) via a fifth parameter, $isPersistent,  in the method getInstance().
5. New method, getJobAttributes(), that returns an array of attributes for the current job, including library list and CCSID. It’s also a good example of how to get output from “RTV”-style CL commands.
Sample output from getJobAttributes():
    [JOB] => QSQSRVR
    [USER] => QUSER
    [NBR] => 240164
    [SYSLIBL] => QSYS       QSYS2      QHLPSYS    QUSRSYS   QSYS38
    [CURLIB] => *NONE
    [USRLIBL] => QTEMP      QGPL       MYUTIL
    [LANGID] => ENU
    [CNTRYID] => US
    [CCSID] => 37
    [DFTCCSID] => 37
1.2.2 (new 02–15–2012)

Fixed bug in Zend Toolkit API when getting a list of spooled files using GetSPLList(). The bug was in RetrieveUserSpaceAttr().

1.2.1 (new 02–14–2012)
1. *CDATA key now passed by default to cause XMLSERVICE (1.6.2+) to wrap output in CDATA tags, which will make characters such as ">" safe to receive in the XML. Turned on by default. 

The use of CDATA can be turned off with the statement:
 $conn->setToolkitServiceParams(array('cdata'=>false)); // when $conn = toolkit svc connection object
Turn back on with $conn->setToolkitServiceParams(array('cdata'=>true)); 

1. *SBMJOB parameter suppressed if *HERE is specified. Was confusing before, that these mutually exclusive options would appear simultaneously.
2. XMLSERVICE 1.6.2 now provides proper encoding of output, even for errors, and can wrap output in CDATA tags (turned on by default). Therefore, so getParamsFromXmlCw()  no longer needs the cleanXml() method or to replace ampersands with entity codes, a prior workaround.
3. In CW.php, removed unneeded and incorrect getInstance() call from i5_error(). 
4. In CW.php, if functionality is called before a connection has been created, an error is now returned.
1.2.0 (new 02–08–2012)
1. ZENDSVR is now the default service library, both in toolkit.ini and in toolkit code.
2. Most settings in toolkit.ini now work for the Zend API as well as for the CW.
3. Fixed a bug where CCSID wasn’t properly set by I5_OPTIONS_RMTCCSID. 
4. Fixed a bug the Zend wrapper could not use logThis, causing errors when using Zend wrapper. It now works for the Zend wrapper as well as for the CW.
5. Added specific error reporting when db2_prepare() or db2_execute() fails because system is misconfigured (e.g. wrong service library, XMLSERVICE not installed, or wrong naming mode), or if "plug" size is too small for a given request.
1.1.8 (new 01–13–2012)

See #4 for new location and name (configurable) of debug log.

1. cwtest.php now tests for the existence of the demo libary, upon which it relies.
2. In cwtest.php, added the line: if (function_exists('i5_output')) extract(i5_output());
after every program call, command, and userspace get  that exports/output variables. Technically, this statement is not required in cwtest.php, because that script runs in the global space (as opposed to running in a function), but we added the statement to set a good example for developers who wrap their toolkit calls in functions and classes.
3. i5_adopt_authority(): make user and password uppercase
4. Debug log default name/location changed to: /usr/local/zendsvr/share/ToolkitApi/debug.log (easier to find than old /tmp location and filename) and is configurable via the debugLogFile key in toolkit.ini.
5. Fixed bug with PCML that ignored the "count" (dim) of structs when the count was specified at the "data" level.
6. If PCML is used for program calls, convert PCML string from "ANSI" format (Windows-1252 or pseudo-ISO8859-1)  (which old toolkit required) to UTF-8 (which SimpleXML requires).
7.  i5_program_call() can now capture CPF errors--viewable with i5_error()--just as i5_command() did.
8. To help the CW report CPF messages, especially when calling APIs, a $_cpfMappings array was created in cwclasses.php. Sometimes a CPF message is reported by a program that isn’t the same as the API program. The $_cpfMappings array helps the joblog/error handler find the errors. Note: this would be better as an external file, in future, but for now is a member variable in cwclasses.php.
9. Updated idle timeout to work with upcoming (v1.62) XMLSERVICE implementation, passing  control key *idle(time/kind) where time=the time in seconds to wait before ending the job that’s been idle. "kind" means don’t end the job if a program is running in it. Timeout only works with *sbmjob type toolkit jobs.
10. Fixed bug in i5_program_call (and PCML equivalent) where output-only parameters would not work properly.
1.1.7 (new 12–28–2011)
1. Performance improvement for command and program calls. Fixed a bug where a 1M plug size was sometimes used (because of an obsolete call to the Joblog class). 512K is the default.

2. New connection options: I5_OPTIONS_JOBNAME and I5_OPTIONS_IDLE_TIMEOUT. The timeout option doesn’t work yet because the XMLSERVICE toolkit (RPG) needs to be updated. CW sends the timeout value, though, so developers can plan ahead.

The cwtest.php demo script will use these options when the “jobname” and “idle_timeout” keys are specified under the [demo] heading in toolkit.ini.

If you specify the “jobname” option, you must also specify “sbmjob_params” under the [system]  heading in toolkit.ini. “jobname” will override the jobname portion of those params (JOBDLIB/JOBD/JOBNAME).

3. The New Toolkit debug logs (previously retxml.xml, input.xml, retcmdxml.xml, inputcmd.xml) have been combined into a single log (/tmp/xml_toolkit_debug.log) and new information added to it. For each XML request executed while debug mode is active, this log will provide the input XML, output XML, timestamps, control keys, disconnect requests, and the execution time. The new format and information should help users to debug their applications and to learn how the toolkit works.
1.1.6 (new 12–26–2011)
1. Private connections are now supported, using the I5_OPTIONS_PRIVATE_CONNECTION constant.

2. New function i5_get_property(). Most useful when retrieving the connection number for a private connection.

3. For the cwdemo.php test script, several connection options have been made configurable in toolkit.ini for easier experimentation

4. A public forum has been set up for questions and comments:
1.1.5 (new 12–14–2011)
Allow the re-use of an existing database connection for the transport.
This feature is optional, to allow users to gain efficiencies and avoid conflicts by re-using a database connection. In addition, the i5 naming mode can also be passed, to ensure that CW and PHP wrappers do not conflict with the naming mode of existing shared connections.

Sample use:

// Make sure the i5 naming modes match, if used.
$namingMode = DB2_I5_NAMING_ON;

// Connect to database some time before the i5_ connection is made.
$existingDb = db2_pconnect('', '','', array('i5_naming' => $namingMode));

// Add db connection to connection options                 
$options[CW_EXISTING_TRANSPORT_CONN] = $existingDb;
$options[CW_EXISTING_TRANSPORT_I5_NAMING] = $namingMode;

$conn = i5_pconnect('', '', '', $options);
1.1.4 (new 11–28–2011)
- i5_pconnect() and i5_pclose() were added. (Not private connections yet)
- Faster processing of I5_OPTIONS_RMTCCSID and I5_OPTIONS_INITLIBL when connecting. This was achieved by grouping multiple CLCommand() commands.
- I5_OPTIONS_INITLIBL works with or without commas

non-USA character sets:
- Ensure consistent  XML encoding. This is important because SimpleXml needs to see a valid encoding specified in the XML to be parsed. (Discovered by Luca Zovi with Italian accented characters).
o When creating XML, even command XML, use the encoding specified in toolkit.ini.
o If XMLSERVICE returns XML without encoding (as is currently the case with error XML), change the encoding to the default configured in toolkit.ini before trying to parse it with SimpleXml.
- Spool files: handle non-English messages (thanks, again, to Luca)
1.1.3 (new 11–21–2011)
- i5_adopt_authority (new): change current user profile in job
- Improved error messages when calling programs/APIs
1.1.2 (new 11–18–2011)
- i5_version: outputs version number of CW ('1.1.2' in this case)
- i5_connect: added I5_OPTIONS_INITLIBL and I5_OPTIONS_RMTCCSID options
- i5_program_prepare: no longer uppercases procedure function names
cwclasses.php, cwconstants.php: 
- support for the above
- Tests the I5_OPTIONS mentioned above. Feel free to change them in the script.
1.1.1 (new 11–16–2011)
- i5_command: fix for returning data (such as ccsid from rtvjoba command)
- i5_output:  new function to allow "extract(i5_output());",
              which creates output variables after calling 
              i5_command(), i5_program_call(), or i5_userspace_get()
              from inside a function or class. Not needed in global scope.


Retrieved from
Page last modified on January 22, 2014, at 04:29 PM EST