Toolkit Compatibility Wrapper
The Toolkit Compatibility Wrapper allows scripts that use i5 Toolkit functionalities to continue to do so with requests fulfilled by the XMLSERVICE Toolkit functions with none, or limited code changes.
Configuring the PHP and Apache to Work with the XMLSERVICE Toolkit
Because the Toolkit Compatibility Wrapper uses the same function names as the i5 Toolkit , this extension must first be disabled for the Toolkit Compatibility Wrapper to be tested.
Use your standard ZENDSVR Apache instance.
This way is easiest, but any production applications that rely on i5 Toolkit may not work correctly if the extension is disabled.
To disable i5 Toolkit and test the Toolkit Compatibility Wrapper using Method 1:
Create a second Apache instance called CW where you can disable the i5comm extension. This “second instance” method is not supported by Zend, but allows you to test the Toolkit Compatibility Wrapper without interfering with existing applications. You will also get “auto prepending” of the Toolkit Compatibility Wrapper in your tests so you will not have to add an “include” or “require.”
To disable i5 Toolkit and test the Toolkit Compatibility Wrapper using Method 2:
In the special PHP.INI file, you may want to set max_execution_time = 120 or so, so that experimental long-running demo scripts will not end prematurely.
The CW instance will have a different port number than usual, perhaps something like 10092.
If you want to run your existing scripts with this CW server, you can let the Toolkit Compatibility Wrapper see them by adding Alias statements in Apache. For Example:
# Allow CW instance to run old toolkit class library from zendphp7
Alias /i5Toolkit_library /www/zendphp7/htdocs/i5Toolkit_library
# Allow requests for files in Zend Server folders (see aliases above)
allow from all
Configuring the Toolkit Compatibility Wrapper
To configure the Toolkit Compatibility Wrapper, open the /usr/local/zendphp7/share/ToolkitApi/toolkit.ini configuration file.
Configuration options include:
- debug=true or false: If debugging is on, XML input and output will be logged in the /tmp folder: input.xml, retxml.xml, (program calls), inputcmdxml.xml, and retcmdxml.xml (command calls).
- Logfile=path: Establishes a toolkit log file where warnings and errors will be logged. Log your own messages using $conn->logThis(‘string to log’).
- Under the hosts section you can set up mappings to custom database names. Generic local database names are set up by default.
- Important! Scripts may need to be changed:
Calls to i5_program_call(), i5_userspace_get(), and i5_command() can provide output by creating PHP variables. The i5 Toolkit seemingly exported these variables into local scope (outside the i5_ function, of course), while the Toolkit Compatibility Wrapper beta exports such variables into global scope. Therefore, if these functions are used within a class or a function call, please add the line
if (function_exists('i5_output')) extract(i5_output());
after the function call.
When invoking i5_program_call(), i5_userspace_get(), and i5_command() in global space (directly in the called script, not from inside a function), no changes are required.
- Many i5 Toolkit functions, such as i5_connect() and i5_program_prepare(), are returned “Resource” objects. The Toolkit Compatibility Wrapper will instead return native PHP objects. Any code that checks for is_resource() should use is_object() instead, or simply check that the object is !== false.
- I5_connect() connects to one server at a time.
An annotated version of the old PHP Toolkit Documentation has been included that indicates which functions are supported by the Compatibility Wrapper.
- Although XMLSERVICE and Zend’s new PHP wrapper can work over transports
other than ibm_db2, such as ODBC and CGI, allowing great flexibility,
the Toolkit Compatibility Wrapper has not yet been tested with these
For this beta, the focus is on ibm_db2- the best performing transport.
- Private connections have not yet been implemented.
- For the $options() parameter of i5_connect(), only I5_OPTIONS_RMTCCSID and I5_OPTIONS_INITLIBL are supported at this time. More will be added later.
- Record level access (i5_open) is not included.
- SQL access (i5_query, etc.) is not currently supported. It may be supported in a future release.
- If an error occurs, some functions provide CPF messages, some provide CPF plus error text, while others provide a more generic message. Error reporting will be improved in future releases, if possible.
- The i5_joblog_list() function works but returns a limited set of data for each joblog. This will be enhanced in future.
- The ibm_db2 setting “ibm_db2.i5_ignore_userid” is not supported at this time.
For users of 5250 Bridge: Zend Server 5.1.1 (only available from IBM at this time) includes an updated version of 5250 Bridge that works with the new toolkit, so the Toolkit Compatibility Wrapper is not required for the 5250 Bridge.
For further information on the XMLSERVICE Toolkit and the Toolkit Compatibility Wrapper, including technical documentation and updates, go to http://www.youngiprofessionals.com/wiki/XMLSERVICE.