i5_pconnect

Create or get a persistent connection to an AS/400 server.

resource i5_pconnect (string server, string user, string password [, array options] )

Parameters

server	Name of the IBM i server. Can be either a DNS name, an IP address, or special keyword I5_SAME_JOB. Special keyword I5_SAME_JOB can be used when running PHP on IBM i. Connection is then established within the actual PHP server job. No additional job is created on the system. When running PHP on IBM i, set this parameter to an empty string to connect to the local system. When running PHP on Windows or Linux, server name or address is mandatory. Default port is 6077. To change port, add the port number after the server’s name or address, separated by a colon: Example: I5SERVER:6079
user	Username to use for connection. When your PHP server is running on Windows or Linux, Username is mandatory. When running PHP on IBM i, you can set this parameter to an empty string, to use the default user configured in PHP. When option I5_OPTIONS_SSO is set, user and password parameters are not used.
password	Password for the username.
options	Connection options in an associative array. See below details about connection options.
	*Option*	Description
	I5_OPTIONS_SSO	Single Sign On. Connection is established using the user id signed on the end user station. Kerberos and EIM are used by Easycom to process identification. This option can only be used with PHP on IBM i. This option is not available with the free version of i5-Toolkit.
	I5_OPTIONS_JOBNAME	Set the name of the new job in EASYCOM subsystem. Default is local machine name (The web server).
	I5_OPTIONS_SQLNAMING	Set the naming convention in SQL. Statement to separate library and file names. "SYS" (default) to use slashes (/). "SQL" to use dots (.).
	I5_OPTIONS_DECIMALPOINT	Set the character value to use as decimal point. Default is point (.).
	I5_OPTIONS_LOCALCP	Set the local code page used by PHP application. See comments bellow about Character Set & Code page.
	I5_OPTIONS_CODEPAGEFILE	Change the character conversion rules by using an external conversion table.
	I5_OPTIONS_RMTCCSID	Set the EBCDIC CCSID to use for data conversion. If Easycom client job on the i5 doesn’t have a CCSID, and if its default CCSID is not appropriated, the application can choose the right EBCDIC CCSID.
	I5_OPTIONS_EACUNLOCK	Password to unlock EASYCOM server, by calling EACP003 exit program.
	I5_OPTIONS_ALIAS	Alias name given to the connection. This option has an effect only on when PHP server is running on Windows, in multi thread configuration. If a connection having same username, password and alias is already active, it is reused.
	I5_OPTIONS_INITLIBL	Specifies library names to add on top of library list.
	I5_OPTIONS_IDLE_TIMEOUT	Used on i5_pconnect() only. Set the delay (seconds) after what a persistent connection is closed if it not reused by a script. Default is infinite.
	I5_OPTIONS_PRIVATE_CONNECTION	Used on i5_pconnect() only. Set the ID of the persistent connection to reuse.
	I5_OPTIONS_AUTOMATIC_NEXT_RESULT	String value. If this option is not set to "1", you will have to call i5_next_result() before to fetch from the first result set resulting from a CALL SQL statement. For compatibility with previous Easycom versions, the first i5_fetch_xxx() fetches the parameters values, if this option is not set to "1".
	I5_OPTIONS_SSL_MODE	Windows and Linux only! I5_OPTIONS_SSL_TRUE/ I5_OPTIONS_SSL_FALSE/ I5_OPTIONS_SSL_MANDATORY Forces SSL mode. If true, the SSL connection will be attempted, and if SSL cannot be used, a non-secure connection will be attempted. If mandatory, SSL connection will be attempted, and if SSL cannot be used, connection is aborted.
	I5_OPTIONS_SSL_INTF	I5_SSL_INTERFACE_WINDOWS / I5_SSL_INTERFACE_OPENSSL SSL interface to use.
	I5_OPTIONS_SSL_CAFILE	In OpenSSL, the CA file to verify server certificate.
	I5_OPTIONS_SSL_USER_CERT_FILE	In OpenSSL, the CA path in which searching for authority certificates. This is to verify the server certificate.
	I5_OPTIONS_SSL_USER_CERT_FILE	Client certificate file. This is for client certificate authentication when OpenSSL is used. The certificate file must be in PEM format. When using Windows interface, the option is not needed: the certificate is automatically selected.
	I5_OPTIONS_SSL_USER_CERT_PKEY_FILE	Client certificate private key file. This is the file path for the OpenSSL private key file. When using Windows interface, the option is not needed: the certificate and private key is automatically selected.
	I5_OPTIONS_SSL_USER_CERT_PASSPHRASE	Passphrase to be able to read the private key file. This is used in OpenSSL only.

Return

AS/400 connection resource or false on failure.

The connection resource will be given on input to subsequent function calls.

If only one connection is open by the script, the connection resource is optional on subsequent function calls.

Error returned

