Creating a Toolkit Object

Options for Connection Settings

The getInstance() method allows two connection styles, with two different method signatures. This method can either create a new connection or reuse an existing database connection, depending on the parameters passed.

// To create a new connection, specify database name, user, and password
$ToolkitServiceObj = ToolkitService::getInstance($databaseName, $user, $password, $transportType, $isPersistent)

Arguments

Value

Description

$database name

*LOCAL – default

or database name from WRKRDBRIDE

IBM i server to connect to, identified by its database name (the database name is needed since internally, we connect to XMLSERVICE via DB2 stored procedure).

 

Specify a database name, which may be *LOCAL or a value obtained from the WRKRDBDIRE command.

$user

  • Empty string for default QTMHHTTP
  • an actual user profile name

IBM i user profile

$password
  • Empty string for default QTMHHTTP user
  • Password corresponding to $user

IBM i password

 

$transportType
  • '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.

$isPersistent
  • true
  • false (default)

Optional. For better performance when using ibm_db2 or odbc transport types, specify true here. The IBM i will make available a pool of “persistent” database jobs for use by this user/password combination. Although the toolkit makes this functionality transparent, we recommend that developers consider the implications of sharing jobs in this way.

Sample Code

Usage Example 

$ToolkitServiceObj = ToolkitService::getInstance(“*LOCAL”, “USER”, “PASSWORD”);
 
// To reuse an existing database connection as the toolkit transport, specify an existing database resource and a DB2/I5 naming flag
 
$ToolkitServiceObj = ToolkitService::getInstance($dbConn, $i5NamingFlag)

 

Arguments

Value

Description

$databaseResource

A valid database resource returned from db2_connect() or db2_pconnect()

Reuse an existing database resource in order to share QTEMP, library list, etc., (stateless mode only) or for efficiency.

Another reason to reuse the database resource is if persistent connections are used. If separate persistent connections were created by db2_pconnect and again in the toolkit, these connections might end up being shared with each other, causing problems if their options vary. By passing the resource and naming mode to the toolkit, however, you ensure that options such as the i5 naming mode will match.

$i5NamingFlag

  • DB2_I5_NAMING_ON
  • DB2_I5_NAMING_OFF (default)

Optional. Pass the same naming flag that you used in your db2_connect() or db2_pconnect(). If you didn't pass any flag there, don't pass it here, either, and the default of OFF will be used.

Sample Code

Usage Example 

// To reuse an existing database connection as the toolkit transport, specify an existing database resource and a DB2/I5 naming flag
$i5NamingFlag = DB2_I5_NAMING_ON; // ON means use slash '/' and liblists
// connect to db
$dbConn = db2_connect('*LOCAL', 'MYUSER', 'MYPW', options(array('i5_naming'=>$i5NamingFlag));
if (!$dbConn) die('Could not connect to db: ' . db2_conn_error() . ' ' . db2_conn_errormsg());
// successful db connection. Pass into toolkit
$ToolkitServiceObj = ToolkitService::getInstance($dbConn, $i5NamingFlag)