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.

Method 1

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.

Instructions on how to complete a procedure

To disable i5 Toolkit and test the Toolkit Compatibility Wrapper using Method 1:

  1. Comment out the following directive in the /usr/local/zendphp74/etc/php.ini  file:
    ;extension=i5comm.so

  2. Restart Apache.

Method 2

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

Instructions on how to complete a procedure

To disable i5 Toolkit and test the Toolkit Compatibility Wrapper using Method 2:

  1. Copy the 'php.ini' file from
    /usr/local/ZendSvr/etc/php.ini
     to
     /usr/local/ZendSvr/etccw/php.ini

  2. Edit /usr/local/ZendSvr/etccw/php.ini:

  • ;disable i5 toolkit extension
  • ;extension=i5comm.so
  1. Also in this special 'PHP.INI' file, add ToolkitAPI path to the 'include_path' directive:
    /usr/local/zendphp74/share/ToolkitAPI
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.
  1. Find “auto_prepend_file” in the INI and set it as below to point to the shared location (within the include_path set earlier) of the Toolkit Compatibility Wrapper library, so all your scripts in this instance will automatically use the Toolkit Compatibility Wrapper:
    auto_prepend_file = "CW/cw.php"

  2. Save this INI file.

  3. Set up a new Apache instance, called CW, with configuration in /www/cw/conf and its own fastcgi.conf in the same folder.

The CW instance will have a different port number than usual, perhaps something like 10092.

  1. In /www/cw/conf/fastcgi.conf, point to the custom directory where php.ini resides:
    SetEnv="PHPRC=/usr/local/ZendSvr/etccw"

  2. If you need to change anything in conf.d, you can also set:
    SetEnv="PHP_INI_SCAN_DIR=/usr/local/ZendSvr/etccw/conf.d"

  3. Start the CW Apache instance.

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 zendphp74 
                    
Alias /i5Toolkit_library /www/zendphp74/htdocs/i5Toolkit_library
# Allow requests for files in Zend Server folders 
		 (see aliases above)
<Directory /www/zendphp74/htdocs>
  Options FollowSymLinks 
  order allow,deny
  allow from all 
  AllowOverride all
</Directory>

 

Configuring the Toolkit Compatibility Wrapper

To configure the Toolkit Compatibility Wrapper, open the /usr/local/zendphp74/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.

Compatibility Changes

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

Limitations

  • 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 methods.
    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 further information on the XMLSERVICE Toolkit and the Toolkit Compatibility Wrapper, including technical documentation and updates, go to http://www.youngiprofessionals.com/wiki/XMLSERVICE.