I5_ERR_MEMALLOC	3			Not enough memory
I5_ERR_PHP_OPTIONSTYPE	259			The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_TYPEPARAM	262			Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_NBPARAM_BAD	263			Wrong parameter count
I5_ERR_PHP_PRIVATE_CONNECTION_NOT_FOUND		285	the -1 connection has not been found.
I5_ERR_PHP_LOCALHOST_NOT_PERMIT	286			you must specify the AS/400 address

Details

This function acts like i5_connect(), except for the following differences :

- If a connection to the same AS/400 server, same user profile and password, already exists within the current web server process, and if it is available, it will be reused.

- If such a connection doesn’t exist, a new one is created, and kept opened when the PHP script ends.

- A subsequent call to i5_close() will not close the connection.
Use i5_pclose() to definitely close the connection.

- A time out can be set with option I5_OPTIONS_IDLE_TIMEOUT.
If the connection isn’t reused during that delay, it will be automatically closed.

- A PHP application can manage session affinity by creating private jobs for a session.

Note:

When a PHP script connects to a private i5 job, it gets a connection that will not be reused by any other PHP session.
The job environment is maintained along the PHP session. For example, if a script creates a file in QTEMP library, this file will be present for subsequent scripts in the same session.
Resources and cursors are not maintained!

I5_pconnect() uses same option as i5_connect().
Following special options apply only to i5_pconnect().

I5_OPTIONS_PRIVATE_CONNECTION:

Using this option, all the PHP scripts inside the same PHP session, can use the same i5 job along the session.

First time this function is called in the session, set value 0 to this option to create a new connection.
Then, call function i5_get_property() to get the connection ID. Store this connection in a session variable.

When i5_pconnect() is called in a next script, set i5_OPTIONS_PRIVATE_SESSION option to the connection ID value. Easycom will connect to the same i5 job.

I5_OPTIONS_IDLE_TIMEOUT:

Set the maximum delay (in seconds) the i5 job will remain active without any request from PHP. If the PHP session ends without running i5_pclose(), the job will end after this delay.

Example

Example 1: Connecting to a private job.

session_start();

$conId = 0;

if (isset($_SESSION['connectionID'])) {

$conId = $_SESSION['connectionID'];

echo "Connection ID is $conId ";

} else {

echo "No connection ID stored. ";

}

// I5_OPTIONS_PRIVATE_CONNECTION connection is private for the session

// I5_OPTIONS_IDLE_TIMEOUT After a delay with no activity, the job will end.

$option = array(

I5_OPTIONS_PRIVATE_CONNECTION => $conId,

I5_OPTIONS_IDLE_TIMEOUT=>"60",

I5_OPTIONS_JOBNAME=>"PHP_PCON"

);

$retcon = i5_pconnect('193.104.118.120', 'qpgmr', 'password', $option );

if (is_bool($retcon) && $retcon == FALSE) {

$errorTab = i5_error();

if ($errorTab['cat'] == 9 && $errorTab['num'] == I5_ERR_PHP_PRIVATE_CONNECTION_NOT_FOUND) {

echo "Connection ID no longer active ";

$_SESSION['connectionID'] = 0;

} else

print_r($errorTab);

} else {

if ($conId == 0) {

//Session variable was 0: Get connection ID and store it in session variable.

$ret = i5_get_property(I5_PRIVATE_CONNECTION, $retcon);

if (is_bool($ret) && $ret == FALSE) {

$errorTab = i5_error();

print_r($errorTab);

} else {

// Connection ID is stored in session variable

$_SESSION['connectionID'] = $ret;

}

if ($conId > 0){

i5_pclose($retcon);

$_SESSION['connectionID'] = 0;

} else {

i5_close($retcon);

}

Example 2: Basic persistent connection.

$conn = i5_pconnect("193.104.118.120", "QPGMR", "PASSWORD");

if (!$conn) {

$error = i5_error();

echo " Error during connection ";

echo " Error number: ".$error["num"];

echo " Error category: ".$error["cat"];

echo " Error message: ".$error["msg"];

echo " Error description: ".$error["desc"];

trigger_error("I5 connection fails", E_USER_ERROR);

} else {

echo " Connection OK ";

$isnew = i5_get_property(I5_NEW_CONNECTION, $conn);

if ($isnew) {

echo " New connection. Do some job initialization ";

/* leaves connection without closing it. */

/* Make it available for another script. */

$ret = i5_close($conn);

if (!$ret) trigger_error("i5_pclose error : ".i5_errormsg(), E_USER_ERROR);

} else {

$ret = i5_pclose($conn);

if (!$ret) trigger_error("i5_pclose error : ".i5_errormsg(), E_USER_ERROR);

}

echo " I5 disconnected ";

See also

i5_private_connect
i5_connect
i5_close

i5_pclose

i5_get_property

i5_set_property