easycom for php - aura equipements easycom...

Easycom For PHP

Introduction to Easycom For PHP

Easycom For PHP is the foundation of the original PHP Toolkit for IBM i, embedded in Zend Core and Zend Server for IBM i.

Easycom For PHP allows user to get to IBM i - AS400 data and programs from PHP applications. It features a set of functions giving access to databases and IBM i resources in native and SQL mode. It enables programs and ILE procedures calling (RPG, COBOL, CL, ...). PHP applications can access all the OS/400 objects: Data areas, data queues, spools, …

The i5 Toolkit (Easycom for PHP) is available for Windows, IBM i and Linux PHP servers.

Contact Aura Equipments for details.

Easycom For PHP is based on Easycom technology from AURA Equipments. It is an add-in, dynamically loaded by PHP; It doesn’t need any compilation.

It is available for Windows, Linux and IBM i. It allows to develop WEB applications on all Web servers supporting PHP 5th version and higher.

With Easycom For PHP , you get a set of API functions. The first function your application has to call, is i5_connect(), i5_pconnect(), or i5_private_connect().

AURA Equipments provides a large range of connectors to AS/400 – IBM I, for various languages and developments tools:

.Net,

Delphi,

Java,

WinDev,

WebDev,

Basic C / C++,

…

http://www.easycom-aura.com/

http://www.easycom-aura.com/

Configuration required

Server (I5)

All I5 models from B series

ll I5/OS versions from version V4R5

Communication TCP/IP

Client (web server)

Windows , Linux , or i5/OS web server

Protocol TCP/IP

Software's

Web server: Apache, IIS …

PHP 5.2 to 5.5

A QSECOFR profile type is required to setup the server add-in.

Administrator rights are required to activate client side of Single Sign On.

Easycom For PHP setup

Easycom Server

Easycom Server was installed on your IBM i. Its default library name is EASYCOM. EASYCOM sub-system must be running. EASYCOMD job is running in EASYCOM sub-system. EASYCOM subsystem must be started at IPL. Check you “starup” procedure.

PHP on IBM i

Easycom PHP extensions are present in directory: /usr/local/Easycom/php_extensions

Each subdirectory contains PHP extensions for each PHP version on IBM i:

5.2, for PHP 5.2

5.3, for PHP 5.3

5.4, for PHP 5.4

5.5, for PHP 5.5 Subdirectories contain Easycom extensions:

I5comm.so, main Easycom extension

Pdo_easycom.so, the PDO driver for Easycom. If ZEND Server 5, or Zend Server 6 was installed on your system when Easycom was installed, then Easycom PHP extensions were also copied to the apprpriate “php-extensions” subdirectory for Zend Server Example, for Zend Server 6:

/usr/local/zendsvr6/lib/php_extensions

Configuration file “php.ini” was also updated to add Easycom extension to PHP instances. Exemple, for Zend Server 6, configuration file is:

/usr/local/zendsvr6/etc/php.ini

Following entries were inserted:

extension = i5comm.so

[PHP_EASYCOM]

extension = pdo_easycom.so

On PHP For i5/OS.

If you installed ZEND Core for i5/OS, Easycom server is already installed.

Otherwise, the standards Easycom For PHP installation procedure will use FTP to upload Easycom Server to a single library on your System I – AS/400.

Default name for the Easycom library is "EASYCOM".

Easycom For PHP installation procedure is a Windows executable file. On Windows platform.

Run the installation procedure on the Windows web server, to install the server part of Easycom on the AS/400, and the client part.

The client part of Easycom for PHP is installed in: "Program Files\EasycomPHP" directory.

Some components are also installed in Windows system directory, and PHP directory.

EAC32VBA.DLL

EASYCO32.DLL

PHP Extensions directory.

Sub drirectory "EasycomDLL"

php_Easycom5_2_0V3.dll

php_Easycom5_1_0V3.dll

Easycom extension is added to the PHP configuration file php.ini usually located in Windows directory with the following line:

extension= EasycomDLL\php_Easycom5_2_0V3.dll

(DLL must matches with the PHP version number)

Extension_dir option may be also modified so that a PHP can find the Easycom for PHP DLL.

Extension_dir="C:\Program Files\PHP\extensions\"

On Linux platform.

Uncompress the tgz file on your Linux system.

The new sub-directory "EasycomForPHP". You get contains 4 libraries:

libI5comm5_1_0.so For PHP 5.1 32 Bits




Copy the right library to the PHP extensions directory. You can find this directory path in "php.ini" file, entry "Extension_dir="

Update "php.ini" file, by adding an entry "extension=" to the right library.

Example:

extension= libI5comm5_2_064.so

Reminder: PHP must be correctly linked to the web server (Apache 1.3 typical). Refer to the PHP doc. for procedure.

Add Easycom for PHP to Eclipse

To get automatic completion for Easycom for PHP functions in Eclipse source editor, you have to add a user library including Easycom For PHP functions definitions.

Follow these steps :

Go to Preferences dialog box in Eclipse menu.

Expand PHP and select "PHP Librairies".

Click on "New" button and enter a library name (ex Easycom For PHP).

Click on "Add External folder" button and select "Eclipse" directory in the install directory of Easycom For PHP ("C:\Program Files\EasycomPHP" by default ).

Validate Preferences box.

The user library "Easycom For PHP" is now available for all projets in your current workspace. If you change workspace you have to update "Preferences" for it too.

To add this new user library in your project, display the property box of your project and follow these steps :

Select "PHP Include Path"

Click on "Add Library" button"

Do next

Select "Easycom For PHP"

Click finish

Validate the Properties project box

Now you should have completion in for your PHP source files.

Activation key

You have to activate Easycom For PHP, before to use it with your System i.

You have received an activation code from AURA Equipments.

On an I5 station, type the following commands:

CHGCURLIB EASYCOM

EASYREG <F4>

Fill up the form, with the data as they appear on the document you received from AURA Equipements.

License . . . . . . . . . . . . PHP

Special Development License *NO

Company name . . . . . . . . . . Company name, as printed on the document

you received

Activation Key . . . . . . . . . Your key. Caution (O, 0, I, 1)

Connections number . . . . . According to license

Authorized partition ID (1->n)

EASYCOM'S Version . . . . . . . 3

EASYCOM'S Options . . . . . . .

Expiration date (ddmmyyyy) . . . 00000000

(or expiration date for evaluation)

Authorized Proc. group

Extended Licence *NONE

Warning: Make sure that O (letter) differs from 0 (figure) same for I (letter) from 1 (figure).

Before entering key(s), it's safe to close EASYCOM connections.

How to check that Easycom For PHP is correctly installed and

configured?

First of all, run the connection test "Easycom Configuration". From a Windows station.

If the connection is settled, the following data's will be returned to you:

I5 serial number,

Model,

Server version.

In other case, check TCP/IP (ping) connection and see if Easycom subsystem is running.

Then you know that server part is operating (see: Connection and activation).

Start the web server so that Easycom extension is loaded.

If an error occurs see "Web Server launching error messages".

If no error occurs check a PHP script with Easycom functions, open a connection, a file…

Web server launching error message

If the following message appears when launching Web server:

PHP Warning: Easycom: Unable to initialize module

Module compiled with debug=0, thread-safety=0 module API=20000441

PHP compiled with debug=0, thread-safety=1 module API=20001214

It means that you are not using a compatible Easycom DLL for the PHP. File PHP.INI needs to be modified entering the right file.

As an example: If you are using PHP 4.3.3, you must specified php_easycom4_2_1V2FR.DLL. This DLL being compatible with all PHP >=4.2.1 and < 4.4.0

See: Easycom For PHP installation

MySQL / ODBC / Easycom comparative table

Easycom For PHP v1

Easycom For PHP v2 MySQL ODBC Easycom For PHP v3

Connection management

easycom_connect

easycom_connect2

easycom_close

i5_connect

i5_close

i5_adopt_authority

mysql_connect

mysql_pconnect

mysql_close

mysql_change_user

odbc_connect

odbc_pconnect

odbc_close

odbc_close_all

i5_connect

i5_close

i5_adopt_authority

Errors management

easycom_err i5_error

i5_errno

i5_errormsg

i5_start_testfile

mysql_error

mysql_errno

odbc_error

odbc_errormsg

i5_error

i5_errno

i5_errormsg

i5_start_testfile

Parameterized Requests

easycom_query

easycom_free_query

i5_query

i5_free_query

mysql_query

odbc_do / odbc_exec

i5_query

i5_free_query

easycom_prepare

easycom_execute

i5_prepare

i5_execute

i5_setparam

i5_getparam

i5_bind_param

i5_bind_result

i5_next_result

odbc_prepare

odbc_execute

odbc_next_result

i5_prepare

i5_execute

i5_setparam

i5_getparam

i5_bind_param

i5_bind_result

i5_next_result

SQL

easycom_query

easycom_free_query

i5_query

i5_free_query

mysql_query

odbc_do / odbc_exec

i5_query

i5_free_query

Native access

easycom_openFile

easycom_edit

easycom_cancel_edit

easycom_add_new

easycom_update

easycom_delete

easycom_put_field

easycom_put_key_value

easycom_definelink

i5_open

i5_edit

i5_cancel_edit

i5_addnew

i5_update

i5_delete

i5_setvalue

i5_seek

i5_range_from

i5_range_to

i5_range_clear

i5_open

i5_edit

i5_cancel_edit

i5_addnew

i5_update

i5_delete

i5_setvalue

i5_seek

i5_range_from

i5_range_to

i5_range_clear

easycom_free_file

i5_data_seek

i5_num_rows

i5_bookmark

i5_link

i5_nolink

i5_free_file

i5_paramdesc

i5_new_record

i5_update_record

i5_delete_record

mysql_data_seek

mysql_num_rows

mysql_free_result

odbc_cursor

odbc_free_result

i5_data_seek

i5_num_rows

i5_bookmark

i5_link

i5_nolink

i5_free_file

i5_paramdesc

i5_new_record

i5_update_record

i5_delete_record

Reading and informations

easycom_field_info

easycom_num_fields

i5_info

i5_num_fields

mysql_fetch_field

mysql_num_fields

odbc_field_num

i5_info

i5_num_fields

i5_list_fields

i5_field_scale

i5_field_len

i5_field_name

i5_field_type

i5_fetch_array

i5_fetch_assoc

mysql_list_fields

mysql_field_flags

mysql_field_len

mysql_field_name

mysql_field_type

mysql_fetch_array

odbc_columns

odbc_columnsprivileges

odbc_field_precision

odbc_field_scale

odbc_field_precision

odbc_field_len

odbc_field_name

odbc_field_type

odbc_fetch_array

i5_list_fields

i5_field_scale

i5_field_len

i5_field_name

i5_field_type

i5_fetch_array

i5_fetch_assoc

easycom_fetch_object

easycom_fetch_row

i5_fetch_object

i5_fetch_row

i5_affected_rows

i5_setblob

i5_getblob

i5_get_keys

mysql_fetch_assoc

mysql_field_seek

mysql_fetch_object

mysql_fetch_row

mysql_affected_rows

odbc_fetch_into

odbc_fetch_object

odbc_fetch_object

odbc_fetch_row

i5_fetch_object

i5_fetch_row

i5_affected_rows

i5_setblob

i5_getblob

i5_get_keys

i5_result

mysql_result

odbc_result_all (html)

odbc_result

i5_result

Commands

easycom_command

easycom_commandGetVar

easycom_remote_command

i5_cmd

i5_cmdget

i5_remotecmd

i5_command

i5_get_system_value

i5_cmd

i5_cmdget

i5_remotecmd

i5_command

i5_get_system_value

Transactions

easycom_transaction

easycom_rollback

easycom_commit

i5_transaction

i5_rollback

i5_commit

odbc_autocommit

odbc_rollback

odbc_commit

i5_transaction

i5_rollback

i5_commit

Program Calls

i5_program_prepare

i5_program_prepare_PCML

i5_program_call

i5_program_close

System Values

I5_get_system_value

Data Areas

i5_data_area_create

i5_data_area_read

i5_data_area_write

i5_data_area_delete

Data Queues

i5_dtaq_prepare

i5_dtaq_receive

i5_dtaq_send

i5_dtaq_close

Object Listing

i5_objects_list

i5_objects_list_read

i5_objects_list_close

Spooled File

i5_spool_list

i5_spool_list_read

i5_spool_list_close

i5_spool_get_data

Job Log List

i5_jobLog_List

i5_jobLog_List_read

i5_jobLog_List_close

Active Job List

i5_job_list

i5_job_list_read

i5_job_list_close

User Spaces

i5_userspace_prepare

i5_userspace_put

i5_userspace_get

i5_userspace_create

PHP DATA DESCRIPTION Data structures are defined via PHP as follows: Main data is the array of values, having the following fields: • Name - name of the field • Type - type of the field, can be:

I5_TYPE_CHAR I5_TYPE_INT I5_TYPE_PACKED I5_TYPE_ZONED I5_TYPE_FLOAT I5_TYPE_BYTE I5_TYPE_STRUCT

• Length - for CHAR, BYTE - integer describing length. Length can be number or name of the variable holding the length in the data structure. - for PACKED, ZONED - string "NUMBER.NUMBER" defining length and precision - for STRUCT - array containing data definition of the structure - for INT, FLOAT – ignored

• IO

- I5_IN - I5_OUT - I5_INOUT ( = I5_IN | I5_OUT) - default is input, these values can be OR'ed together to get input-output value

• Count (optional) - repetition count if the field is an array • CountRef (optional) - reference to the repetition count if the field is an array Data structure is defined via PHP as follows: • DSName - name of the parameter • DSParm (optional) - array of the parameter of the Data structure. Each parameter is defined by a simple data definition.

Example

/*Call a program passing a DS as parameter */

$description = array ( array ("Name"=>"P1", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>10,

"Count"=>5), array ("Name"=>"P2C", "IO"=>I5_INOUT,"Type"=>I5_TYPE_LONG, "Length"=>4), array ("Name"=>"P2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>1,

"CountRef"=>"P2C" ), array ("DSName"=>"PS", "Count"=>2, "DSParm"=>array ( array ("Name"=>"PS1", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>10), array ("Name"=>"PS2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>10), array ("Name"=>"PS3", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>10) ) ) ); $hdlPgm = i5_program_prepare("EASYCOM/RPCTEST", $description); $Psparameter = array( array("PS1"=>"test1", "PS2"=>"test2", "PS3"=>"test3"), array("PS1"=>"test3", "PS2"=>"test4", "PS3"=>"test5") ); $parameter2 = Array( "P1"=>array("t1", "t2", "t3", "t4", "t5"), "P2C"=>2, "P2"=>array("a", "b"), "PS"=>$Psparameter); $parmOut2 = array("P1"=>"P1", "PS"=>"PS"); $ret = i5_program_call($hdlPgm, $parameter2, $parmOut2); if (!$ret){

print_r(i5_error()); trigger_error("i5_execute error : ".i5_errormsg(), E_USER_ERROR); } echo "P1 : $P1 ";

echo "PS: ";print_r($PS);echo " ";

API Functions

Introduction to Easycom API functions

All Easycom for PHP API function names have prefix i5_ (for i5/OS). Functions are available on Windows, linux and IBM i platforms. Easycom for PHP provides a set of API functions to access IBM I resources:

Native program call.

Native procedure call (Service Programs)

Native record level access to database files

System API Calls

SQL database access

System commands

Data Queues Access

User space Access

Data Area

…

Connection

i5_connect

Open a new connection to the IBM i - AS/400 server.

resource i5_connect ( string server, string user,

string password [, array options] )

Parameters

server Name of the IBM i server to connect to, Can be either a DNS name, an IP address, or special keyword I5_SAME_JOB.

New ! 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 cretated on the system. This option is not available with the i5-Toolkit free version.

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. This default port connects to the default standalone Easycom server, running in EASYCOM subsystem on the targer system.

For Zend Server or Zend Core, default port is 6079. This value is configured un php.ini file, section [zend], entry "i5comm.Port=6079". It connects to the Easycom server running in Zend subsystem.

To change port to connect to, add the port number at the end the server name or address, separated by a colon: Exemple: I5SERVER:6079

user User name to use for connection. When your PHP server is running on Windows or Linux, User name 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 user name.

options Connection options in an associative array.

See below details about connection options.

Option Description

I5_OPTIONS_SSO New ! 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 attempred.

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

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.

Returns: 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_LOCALHOST_NOT_PERMIT 286 you must specify the AS/400 address

Details

Open a connection with specified AS400 server (name or IP address) for a given user profile and password.

This function must be called first, before any subsequent function is called. A new job is created in EASYCOM subsystem, except when I5_SAME_JOB is set for server parameter.

The connection will be closed at the end of the script, except when running PHP server on Windows, with a multi threaded web server. To keep the connection open at the end of the script, use i5_pconnect(), or i5_private_connect()

Note: It is recommend to configure EASYCOM subsystem with PRESTART JOBS for a quick connections opening.

Note: Running Easycom For PHP on Windows, in multi thread configuration.

In a multi thread environment, the PHP application can follow up the web session.

Connections can be kept open within the web session, with files and queries. So, Easycom connections are not automatically closed at the end of each script.

This feature is available only on Windows PHP servers.

Character Set & Code page - I5_OPTIONS_LOCALC, I5_OPTIONS_RMTCCSID :

I5_OPTONS_LOCALCP option sets the local code page to use on the PHP server. This is an ASCII character set. All EBCDIC i5 data will be converted to and from this code page.

If local code page to use is not UTF-8, option is set to a single CCSID value, or a character encoding.

Example:

I5_OPTIONS_LOCALCP=>"ISO8859-8"

I5_OPTIONS_LOCALCP=>"916"

In this case, any ASCII CCSID can be used.

Only character encoding supported by PASE or Linux can be used. See CCSID & character encoding table bellow.

If local code page is UTF-8, option contains an intermediate code page, prefixed by "UTF-8;"

Example:

I5_OPTIONS_LOCALCP=>"UTF-8;ISO8859-1"

Easycom will convert to and from UTF-8 in two steps.

UTF-8 Intermediate code page EBCDIC

In this case, the CCSID or character encoding given for the intermediate code page must be present in the table bellow.

CCSID & Character encoding table :

ALL character encoding are not supported by PASE or Linux.

CCSID Character Encoding

1046 1124 1126 1252 850 856 921 922 932 943 819 912 913

IBM-1046 IBM-1124 IBM-1129 IBM-1252 IBM-850 IBM-856 IBM-921 IBM-922 IBM-932 IBM-943 ISO8859-1 ISO8859-2 ISO8859-3

914 915 1089 813 916 920 923

ISO8859-4 ISO8859-5 ISO8859-6 ISO8859-7 SO8859-8 ISO8859-9 ISO8859-15

Example

/* Basic connection to AS400 */

$conn = i5_connect("193.104.118.120", "QPGMR", "PASSW") or die(i5_errormsg());

echo " Connection OK ";

/* Connection to AS400 setting options */

$conProperty = array(I5_OPTIONS_JOBNAME=>"PHPJOB", I5_OPTIONS_INITLIBL=>"WEBLIB")

;

$conn = i5_connect("MYAS400", "QPGMR", "PASSW",$conProperty) or die(i5_errormsg()

);


/* Connection error detail in case of failure */

$conn = i5_connect("193.104.118.120", "QPGMR", "PASSW");

if (!$conn) {

$error = i5_error();

echo " Error during connection\n";

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

}

/* Disconnect from AS/400 */

$ret = i5_close($conn);

If ($ret){

echo " I5 disconnected ";

} else {

$ret = i5_errormsg($conn);

}

/* SSL connection with user certificate and OpenSSL interface */

$option = array();

$option[I5_OPTIONS_JOBNAME] = "PHP_JOB";

$option[I5_OPTIONS_SSL_MODE] = I5_OPTIONS_SSL_TRUE;

$option[I5_OPTIONS_SSL_INTF] = I5_SSL_INTERFACE_OPENSSL;

$option[I5_OPTIONS_SSL_CAFILE] = 'C:\Temp\OpenSSL\P520CA.crt';

$option[I5_OPTIONS_SSL_USER_CERT_FILE] = 'C:\Temp\OpenSSL\qpgmr.pem';

$option[I5_OPTIONS_SSL_USER_CERT_PKEY_FILE] = 'C:\Temp\OpenSSL\qpgmr_p.key';

$option[I5_OPTIONS_SSL_USER_CERT_PASSPHRASE] = 'PASSW_PRIVATE';

$conn = i5_connect("193.104.118.120", "QPGMR", "PASSW", $option);

if (!$conn) {








} else {


}

See also

i5_pconnect i5_private_connect i5_close i5_adopt_authority

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 to connect to, 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 cretated on the system. This option is not available with the i5-Toolkit free version.


When running PHP on Windows or Linux, server name or address is mandatory. Default port is 6077. This default port connects to the default standalone Easycom server, running in EASYCOM subsystem on the targer system.

For Zend Server or Zend Core, default port is 6079. This value is configured un php.ini file, section [zend], entry "i5comm.Port=6079". It connects to the Easycom server running in Zend subsystem.

To change port to connect to, add the port number at the end the server name or address, separated by a colon: Exemple: I5SERVER:6079

user User name to use for connection. When your PHP server is running on Windows or Linux, User name 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 user name.



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.














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_INITLIBL specifies library names to add on top of library

list.











Forces SSL mode.





I5_OPTIONS_SSL_CAFILE In OpenSSL, the CA file to verify server

certificate.







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_PHP_PRIVATE_CONNECTION_NOT_FOUND 285 the -1 connection has not been found.


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

Private connections, or, Connection affinity:

When a PHP script connect 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 varaible 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) {


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) {


echo " Error during connection ";






} else {


$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. */


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

} else {

$ret = i5_pclose($conn);


}

}

echo " I5 disconnected ";

See also

i5_private_connect i5_connect i5_close

i5_pclose

i5_get_property

i5_set_property

i5_private_connect

Create or get a private persistent connection to an AS/400 server. This function acts like i5_pconnect with I5_OPTIONS_PRIVATE_CONNECTION option. except that the connection ID is automatically managed by the function.

resource i5_private_connect (string server,

string user,

string password

[, array options] )

Parameters

server Name of the IBM i server to connect to, Can be either a DNS name or an IP address.

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 cretated on the system.


When running PHP on Windows or Linux, server name or address is mandatory.

Default port is 6077. This default port connects to the default standalone Easycom server, running in EASYCOM subsystem on the targer system.

To change port to connect to, add the port number after the server name or address, separated by a colon:

Exemple: I5SERVER:6079

user User name to use for connection.

When your PHP server is running on Windows or Linux, User name 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

Pass word Password for the username



Option Description














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_INITLIBL specifies library names to add on top of library list.











Forces SSL mode.





I5_OPTIONS_SSL_CAFILE In OpenSSL, the CA file to verify server certificate.







I5_OPTIONS_SSL_USER_CERT_PASSPHRASE Passphrase to be able to read the private key file.

This is used in OpenSSL only.

Returns: True if OK, false if failed.


I5_ERR_PHP_HDLCONN 257 This resource has no connection active.

I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.


I5_ERR_PGM_DONT_EXIST 530 Internal error; please contact Aura Equipement; error number 530

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 PHP session, it will be reused.

- If such a connection doesn’t exist, a new one is created, kept open when the PHP script ends, and dedicated to the current PHP session.

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

- Easycom manages session affinity by creating private jobs for the PHP session. All the PHP scripts inside the same PHP session, use the same AS/400 job along the session.

Call function i5_get_property(), with option I5_NEW_CONNECTION , to know if the returned connection is a new one, or not.

Private connections, or, Connection affinity:

When a PHP script connect 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_private_connect() uses same option as i5_pconnect(). Following special options apply only to i5_pconnect() and i5_private_connect().

I5_OPTIONS_IDLE_TIMEOUT:

Set the maximum delay (in seconds) the AS/400 job will remain active without any request from PHP. Default delay is 900 seconds. If the PHP session ends without running i5_pclose(), the job will end after this delay.

I5_OPTIONS_PRIVATE_CONNECTION:

Setting value 0 to this option will force Easycom to create a new private connection, even if one already exist.

Example

Example 1: Connecting to a private job.

<?php

session_start();

$action = 'noAction';

if (isset($_GET['typeAction'])){

$action = $_GET['typeAction'];

}

?>

<html>

<head>

<title>Easycom For php</title>

<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

</head>

Action : <?php echo $action ?>

<body bgcolor="#FFFFFF" >

Sample

<?php

$option = array();

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

$option[I5_OPTIONS_IDLE_TIMEOUT] = "50";

$retcon = i5_private_connect($connect, $user, $pass, $option);

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

print_r($errorTab);

} else {

$isnew = i5_get_property(I5_NEW_CONNECTION, $retcon);

if ($isnew) {

/* New connection. Do some job initialization */;

} else {

/* Connection was already existing. Using the same job */;

}

}

if ($action == 'pclose'){

$ret = i5_pclose();

echo "Connection definitely closed ";

}

?>

<div style="border:solid">

Close definitely the connection :.

<form action="privateConnectId.php" method="get">

<input name="typeAction" type="hidden" value="pclose">

<input name="validate" type="submit" value="Close Connection">

</form>

</div>

 

<div style="border:solid">

Continue with the same connection :.

<form action="privateConnectId.php" method="get">

<input name="typeAction" type="hidden" value="noAction">

<input name="validate" type="submit" value="Re Use">

</form>

</div>

</body>

</html>

See also

i5_close

i5_pclose

i5_get_property

i5_set_property

i5_pconnect

i5_set_property

Change an Easycom server property.

bool i5_set_property ( int Property, int / string Value

[resource connection] )

Parameters

Property Symbolic value of the property to change.

Property Description

I5_CURSOR_SENSITIVITY Change SQL cursor sensitivity. Valid values are :

0 = I5_SQL_UNSPECIFIED – Cursors on the statement handle might make visible none, some, or all such changes depending on the cursor type. This is the default.

1 = I5_SQL_INSENSITIVE – All valid cursors on the statement handle show the result set

without reflecting any changes made to it by any other cursor.

2 = I5_SQL_SENSITIVE – All valid cursors on

the statement handle make visible all changes made to a result by another cursor.

Value New value to set to the property.

connection Connection resource - result from i5_connect() or i5_pconnect()


Error returned

I5_ERR_DESC_WRONG_DATAOP 41 Wrong operation on a data field of a description

I5_ERR_PARSEXML 42 Internal error; please contact Aura Equipement; error number 42




I5_ERR_PHP_DESC_EMPTY 310 The description array is empty.

Details

I5_CURSOR_SENSITIVITY is changed for the next queries, until the next change of the property value. It doesn’t affect the properties for already open queries.

Example

i5_set_property(I5_CURSOR_SENSITIVITY, 1);

/* Next request is open with insensitive cursor */

$query = i5_query("SELECT * FROM EASYCOM/SP_CUST");

if (is_bool($query)){

trigger_error("i5_query error : ".i5_errormsg(), E_USER_ERROR);

}

See also

i5_pclose i5_connect i5_pconnect

i5_get_property

Get an Easycom server property value.

int / string i5_get_property ( int Property,

resource connection )

Parameters

Property Symbolic value of the property to get value of.

Property Description

I5_NEW_CONNECTION This property has sense only when connection was open by

i5_pconnect(),

Return values are :

0 : The connection was already open by a previous call to i5_pconnect() in a previous script.

1 : This is a new connection never used before by another PHP script.

I5_PRIVATE_CONNECTION This property has sense only when connection was open by

i5_pconnect(),

Return value is the connection ID you have to store in a session variable, and set to option I5_OPTIONS_PRIVATE_CONNECTION on a next i5_pconnect() call.


Returns: Property value.

Error returned






Details

Example


if (!$conn) {








} else {



if ($isnew) {






} else {



}

}


See also

i5_pconnect

i5_close

Closes connection to AS/400 server.

bool i5_close ([resource connection] )

Parameters



Error returned

I5_ERR_PHP_HDLDFT 256 No default connection found.


I5_ERR_PHP_RESOURCE_BAD 261 No resource found .



Details

Closes the connection associated with the specified resource or the last opened connection.

If the connection was opened with i5_pconnect(), the connection will not be totally closed. Use i5_pclose() to physically close it.

i5_close() is automatically executed at the end of PHP script.

Example

/* Connection error detail in case of failure */

$conn = i5_connect("193.104.118.120", "QPGMR", "PASSW");

if (!$conn) {








} else {


}

/* Disconnect from AS/400 */


If ($ret){

echo " I5 disconnected ";

} else {

$ret = i5_errormsg($conn);

}

See also

i5_pclose i5_connect i5_pconnect

i5_pclose

Closes a persistant connection to AS/400 server.

bool i5_pclose ([resource connection] )

Parameters








Details

Closes the connection associated with the specified resource or the last opened connection.

Connection is physically closed. See i5_close() to keep connection open by i5_pconnect()

Example


if (!$conn) {








} else {



if ($isnew) {






} else {



}

}


See also

i5_close i5_connect i5_pconnect

i5_adopt_authority

Changes authority of the connection to a specific user. All actions will be executed as this user from now on.

bool i5_adopt_authority ( string username,

string password

[, resource connection] )

Parameters

username Name of the user to change to

password

Password for the user

connection Connection resource - result from i5_connect

Returns:

True if OK, false if failed.

Error returned






Details

I5_adopt_authority function adds the authority of a new user to the EASYCOM job associated to the connection.

See IBM documentation for more information on security and authority's management.

Example

$conn = i5_connect("AS_NAME", "PHP", "PASSWORD"); if ($conn) { $res = i5_adopt_authority("QPGMR","PASSWORD", $conn); if (!$res) trigger_error("i5_adopt_authority error : ".i5_errormsg(),

E_USER_ERROR); } else { trigger_error("i5_connect error :".i5_errormsg(), E_USER_ERROR); }

See also

i5_connect

i5_start_testfile

Activates I5 Easycom trace file.

bool i5_start_testfile ( string trace , int level

[, bool TimeStamp


Parameters

trace Trace file name to be created (library/file.member)

level File detail level, 1 to 4

TimeStamp Display each operation time and date

connection Connection ID(optional)

Returns:






Details

This function is for analysis and debug purpose? It activates a trace file on system i.

If the file does not exist it is created, otherwise it is cleared.

Level defines file detail, level 1 displays only mains functions (low level), level 4 is much more detailed.

Time and date in the trace file give precise time of each operation (TRUE or FALSE)

This function is only valuable in a testing or developing context, it reduces heavily machine speed while creating a file witch can be very large.

Example

$res = i5_connect("MY_AS", "USER", "PASSWORD"); if (!is_bool($res)) { $ret = i5_start_testfile("EASYCOM/TRACE", 4);}

i5_transaction

Starts transaction.

bool i5_transaction ( int mode


Parameters

connection Connection ID

mode Easycom constant (see above)

Returns:

TRUE if transaction has started, FALSE in case of error.





Details

Transactions management requires some rules, i.e. files journalization.

Several transaction modes are possible, they define isolation level, that means, if applied, if changes will be visible or not to other users as well as writing access (open in writing or restricted access).

Modes

I5_ISOLEVEL_CHG UR READ UNCOMMITED, READ WRITE

Modified records remain locked.

Modifications are showed.

I5_ISOLEVEL_CS CS READ COMMITED

Read records are locked.


Changes are not showed.

I5_ISOLEVEL_ALL RS REPEATABLE READ

Read records remain locked.


Modifications are not showed.

Options details are out of this documentation purpose, refer to iSeries and DB2 documentation (particularly LCKLVL parameter of STRCMTCTL command).

If a transaction is currently active, an I5_ALLREADYINTRAN error type will be generated.

Example

<?php

$conn = i5_connect("MY_AS", "USER", "PASSWORD");

if ($conn) {

$res = i5_query("SELECT count(*) FROM animals");

$rec = i5_fetch_array($res );

echo $rec[0] . "\n";

/* Transaction beginning */

i5_transaction(I5_ISOLEVEL_NONE, $conn);

/* Operations on ANIMALS table */

i5_query("INSERT INTO animals VALUE 'Cat', 'Mistigri'");


$rec = i5_fetch_array($res);

echo $res[0] . "\n";

/* Transaction and DELETE request validation */

i5_commit($conn);




i5_close($conn);

}

?>

?>

See also

i5_commit

i5_rollback

i5_commit

Validates current transaction.

bool i5_commit ( string comment


Details

Validate current transaction started with i5_transaction function for the specified connection.

A comment will be added in the journal file.

All files involved in a transaction must be journalized.

See column Journals and transactions with I5 files .

Parameters

comment Chain with transaction comment


Returns: TRUE if transaction is valid, FALSE in case of error.







Example


if ($conn) {





i5_transaction(I5_ISOLEVEL_NONE);

/* Lines insertion in ANIMALS */

i5_query("INSERT INTO Animals VALUES ('CAT', 'Misstic', 'F', 3.2)");

i5_query("INSERT INTO Language VALUES ('DOG', 'Hercule', 'M',

4.4)");




/* Transaction and DELETE request validation */ i5_commit($conn);




i5_close($conn);

}

See also

i5_transaction

i5_rollback

i5_rollback

Cancels current transaction.

bool i5_rollback ( [resource connection] )

Details

Cancels all changes made since transaction was started with i5_transaction function.

An I5_NOTINTRAN error will be generated if no transaction was started.

Parameters


Returns:







Example

<?php

$conn = i5_connect("MON_AS", "USER", "PASSWORD");

if ($conn) {





i5_transaction($conn);

/* All ANIMALS lines deletion */

i5_query("DELETE * FROM animals");




/* Cancel DELETE request */ i5_rollback($conn);




i5_close($conn);

} ?>

This will display:

43

0

43

See also

i5_transaction

i5_commit

Program and Procedure calls

i5_XmlBindSrvPgm

This function bind a Service Program to the job.

bool i5_XmlBindSrvPgm ( string Service_Program

[, resource Connection ] )

Details

Service Program is bound to the job. All procedure entry points become accessible for calls from i5_XmlCallProgram function calls.

Parameters

Service_Program Name of service program to bind. Name can be qualified (Library/Name). If library is not specified, *LIBL is the default.

Connection Easycom Connection - Result of i5_connect() or i5_pconnect().

Returns:

True / False.

Example

// Bind SRVPTEST1 service program.

i5_XmlBindSrvPgm ("SRVPTEST1");

// Declare PSPCUST procedure. PSPCUST is an entry point in SRVPTEST1

$SRPG = "DS_CUST E DS extname(SP_CUST:RSP_CUST);

PSPCUST PR;

Result LIKEDS(DS_CUST);

TERM1 5S 0 CONST;";

i5_XmlDefine ("s-rpg", $SRPG);

// Call procedure

$ArrayOut = i5_XmlCallProgram ("PSPCUST", $ArrayIn);

Note

See also

i5_XmlCallProgram i5_XmlDefine i5_XmlLoadDefinition i5_XmlExecRequest

i5_XmlCallProgram

This function calls a program or procedure, exchanging parameter values.

array i5_XmlCallProgram ( string Program_Name

, array Input_Values,

[ , string

Ret_Values_Var_Name ]

[ , resource Connection ])

Details

This function calls a native IBM i program or procedure, whose prototype was previously loaded by a previous call to i5_XmlDefine, or i5_XmlLoadDefinition.

Parameter values on input and output are passed using associative arrays.

Parameters

Program_Name Program or Procedure name. This name must have been previously prototyped from a PCML or RPG source, by a previous call to i5_XmlDefine, or i5_XmlLoadDefinition.

This name is a virtual name. Real program or procedure name is given in the prototype. See Calling Programs or Procedures example.

To call a procedure from a service program, first, you need to bind the service program to the current Easycom job, call function i5_XmlBindSrvPgm.

Input_Values Input values in an associative array.

Ret_Values_Var_Name When a procedure from a servive program is called, it can return a return value, in addition to output parameters. When a return value is present, the variable is created. If return value is a data structure, variable is created as an associative array.


Returns:

If function succeeds, it returns an associative array with output parameter values.

Examples

Calling a a program with no return value. Only output parameters are retrieved.

// Define SAMPLESDS1 procedure prototype

$SRPG = "DS_A DS;

MBR1 10a;

MBR2 10a;

MBR3 8p2;

SampleDS1 PR extpgm(SampleDS1);

PARM1 10a;

PARM2 8p2;

PARM3 likeds(DS_A);";

i5_XmlDefine ("s-rpg", $SRPG);

// Call it!

$ArrayIn = array("PARM1"=>"pararm 1", "PARM2"=>12345,

PARM3"=>array("MBR1"=>"Param 3-1"));

$ArrayOut = i5_XmlCallProgram("SAMPLEDS1", $ArrayIn);

echo 'Param 1='. $ArrayOut['PARM1'].'';

echo 'Param 3, Member 3='. $ArrayOut['PARM3']['MBR3'].'';

Calling a procedure returning a DS.

// Define FSPCUST procedure. Procedure is in SRVPTEST1 service program.

// FSPCUST returns a DS.

$SRPG = "DS_CUST E DS extname(SP_CUST);

FSPCUST PR LIKEDS(DS_CUST);

TERM1 5S 0;";

$XMLStr = i5_XmlDefine ("s-rpg", $SRPG


$ArrayIn = array("TERM1"=>1551);

$ArrayOut = i5_XmlCallProgram ("FSPCUST", $ArrayIn, "RetVal");

echo 'Return Value=';

var_dump($RetVal);

echo '';

See also

i5_XmlBindSrvPgm i5_XmlDefine i5_XmlLoadDefinition i5_XmlExecRequest

i5_XmlDefine

This function loads Procedure or Program definitions from an immediate PCML or simplified RPG source.

bool i5_XmlDefine ( string Source_type

, string Source_String


Details

Data structures, programs and procedures are defined in a character string provided by the PHP script

Program and procedure prototypes are stored in the current Easycom job.

Parameters

Source_Type Type of source provided in the Source String. Possible values are:

PCML: Definition is in PCML format.

S-RPG: Definition is in RPG like syntax..

Source_String Structures and Procedure definitions.

In PCML or S-RPG format


Simplified RPG is like RPG. Statements are ended by a semi colon. There are no column restrictions. Keywords can be anywhere in the line.

/COPY directive can used in S-RPG definitions, to load external RPG source members.

PR keyword is used to declare a procedure. If the procedure maps to a program (*PGM) use standard RPG keyword EXTPGM to point to the real program. If the procedure maps to a procedure in a service program, use keyword EXTPROC to give the real procedure name, if it is different from the name used and defined by PHP.

DS keyword is used to define data structures. EXTNAME keyword can be used to define an external data structure from a physical file description. In that case, special letter E is present before DS keyword.

CONST keyword sets parameter as INPUT only. Example: Define a procedure that maps to a program. Define an external DS.

$SRPG = "DS_CUST E DS extname(SP_CUST:RSP_CUST);

PSPCUST PR EXTPGM('PSPCUSTR');

Result LIKEDS(DS_CUST);

TERM1 5S 0 CONST;";

$XMLStr = i5_XmlDefine ("s-rpg", $SRPG);

...

$ArrayIn = array("TERM1"=>$InputValue);

$ArrayOut = i5_XmlCallProgram ("PSPCUST", $ArrayIn);

Example: Define DS and Procedure. Procedure is in service program – Bind Service program.

$SRPG = "DS_A DS;

MBR1 10a;

MBR2 10a inz('Member 2');

MBR3 8p2;

SampleDS1 PR;

PARM1 10a;

PARM2 8p2;

PARM3 likeds(DS_A);";

$XMLStr = i5_XmlDefine ("s-rpg", $SRPG);


...

$ArrayOut = i5_XmlCallProgram ("SAMPLEDS1", $ArrayIn);

PCML (Program Call Markup Language) is defined by IBM. Refer to IBM documentation for a complete description.

You can make the RPG compiler generate a PCML description of your procedures.

On CRTRPGMOD command, Set option PGMINFO(*PCML) INFOSTMF(IFS file path)

A stream file will be created on the IFS. See i5_XmlLoadDefinition function to load the generated file. Example: Define a procedure using PCML.

$PCML = '<pcml version="1.0">

<program name="QUSLOBJ0200" Path="QUSRTVUS">

<data name="USSPC" type="struct" struct="QNAME" usage="input" />

<data name="START" type="int" length="4" usage="input" />

<data name="DATALEN" type="int" length="4" usage="input" />

<data name="RCVVAR" type="struct" struct="QUSL020002" usage="output"

outputsize="DATALEN" Count="COUNT" />

<data name="COUNT" type="int" length="4" usage="input" Passby="Nothing" />

</program>

</pcml>';

$XMLStr = i5_XmlDefine ("PCML", $PCML);

Returns:

True / False.

See also

i5_XmlBindSrvPgm i5_XmlCallProgram i5_XmlLoadDefinition i5_XmlExecRequest

i5_XmlLoadDefinition

This function loads Procedure or Program definitions from RPG or PCML source files.

bool i5_XmlLoadDefinition ( string Source_type

, string Source_File


Details

Procedure and program definitions are loaded from external files, and stored in the current Easycom job.

Parameters

Source_Type Type of source provided in the source file. Possible values are:

PCML: Definition is in PCML format, stored in an IFS stream file.

RPG: Definition is taken from an RPG ILE source, stored as a file member, or a stream file. If file path has the form "/dir/…/file", then file is a stream file

.

Source_File Path to a stream file, or source file member.


From an RPG source file, only definition statements are used to define procedures (D cards).

Main entry point defined by "*ENTRY PLIST" will be used only if it is at the beginning of the C cards.

Compiler directives such as /COPY, /IF are valid for Easycom. Example: Load Structure and Procedure definitions from RPG source.

$Ret = i5_XmlLoadDefinition ("RPG", 'EASYCOMXMP/QRPGLESRC,CVTNW_H');

$ret = i5_XmlBindSrvPgm ("XMPSRVPGM");

$ArrayIn = array('LIMIT'=>150, 'DECV'=>12345);

$ArrayOut = i5_XmlCallProgram ("FCVTNW", $ArrayIn, "RetVal");

echo 'Return value = '.$RetVal.' ';

Example: Load Structure and Procedure definitions from PCML.

$Ret = i5_XmlLoadDefinition ("PCML",

’/usr/local/easycom/PHP/Samples/QGYOLAUS.pcml');

Returns:

True / False.

See also

i5_XmlBindSrvPgm i5_XmlCallProgram i5_XmlDefine i5_XmlExecRequest

Note

i5_XmlExecRequest

This function sends an XML request to XML Easycom Server.

mixed i5_XmlExecRequest ( string Input_Request

[resource Connection ])

Details

XML string is sent to XML Easycom Server, for execution. A resulting XML is returned back. Parameters

Input_Request Input_Request can be :

A string containing XML tags according to XML Easycom syntax.

A string containing a full path to an XML file in the IFS. This XML file contains XML Easycom requests.


Returns:

Function returns a string containing XML stream with Program return value and modified parameters.

In case of error, i5_XmlExecRequest() returns false. Call i5_XmlLastError() to retrieve error details.

Examples

i5_XmlExecRequest() receives an XML string, and it returns an XML string. // Define procedures

$XmlIn = '<?xml version="1.0" encoding="utf-8"'.'?'.'>'.

'<Easycom>'.

' <define>'.

' <file stmf="/tmp/sr/CUST_DIM.pcml" type="PCML" />'.

' </define>'.

'</Easycom>';

$XmlOut = i5_XmlExecRequest($XmlIn);

echo 'Out='.htmlentities ($XmlOut).'';

// Effective Call

$CustId = "01551";

$XmlIn = '<?xml version="1.0" encoding="utf-8"'.'?'.'>'.

'<Easycom>'.

' <Program Name="CUST_DIM">'.

' <parameterList>'.

' <Toread>'."15".'</Toread>'.

' <IO>'."20".'</IO>'.

' <Term1>'.$CustId.'</Term1>'.

' </parameterList>'.

' </Program>'.

'</Easycom>';

$XmlOut = i5_XmlExecRequest($XmlIn);

echo 'Out='.htmlentities ($XmlOut).'';

i5_XmlExecRequest() receives a path to a file in IFS, and it returns an XML string. IFS file contains XML Easycom requests. $XMLStr = i5_XmlExecRequest("/tmp/sr/_define01.xml");

See also

i5_XmlBindSrvPgm i5_XmlCallProgram i5_XmlDefine i5_XmlLoadDefinition

i5_program_call

This function calls the Program or Procedure described with the i5_program_prepare and optionally accepts results.

bool i5_program_call ( resource program ,

array params

[, array retvals])

Details

Several calls can be made with the same description using the same program resource.

Parameters

program Program resource opened by i5_program_prepare(), or i5_program_prepare_PCML().

params Parameters according to description.

Can be given as flat array, then parameters are assigned in order, or

as key => value pairs then the values are assigned to the parameter

named by the key

retvals Array of key => value pairs where keys describe output parameter name and

values name PHP variable that would receive the parameter

Fetch should still work even if the return parameters are defined and assigned.






I5_ERR_PHP_VARIABLE 281 You can't use the I5_bind_param function and specify parameters


I5_ERR_PHP_EXECUTE 289 You cannot read a request with parameters without calling the I5_execute function.

I5_ERR_PHP_NO_COMMAND 290 Empty command line or name

I5_ERR_PHP_NO_PARMNAME 293 Internal error; please contact Aura Equipement; error number 293

Example

/* call a program passing simple parameters and an associative array */

$description = array (

array ("Name"=>"OP1", "IO"=>I5_IN, "Type"=>I5_TYPE_PACKED, "Length"=>"5.2"),

array ("Name"=>"STR1", "IO"=>I5_IN, "Type"=>I5_TYPE_CHAR, "Length"=>20),

array ("Name"=>"OP2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_PACKED, "Length"=>"5.2"),

array ("Name"=>"STR2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>30),

array ("Name"=>"OP3", "IO"=>I5_OUT, "Type"=>I5_TYPE_PACKED, "Length"=>"10.4") ); $hdlPgm = i5_program_prepare("EASYCOM/RPCSAMPLE", $description);

$parameterIn = Array("OP2"=> 20.2, "STR2"=>"test", "STR1"=>"Hello", "OP1"=> 10.1); $parameterOut = array("OP2"=>"parmOperator2", "STR2"=> "parmString2");

$ret = i5_program_call($hdlPgm, $parameterIn, $parameterOut);

if (!$ret){ print_r(i5_error());

trigger_error("i5_execute error : ".i5_errormsg(), E_USER_ERROR); }

echo "Parameter 3(P1+ P3, 10.1 + 20.2) : $parmOperator2 ";

echo "Parameter 4(P2), Hello : $parmString2 "; $ret = i5_program_close ($hdlPgm);

if (!$ret){

trigger_error("i5_program_close error : ".i5_errormsg(), E_USER_ERROR); }

/*call a program passing simple parameters and an indexed array */


array ("Name"=>"OP1", "IO"=>I5_IN, "Type"=>I5_TYPE_PACKED, "Length"=>"5.2"),

array ("Name"=>"STR1", "IO"=>I5_IN, "Type"=>I5_TYPE_CHAR, "Length"=>20),

array ("Name"=>"OP2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_PACKED, "Length"=>"5.2"),

array ("Name"=>"STR2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>30),

array ("Name"=>"OP3", "IO"=>I5_OUT, "Type"=>I5_TYPE_PACKED, "Length"=>"10.4") ); $hdlPgm = i5_program_prepare("EASYCOM/RPCSAMPLE", $description); $parameterIn = Array(10.1, "Hello", 20.2, "test"); $parameterOut = array("OP2"=>"parmOperator2", "STR2"=> "parmString2"); $ret = i5_program_call($hdlPgm, $parameterIn, $parameterOut);



echo "Parameter 3(P1+ P3, 10.1 + 20.2) : $parmOperator2 ";

echo "Parameter 4(P2), Hello : $parmString2 "; $ret = i5_program_close ($hdlPgm);

if (!$ret){

trigger_error("i5_program_close error : ".i5_errormsg(), E_USER_ERROR); }

Note

Use i5_command in order to invoke a program without parameters. For example, i5_command("call LIB_NAME/PROGRAM_NAME").

i5_program_close

Frees program resource handle.

void i5_program_close ( resource program )

Parameters

program Program resource opened by i5_program_open






Example

$description = array ( array ("Name"=>"OP1", "IO"=>I5_IN, "Type"=>I5_TYPE_PACKED, "Length"=>"5.2"),

array ("Name"=>"STR1", "IO"=>I5_IN, "Type"=>I5_TYPE_CHAR, "Length"=>20), array ("Name"=>"OP2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_PACKED, "Length"=>"5.2"), array ("Name"=>"STR2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>30), array ("Name"=>"OP3", "IO"=>I5_OUT, "Type"=>I5_TYPE_PACKED, "Length"=>"10.4") ); $hdlPgm = i5_program_prepare("EASYCOM/RPCSAMPLE", $description); $parameterIn = Array(10.1, "Hello", 20.2, "test"); $parameterOut = array("OP2"=>"parmOperator2", "STR2"=> "parmString2"); $ret = i5_program_call($hdlPgm, $parameterIn, $parameterOut); if (!$ret){ print_r(i5_error()); trigger_error("i5_execute error : ".i5_errormsg(), E_USER_ERROR); } echo "Parameter 3(P1+ P3, 10.1 + 20.2) : $parmOperator2 "; echo "Parameter 4(P2), Hello : $parmString2 "; $ret = i5_program_close ($hdlPgm); if (!$ret){ trigger_error("i5_program_close error : ".i5_errormsg(), E_USER_ERROR); }

i5_program_prepare

Opens a Program or Procedure and prepares it to be run.

resource i5_program_prepare ( (string name

[, array description]

[, resource connection])

Parameters

name Program name. For a call to a Procedure in a Service Program, the procedure name is given in parentheses, e.g., Lib/Service_Program(PROC)

description PHP-format program description. This should be provided if the program is not described on server.

See: PHP Data Description

connection Result of i5_connect

Returns: Resource if open succeeded, false if open failed.







I5_ERR_PHP_ALREADY_PGMNAME 284 You cannot call this function; because it was already called or x was called.


I5_ERR_PHP_GET_SYSVAL 297 The command returned an error: x.

I5_ERR_PHP_BAD_DS_INPUT 308 Values for 'Data Structure' parametre -1 does not match the description.

Example 1

/*Call a program passing a data structure as parameter */

/* 4th parameter is a DS */


array ("Name"=>"P1", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>10,

"Count"=>5),

array ("Name"=>"P2C", "IO"=>I5_INOUT,"Type"=>I5_TYPE_LONG, "Length"=>4),

array ("Name"=>"P2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>1,

"CountRef"=>"P2C" ),

array ("DSName"=>"PS", "Count"=>2, "DSParm"=>array (

array ("Name"=>"PS1", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>10),

array ("Name"=>"PS2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>10),

array ("Name"=>"PS3", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>10) ) ) ); $hdlPgm = i5_program_prepare("EASYCOM/RPCTEST", $description); $Psparameter = array( array("PS1"=>"test1", "PS2"=>"test2", "PS3"=>"test3"),

array("PS1"=>"test3", "PS2"=>"test4", "PS3"=>"test5") ); $parameter2 = Array( "P1"=>array("t1", "t2", "t3", "t4", "t5"),

"P2C"=>2,

"P2"=>array("a", "b"),

"PS"=>$Psparameter ); $parmOut2 = array("P1"=>"P1", "PS"=>"PS");

$ret = i5_program_call($hdlPgm, $parameter2, $parmOut2);



echo "P1 : $P1 ";

echo "PS: ";print_r($PS);echo " ";

Example 2

/*Call program with simple parameters*/

$description = array ( array ("Name"=>"OP1", "IO"=>I5_IN, "Type"=>I5_TYPE_PACKED, "Length"=>"5.2"), array ("Name"=>"STR1", "IO"=>I5_IN, "Type"=>I5_TYPE_CHAR, "Length"=>20), array ("Name"=>"OP2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_PACKED, "Length"=>"5.2"), array ("Name"=>"STR2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>30), array ("Name"=>"OP3", "IO"=>I5_OUT, "Type"=>I5_TYPE_PACKED, "Length"=>"10.4") ); $hdlPgm = i5_program_prepare("EASYCOM/RPCSAMPLE", $description); $parameterIn = Array("OP1"=> 10.1, "STR1"=>"Hello", "OP2"=> 20.2,

"STR2"=>"test"); $parameterOut = array("OP2"=>"parmOperator2", "STR2"=> "parmString2"); $ret = i5_program_call($hdlPgm, $parameterIn, $parameterOut); if (!$ret){ print_r(i5_error()); trigger_error("i5_execute error : ".i5_errormsg(), E_USER_ERROR); } echo "Parameter 3(P1+ P3, 10.1 + 20.2) : $parmOperator2 "; echo "Parameter 4(P2), Hello : $parmString2 ";

i5_program_prepare_PCML

Opens a Program or Procedure using a PCML description, and prepares it to be run.

resource i5_program_prepare_PCML ( array description

string program_name


Detail

The program information file (in PCML format) can be created by compiling the RPG

program. Example:

CRTBNDRPG PGM(EACDEMO/TESTSTRUC) SRCFILE(EACDEMO/QRPGLESRC) SRCMBR(TESTSTRUC) PGMINFO(*PCML) INFOSTMF('/www/zendcore/htdocs/teststruc.pcml')

The PCML file will contain the program parameters info. There are two ways you can assign the program parameters to i5-program_prepare_PCML description:

- Copy the content of PCML file to you PHP script and assign the i5_program_prepare_PCML description array to the PCML content. See PCML example in PCML Example 1

- Assign i5_program_prepare description array to the PCML file located in the same PHP program directory. See PCML example in figure 2

Parameters

description PCML file's program and parameters information. This parameter string can contain the PCML description itself, or the path to a text file containing the PCML description.

Program_name Program name is usually embedded inside the PCML file. By setting this parameter, you can override the contain of the PCML file, and connect to another program having same description.

Program name is in the form:

LIBRARY/NAME NAME, when program is in the job library list. LIBRARY/NAME(Procedure), for a Procedure in a Service Program. NAME(Procedure), when Service Program is in the LIBL.








I5_ERR_PHP_NO_DS_VALUE 307 You cannot set a value for 'Data Structure' x.

Example PCML :

$description = "<pcml version=\"4.0\">     <struct name=\"S2\"> <data name=\"ZOND2\" type=\"zoned\" length=\"10\" precision=\"5\" usage=\"inherit\" /> <data name=\"PACK2\" type=\"packed\" length=\"19\" precision=\"5\" usage=\"inherit\" /> <data name=\"PACK3\" type=\"packed\" length=\"19\" precision=\"5\" usage=\"inherit\" /> <data name=\"ALPH2\" type=\"char\" length=\"20\" usage=\"inherit\" /> </struct>  <struct name=\"S1\"> <data name=\"ZOND\" type=\"zoned\" length=\"10\" precision=\"5\" usage=\"inherit\" /> <data name=\"PACK1\" type=\"packed\" length=\"19\" precision=\"5\"

usage=\"inherit\" /> <data name=\"ALPH1\" type=\"char\" length=\"10\" usage=\"inherit\" /> </struct> <program name=\"TESTSTRUC\" path=\"/QSYS.LIB/EACDEMO.LIB/TESTSTRUC.PGM\"> <data name=\"CODE\" type=\"char\" length=\"10\" usage=\"output\" /> <data name=\"S1\" type=\"struct\" struct=\"S1\" usage=\"inputoutput\" /> <data name=\"S2\" type=\"struct\" struct=\"S2\" usage=\"inputoutput\" /> <data name=\"PACK\" type=\"packed\" length=\"1\" precision=\"1\" usage=\"output\" /> <data name=\"CH10\" type=\"char\" length=\"19\" usage=\"output\" /> <data name=\"CH11\" type=\"char\" length=\"20\" usage=\"output\" /> <data name=\"CH12\" type=\"char\" length=\"29\" usage=\"output\" /> <data name=\"CH13\" type=\"char\" length=\"33\" usage=\"output\" /> </program> </pcml> ";

Exemple 2:

($description = file_get_contents("/www/zendcore/htdocs/teststruc.pcml"))

or trigger_error("Error while opening PCML file", E_USER_ERROR);

Commands & System values

i5_command

Calls CL command.

bool i5_command ( string command

[, array inputs, array outputs


Details

Out parameter can be returned by the command.

Parameters

inputs Array of name => value parts, name describing the call input parameters.

Names should match i5 CL command parameter names.

If the array is empty or not provided, no input parameters are given. If the value is integer,

integer is passed, if the value is string, quoted string is passed. If the value is an array, the

list of contained values is passed.

Note: The output parameter is required if the input parameter is specified.

Outputs Array which describes output parameters of the command. If not provided, no output parameters are defined.

Key of the array defined i5 CL command parameter name

"rc" is a predefined name containing the result of the command.

Value can be string. If so - it defines a php variable name to accept the parameter or array;

it should have 2 elements:

- A php variable name to accept the parameter.

- Description of the parameter

Note: The input parameter is required if the output parameter is specified.

connection Connection - result of i5_connect.

I5_ERR_PHP_INTERNAL 288 Internal error; please contact Aura Equipement; error number 288


I5_ERR_PHP_NO_ZVALUE 294 Internal error; please contact Aura Equipement; error number 294

Example

/*This is a direct, simple, command, with no output values*/

$ret = i5_command("CLRSAVF FILE(EASYCOM/SAVOBJ)");

/* This is also a direct command, but with separate values*/

/* This is equivalent to SAVOBJ OBJ('PGM1 PGM2 PGM3')*/ /*LIB(MY_LIB) DEV(*SAVF)

OBJTYPE(*PGM) SAVE(EASYCOM/SAVOBJ)*/

$Input = array( "OBJ" => array("PGM1","PGM2","PGM3"), "LIB" => "MY_LIB", "DEV" => "*SAVF", "OBJTYPE" => "*PGM", "SAVF" => "EASYCOM/SAVOBJ" ); $Output = array(); $ret = i5_command("SAVOBJ", $Input, $Output); /* Now, a command with return value */

/*This is like in CL: RTVJOBA USER(&USER) SYSLIBL(&SYSLIB)*/

$ret = i5_command ("RTVJOBA", array(), array( "curlib" => "curl", "user" => "user", "usrlibl" => "userlib", "syslibl" => array("syslib", "char(165)")) ); print "User : $user "; print "User library: $userlib "; print "system libs list : $syslib ";

i5_cmd

Executes I5 command.

resource i5_cmd ( string command


Detail

It could be a command with or without parameters, in this case it's better to use i5_remotecmd for performance as well as for error management.

Syntax is similar to a CL command, variables names with "&" in front.

Example: $ret = i5_cmd("RTVJOBA USER(&USR)");

More than 20 characters variable or with type other than CHAR must be declared in CHAR(len) or DEC(len dec). All declarations separated with semicolon ";".

Example: $ret = i5_cmd("LIBL=CHAR(2750);DFTWAIT=DEC(7 0);RTVJOBA USRLIBL(&LIBL)");

Further to i5_cmd call, output variables can be fetched with i5_cmdget function (one at a time).

Warning! If, with a correct syntax execution fails, the function does not create error but update a special variable called RC.

This variable contains, in case of fault, provoked CPF code and 0 in case of success.

It is always necessary to check every time that the RC variable is null before fetching the command proper variables.

Parameters

command String; Command to execute


Returns:








Example

/* Connection to AS400 */


/* Executes the command on AS400 */

i5_cmd("user=char(10);usrlib=char(275);syslib=char(165);curl=cha

r(10);rtvjoba user(&user) usrlibl(&usrlib) syslibl(&syslib)

curlib(&curl)");

if ($ret) {

$res = i5_cmdget("RC");

if (RC==0) {

$util = i5_cmdget("user", $conn);

$bibl = i5_cmdget("usrlib", $conn);

$sysb = i5_cmdget("syslib", $conn);

$curl = i5_cmdget("curl", $conn);

print "User: ". $util." " ;

print "User libraries list: ". $bibl . " " ;

print "System libraries list: ". $sysb." " ;

print "Current library: " . $curl . " " ;

}

}

/* Executes the command on I5 */

$ret = i5_cmd("NB=CHAR(20); RTVSYSVAL SYSVAL(QSRLNBR)

RTNVAR(&NB)");

if ($ret) {


if (RC==0) {

/* Retrieves the executed command concerned variable */

$num = i5_cmdget("NB");

echo "Serial number is ". $num ." ";

}

}

See also

i5_cmdget

i5_remotecmd

i5_cmdget

Fetches output variable further to a sent i5_cmd command.

string i5_cmdget ( string variable_name


Detail

i5_cmdget function is allways used after i5_cmd with output parameters.

Those parameters can only be fetched with theirs names, type is always string.

Parameters

namvariable variable to read name

connection Current connection ID







Example

/* Connection to AS400 */


/* Executes the command on AS400 */

i5_cmd("user=char(10);usrlib=char(275);syslib=char(165);curl=cha

r(10);rtvjoba user(&user) usrlibl(&usrlib) syslibl(&syslib)

curlib(&curl)");

if ($ret) {


if ($res==0) {

$util = i5_cmdget("user", $conn);

$bibl = i5_cmdget("usrlib", $conn);

$sysbibl = i5_cmdget("syslib", $conn);

$curl = i5_cmdget("curl", $conn);

print "User: " . $util. " " ;

print "User libraries list: " . $bibl . " " ;

print "System libraries list: " . $sysbibl ." " ;

print "Current library: " . $curl . " " ;

}

}

See also

i5_cmd

i5_remotecmd

i5_remotecmd

Executes I5 command without returned value.

bool i5_remotecmd ( string command


Details

Command is sent to I5 and performed according to connected profile. Its syntax is identical to a terminal entered command syntax but can not be interactive ( DSPxxx type).

Use i5_cmd function for commands with returned values.

Parameters

command Command to perform on I5


Returns:







Example

/* Message sending */

$rets = i5_remotecmd("SNDMSG MSG(‘Hello’) TOUSR(QPGMR)") ;

/* Adds a library */

$ret = i5_remotecmd("ADDLIBLE MALIBL") ;

See also

i5_cmd

i5_cmdget

i5_get_system_value

Gets a system value.

string i5_get_system_value ( string Value_Name


Parameters

name Name of a system value.

Possible values for name are available with the WRKSYSVAL command on an i5/OS terminal

Returns:

The value of the system value in case of success.

False is returned in case of error. For getting the code and error message call i5_error function.







I5_ERR_PHP_EMPTY_NAME 314 Object name can not be empty

Example

$ret = i5_get_system_value('QSYSLIBL');

echo 'QSYSLIBL: ' .$ret. ' ';

$ret = i5_get_system_value('QSRLNBR');

echo 'Serial number: '.$ret.' ';

Native database access

i5_open

Opens native i5 file.

resource i5_open ( string filename [, int mode ]


Details

A file must be opened with i5_open function prior to access it (reading or writing). Function i5_open() returns an ID to be used as parameter for reading, updating or adding, research, etc…operations.

It's more efficient to use job *LIBL by giving only the file name, without library name, if of course the user is entitled to necessary and coherent rights to opening mode and path. You can qualify the path by providing a library name in the form: LIBRARY/NAME. The current library list can be previously changed by ADDLIBLE commands call issued by i5_remotecmd .

The file to open can be a physical or logical file.

The file to open can have been overridden by a previous OVRDBF command call, issued by i5_remotecmd . It can also be filtered by an OPNQRYF command call.

If the file doesn’t have any description, as for a 36 format file, an external description can by applied. The external description is given at then end of the file name, prefixed by "*FMT=". Example: LIB36F/MYFILE *FMT=DATALIB/DESC36L1

Parameters

name File name. File name can have several formats:

FILE

LIBRARY/FILE

FILE(MEMBER)

LIBRARY/FILE(MEMBER)

When library is not specified, the file must be present in the job library list (*LIBL).

mode File mode to use..

I5_OPEN_READ Open the file for read only (default)

I5_OPEN_READWRITE

Open file for reading and writing

I5_OPEN_COMMIT

Open journalize

I5_OPEN_SHRRD

Shared reading

I5_OPEN_SHRUPD

Shared updating

I5_OPEN_SHRNUPD

Sharing without updating

I5_OPEN_EXCLRD

Open Exclusive; Read allowed

I5_OPEN_EXCL

Open Exclusive

connection Connection - result of i5_connect

Opening option may be combined using PHP usual syntax and "|" (pipe) symbol. OPEN_READ or I5_OPEN_READWRITE modes are required to be combine with other modes.

To open a file in reading/writing, under commitment control, in exclusive mode:

i5_open("EASYCOM/SP_CUST", I5_OPEN_READWRITE | I5_OPEN_COMMIT | I5_OPEN_EXCL)

Procedures and Data Queue

Easycom uses files description to accede to stored procedures and data queues (see Manufacturer DTAQ-RPC) . Principle is to describe all parameters (names, nature, types) stored in Easycom proper files (YPROCHDR and YPROCPARMS).

Opening procedure syntax is *PGM/name_procedure

Opening data queue syntax is *DTAQ/name_dataqueue.

Returns:

Resource, if "open" is successful, false otherwise.





Example

/* Opens a file only in reading */

$file_client = i5_open("PROD/CLIENTS");

/* Opens a file only in writing */

$file_web = i5_open("PROD/WEB", I5_OPEN_READWRITE);

/* Opens a file in *LIBL or *CURLIBL */

$file_lib = i5_open("TEST");

$file_clib = i5_open("*CURLIBL/TEST");

/* Opens a particular member */

$file_fact = i5_open("PROD/INVOICES(2005)");

/* Opens a program or a data queue */

$program = i5_open("*PGM/DEMOPGM");

$dataqueue = i5_open("*DTAQ/DEMODATA");

/* Opens two files on two AS400 */

$conn1 = i5_connect("FIRST_AS", "USER1", "PASSWORD1");

$conn2 = i5_connect("SECOND_AS", "USER2", "PASSWORD2");

if ($conn1 && $conn2) {

$file_client1 = i5_open("PROD/CLIENTS", $conn1);

$file_client2 = i5_open("PROD/CLIENTS", $conn2);

}

See also

i5_free_file

i5_seek

Moves current position to a specific record in file.

Syntax N° 1

bool i5_seek ( resource file ,

int/string operator

[, array keyvalue ]

[, int Last_field_len ] )

Syntax N° 2


int/string operator

[, int bookmark ] )

Details

This function moves result pointer to the record witch indexed values meet table specified parameters.

This function is typically used to search in a file according to a key (simple or composite). It locates the record that fills the specified requirement for a defined index.

See functions i5_range_from and i5_range_to to select a range of records.

i5_seek moves the pointer without reading the result, next call to i5_fetch_xxxx will return the line.

Parameters

File i5 file resource.

operator Comparison operator. Position is set to first record satisfying the operator.

Operator can be specified as a symbolic or string value.

Symbolic value String value Description

I5_EQ "=" Equal

I5_GE ">" Greater than

I5_GT ">=" Greater or Equal

I5_LT "<" Less than

I5_LE "<=" Less or Equal

I5_FIRST "FIRST" First record: No key value is required.

I5_LAST "LAST" Last record: No key value is required.

I5_BOOKMARK "BOOKMARK" Go to record number

Keyvalue values of the keys to locate to. If the key is composed by multiple fields, each entry in array "keyvalue" contains the value for one field.

Last_field_len Length of the last field. When the key is composed by multiple fields, parameter "Last_field_len" represents the number of characters to consider for the last given field, when looking for the record.

If "Last_field_len" is omitted, the last given key field will be considered in its full size.

If "Last_field_len" has special value I5_ACTUAL_SIZE, the current contain size of the cell in "keyvalue" array, will be considered for the last field.

Returns:


Error returned





I5_ERR_PHP_TYPEGET 264 The x function is unable to translate this type (-1).

I5_ERR_PHP_OPERATOR_BAD 265 Unknown operator (x)

I5_ERR_FIELDNULL 4097 Field value is NULL

Example

$file = i5_open('EASYCOM/NCLIENT');

/* Looking for MARTIN */ $seek = array("MARTIN"); /* Looking for martin pierre*/ //$seek = array("MARTIN ", "PIERRE"); $ret = i5_seek($file, "=", $seek); $rec = i5_fetch_row($file, I5_READ_SEEK); /* Set a bookmark on current record */ $dupont = i5_bookmark($file); [... others treatments on the file ...] /* Direct return to back to DUPONT record */ $ret = i5_data_seek($file, $dupont); $rec = i5_fetch_row($file, I5_READ_SEEK);

print_r($rec);echo " ";

See also

i5_data_seek

i5_fetch_xxx

i5_match

i5_match

Check if current record match the latest requested key value.

bool i5_match ( resource file

[, int key_fields_count ]


Details

The key value for the current record is compared to the key value provided to the latest i5_seek function call.

Parameters


key_fields_count When the access key is composed by multiple fields, "key_fields_count" represents the count of fields to consider when comparing the key values.

If "key_fields_count" is omitted, the size of the key given on the latest call to i5_seek will be applied.

last_field_len When the access key is composed by multiple fields, "last_field_len" represents the size to consider for the last key field, when comparing the key values.

If "last_field_size" is omitted, the size original size of the key field is applied.

Returns:

True if match, false otherwise.

Error returned





Example


/* Looking for MARTIN */ $seek = array("MARTIN"); /* Looking for martin pierre*/ //$seek = array("MARTIN ", "PIERRE"); $ret = i5_seek($file, "=", $seek); $rec = i5_fetch_row($file, I5_READ_SEEK); if (is_bool($rec))

trigger_error("i5_fetch_row error : ".i5_errormsg(), E_USER_ERROR);

$ret = i5_match($file); if ($ret) echo "Record found "; else echo "Record no found "; /* Set a bookmark on current record */ $dupont = i5_bookmark($file);

[... others treatments on the file ...] /* Direct return to back to DUPONT record */ $ret = i5_data_seek($file, $dupont); if (!$ret)

trigger_error("i5_data_seek error : ".i5_errormsg(), E_USER_ERROR);

$rec = i5_fetch_row($file, I5_READ_SEEK); if (is_bool($rec)) trigger_error("i5_fetch_row error : ".i5_errormsg(), E_USER_ERROR); print_r($rec);echo " ";

See also

i5_seek

i5_fetch_xxx

i5_range_from

Sets an upper range bound for the file. Once the bound is set, the first line for all seeks becomes the line defined by the range.

Bool i5_range_from ( resource file ,

bool included, array values )

Details

Sets the lower filter limit in a file according to one or several keys values set as parameters in table.

Range may be enabled or disabled for each open file. I5_range_from and i5_range_to functions, used together or alone will activate the range. To get full file access i5_range_clear function must be run

Using i5_range_from without calling i5_range_to, range will go from specified limit to file end.

Using i5_range_to without calling i5_range_from, range will go from file start to specified limit.

Upper and lower limits can be set equal:

$commun = array("FAMILY" => "WHOLESALERS"); $ret = i5_range_from($file, true, $commun); $ret = i5_range_to($file, true, $commun);

"included" parameter is a Boolean (TRUE or FALSE) specifying if the limit is included or not in the range.

If the value is FALSE the lower limit (set with i5_range_from) will be the following record and the upper limit (set

with i5_range_to) will be the last record.

Parameters

file i5 file resource.

included True if the field with this key should be included in the range, false otherwise.

values Values for the key fields - array of key=>value pairs.


Error returned

Example


if (is_bool($file)) trigger_error('i5_open error : '.i5_errormsg(),

E_USER_ERROR);

$first = array('CNOM' => 'D');

$last = array('CNOM' => 'F');

$ret = i5_range_from($file, true, $first);

if (!$ret) trigger_error('i5_range_from error : '.i5_errormsg(), E_USER_ERROR);

$ret = i5_range_to($file, false, $last);

if (!$ret) trigger_error('i5_range_to error : '.i5_errormsg(), E_USER_ERROR);

echo 'i5_fetch_row : ';

i5_seek($file, I5_FIRST);

while ($tab = i5_fetch_row($file)) {

printf('%s (%s) ', $tab[3], $tab[2]);

}

See also

i5_seek

i5_range_to

i5_range_clear

i5_range_to

Sets a lower range bound for the file. Once the bound is set, the last entry for all seeks becomes the entry defined by the range.

Bool i5_range_to ( resource file ,

bool included, array values )

Details

Sets the upper filter limit in a file according to key(s) value(s) defined as parameter(s).

Range can be activated or deactivated for each open file. i5_range_from and i5_range_to functions, used together or alone will activate the range. To get full file access i5_range_clear function must be used

Using i5_range_from without calling i5_range_to, range will go from specified limit to file end.

Using i5_range_to without calling i5_range_from, range will go from file start to specified limit.

Upper and lower limits can be set equal:

$commun = array("FAMILY" => "WHOLSALERS"); $ret = i5_range_from($file, true, $commun); $ret = i5_range_to($file, true, $commun);

"included" parameter is a Boolean (TRUE or FALSE) specifying if the limit is included or not in the range.

If the value is FALSE the lower limit (set with i5_range_from) will be the following record and the upper limit (set with

i5_range_to) will be the last record.

Parameters

file i5 file resource

included True if the field with this key should be included in the range,

false otherwise.

values Values for the key fields - array of key=>value pairs.

Returns:


Error returned






Example



E_USER_ERROR);











}

See also

i5_seek

i5_range_from

i5_range_clear

i5_range_clear

Removes range. Reverses the action of i5_range_from and i5_range_to

Bool i5_range_clear ( resource file )

Details

Range is a set of values (interval or filter) in a file, it can be activated with i5_range_from and/or i5_range_to and remains active, limiting file access to the records included in the range until i5_range_clear is called (full file access).

Parameter

file i5 file resource

Returns:


Error returned


Example



E_USER_ERROR);











}

$ret = i5_range_clear($file);

if (!$ret) trigger_error('i5_range_clear error : '.i5_errormsg(), E_USER_ERROR);

echo ' i5_fetch_assoc : ';

$tab = i5_fetch_assoc($file, I5_READ_FIRST);

$count = 0;

while ($tab) {

printf('%s (%s) ', $tab['CPREN'], $tab['CNOM']);

$tab = i5_fetch_assoc($file, I5_READ_NEXT);

$count ++;

if ($count > 3) break;

}

See also

i5_range_from

i5_range_to

i5_seek

i5_free_file

Closes file handle and frees file resources.

Bool i5_free_file ( resource file )

Details

Frees i5_open opened file resources and closes it on I5

Parameters

file I5 file resource

Additional functions to the existing API.



I5_ERR_PHP_CALL_BINDPARAM 274 The I5_bind_result function can be called only once

Example

$file_client = i5_open("PROD/CLIENTS");

[... treatments ...]

$ferme = i5_free_file($file_client);

if ($ferme) {

echo "Closing successful";}

See also

i5_open

i5_free_query

i5_edit

Sets editing mode for the record. In order for a value to be changed, it should be set in edit mode. This locks the record so that other users cannot edit it simultaneously.

Bool i5_edit ( resource file [, int mode] )

Detail

Before any record modification or writing attempt editing mode must be set using i5_edit. function.

Warning: if the record is allready in editing mode or locked by another user, the function will return an I5_ERR_RECORDLOCKED error type. It's important to check this eventuality in the code.

i5_edit will lock the record until i5_update or i5_cancel_edit is called.

Then, values can be allocated using i5_setvalue and, according to mode, validate updating using i5_update function.

I5_EDIT_ONE Quits editing mode after i5_update function call

An i5_delete or a reading will also deactivate. editing mode

I5_EDIT_ALWAYS Keeps in editing mode after i5_update function call

To exit , i5_cancel_edit must be called.

I5_EDIT_AUTO Updating is automatic, so, calling i5_update function to validate is unnecessary.

Note:

Modes I5_EDIT_AUTO and I5_EDIT_ALWAYS can be combined:

$edit = i5_edit($file, I5_EDIT_AUTO | I5_EDIT_ALWAYS);

Parameters


mode Editing mode. I5_EDIT_ONE leaves edit mode after i5_update() and also after reading or i5_delete(). I5_EDIT_ALWAYS remains in edit mode until i5_cancel_edit() is called. I5_EDIT_AUTO is called automatically therefore there is no need to call i5_update() after setting values.

Example

/* Opening connection and file */

$conn = i5_connect("MY_AS","USER","PASSWORD");

$res = i5_open("EASYCOM/TESTFILE", I5_OPEN_READWRITE);

/* Opening current record edition mode */

$ret = i5_edit($res, I5_EDIT_ONE);

if(!$ret) {

echo "error code: " . i5_errno($conn) . " ";

echo "error message: " . i5_errormsg($conn) . " ";

}

else {

/* Modifies ONE current record field value */

$ret = i5_setvalue($ret, "CODE", "C-02");

$ret = i5_update($res);

}


if(!$ret) {



}

else {

/* Modifies ALL current record values */

$table = array("CODE" => "C-02", "NAME" => "DUPONT", "TYPE"

=> 3);

$ret = i5_setvalue($ret, $table);


See also

i5_open

i5_update

i5_delete

i5_addnew

i5_cancel_edit

i5_cancel_edit

Quits editing mode.

Bool i5_cancel_edit ( resource file)

Detail

After calling i5_edit switching to editing mode to record a file, i5_cancel_edit function restores normal mode.

Depending on editing mode, if updating is not automatic (I5_EDIT_AUTO), any modifications introduced with i5_setvalue will be lost.

Parameters

result Open file ID

Returns: TRUE if editing mode is deactivated FALSE if not.

I5_ERR_PHP_HDLBAD 258 Bad connection handle




Example

/* Activate current record edition mode */

$res = i5_open("EASYCOM/TEST");


if(!$ret) {



}

else {


$ret = i5_setvalue($ret, "CODE", "C-02");

if ($_GET["confirmation"]=="no") {

$cancel = i5_cancel_edit($res);

}

See also

i5_open

i5_edit

i5_update

i5_delete

i5_addnew

i5_setvalue

Changes the value of the current record. The record should be in edit mode after i5_edit() or created by i5_addnew().

Syntax N° 1:

Bool i5_setvalue ( resource file

, int/string field, mixed value )

Syntax N° 2:

Bool i5_setvalue ( resource file

, array values )

Detail

This function is used after editing is set with i5_edit function or after an addition with i5_addnew.

If mode is automatic (I5_EDIT_AUTO), updating is performed directly, otherwise i5_update function must be called to validate it.

One or more current record fields can be modified setting field index, name or table as parameter.

If using table, it may be an associative table fields to modify name as key and each field value as values, in respect of their types.

$table = array("CODE" => "C-02", "NAME" => "DUPONT", "TYPE" => 3);

or an indexed table as well, in this case order must be fully respected:

$table = array('C-105', 'DUPOND', 'Jean', 'Avenue du Québec', 'Les Ulis', 3, 'FR');

Code must be index 0 field, index 1 name, index 5 type.

Parameters


field field Field identifier by name or position.

value Value for the field.

values Set of key=>value parts describing fields to change and their new values.

Returns:







Example

/* Opening file in writing */


$rec = i5_fetch_row($res, I5_READFIRST);

/* Activates current record edition mode */


if (!$ret) {



}

else {


$ret= i5_setvalue($ret, "CODE", "C-02");

/* or i5_setvalue($ret, 0, "C-02"); */



/* Modifies MANY current record field values */


=> 3);

$ret= i5_setvalue($ret, $table);


}

/* Modifies the 7 first current record values */

$table = array('C-105', 'DUPOND', 'Jean', 'Avenue du Québec',

'Les Ulis', 3, 'FR');

$ret= i5_setvalue($ret, $table);


}

See also

i5_addnew

i5_edit

i5_update

i5_addnew

Creates new record in the file. Use setvalue() to set values in new record, then update() to write it to file.

i5_new_record() is an atomic function doing all the work.

Bool i5_addnew ( resource file [, int mode] )

Details

File must have been opened in writing (see i5_open), in other case, function returns FALSE and generates an

I5_INVALIDOPENMODE error type.

Then i5_setvalue function allows value allocation while i5_update allows record updating.

Add mode permits new record initialisation either with "empty" values (or default according to fields properties), either with data buffer present values, that is the last read or added record values.

I5_ADDNEW_CLEAR Set fields to blank

I5_ADDNEW_NOCLEAR Don't clears fields

Default mode is I5_ADDNEW_CLEAR.

Parameters

file Opened i5 file.

mode I5_ADDNEW_CLEAR: clears all record fields (default).

I5_ADDNEW_NOCLEAR: does not clear all record fields

Returns: True if resource is OK, false if failed.

Error return





I5_ERR_PHP_DTAQ_BADKEY 309 The key is not correct.

Example

/* Opens file in writing */

$res = i5_open("EASYCOM/TESTFILE", I5_OPEN_READWRITE, $conn);

/* Record adding blank */

$ret = i5_addnew($res);

if(!$ret) {


echo "error message: " . i5_errormsg($conn) . " ";}

else {

/* Alocates values to current record */


=> 3);

$ret = i5_setvalue($ret, $table);


}

See also

i5_open

i5_edit

i5_setvalue

i5_update

i5_delete

i5_free_file

i5_update

Commits changes done to the file record after i5_edit() or i5_addnew() into the file.

Bool i5_update ( resource file )

Details

i5_update function validates added record updating (i5_addnew) or curently edited (i5_edit) witch values were modified (at prior) with i5_setvalue.

Parameters

Example

/* File opening */

$fich = i5_open("EASYCOM/SP_CUST" , I5_OPEN_READWRITE);

/* Current record edition */

$ret = i5_edit($fich);

/* Current record field modification */

$ret = i5_setvalue($fich, "SP_CUST", "C-02") ;

/* Modification validation */

$ret = i5_update($fich);

See also

i5_open

i5_edit

i5_delete

i5_addnew

i5_cancel_edit

i5_delete

Remove current record.

Bool i5_delete ( resource file )

Details

The file must be opened in writing, set on a record, being in editing mode with i5_edit and i5_delete called.

Parameters







Example

/* Connection and file opening */



/* Activates current record edition mode */

/* Deletes record */

$ret = i5_delete($ret);

See also

i5_open

i5_edit

i5_update

i5_addnew

i5_cancel_edit

i5_new_record

Inserts provided data into a new record.

Bool i5_new_record ( resource file , array data )

Parameters

fileHdl File handle returned by i5_open

Data Data array for the new record.

The array can be a flat or associative array.

If a associative array is specify, the key is the name of field and the value pair contains the value of the field

Returns:








Example

$hdlFile = i5_open ("EASYCOM/SP_DET", I5_OPEN_READWRITE); if (IS_BOOL($hdlFile)) trigger_error("i5_open error : ".i5_errormsg(),

E_USER_ERROR); $ret = i5_new_record ($hdlFile , array (2500, "1", 11564, "5", 5)); if (!$ret) trigger_error("i5_new_record error : ".i5_errormsg(), E_USER_ERROR); echo "New record inserted ";

i5_update_record

Updates the current record using the data provided.

Bool i5_update_record ( resource file , array data )

Parameters

fileHdl File handle returned by i5_open.

Data Data array to containing update information.

The array can be a flat or associative array.

If an associative array is specify, the key is the name of field and the value pair contains the value of the field.

Returns:






Example

$hdlFile = i5_open ("EASYCOM/SP_DET_OR", I5_OPEN_READWRITE); if (IS_BOOL($hdlFile)) trigger_error("i5_open error : ".i5_errormsg(),

E_USER_ERROR); $ret = i5_new_record ($hdlFile , array (2500, "1", 11564, "5", 5)); if (!$ret) trigger_error("i5_new_record error : ".i5_errormsg(), E_USER_ERROR); echo "New record inserted "; $ret = i5_seek($hdlFile, "=", array(2500)); if (!$ret) trigger_error("i5_seek error : ".i5_errormsg(), E_USER_ERROR); $rec = i5_fetch_row($hdlFile, I5_READ_SEEK); if (is_bool($rec)) trigger_error("i5_seek error : ".i5_errormsg(),

E_USER_ERROR); $ret = i5_update_record ($hdlFile , array ("quantity" => 50)); if (!$ret) trigger_error("i5_new_record error : ".i5_errormsg(), E_USER_ERROR); echo "New record updated ";

i5_delete_record

Removes current record.

Bool i5_delete_record ( resource file )

Parameters

File Opened i5 file resource.







Example

/* Connection and file opening */

i5_new_record($file, array('C-105', 'DUPOND', 'Jean', 'Avenue du

Quebec', 'Les Ulis', 3, 'FR'));

$rec = i5_fetch_row($file, I5_READFIRST);

i5_update_record($file, array("CODE" => "C-02", "NOM" =>

"DUPONT", "TYPE" => 3));

/* Deletes record */

$ret = i5_delete_record($file);

SQL Queries & Procedures

i5_query

Sends SQL request and possibly collects results set.

resource i5_query ( string query


Detail

SELECT request type i5_query returns a resource in case of success or FALSE in case of error.

For UPDATE or DELETE request type, i5_query returns TRUE in case of success or FALSE in case of error.

i5_query function is the most suitable for all easy processing, without parameter requests, otherwise a parameterized request type like (i5_prepare and i5_execute) must be prepared.

Parameters

query I5 SQL request to be performed

connection Connection ID (optional)

Returns: TRUE or SELECT request type ID or FALSE in case of failure.





Example:

/* Straight request execution */

$query = i5_query('SELECT * FROM EASYCOM/SP_CUST');

if(is_bool($query)){

echo "Error code: " . i5_errno() . " ";

echo "Error message: " . i5_errormsg() . " ";

}

else {

/* Data’s reading and displaying */

echo "<table>";

while ($values = i5_fetch_row($query, I5_READ_NEXT )) {

echo "<tr>";

echo "<td>" .$values[0]. "</td>";

echo "</tr>";

}

echo "</table>";

}

See also:

i5_open

i5_free_query

i5_prepare

i5_execute

i5_set_property

i5_prepare

Prepares SQLrequest

resource i5_prepare ( resource query


Details

Query parameter may include one or several SQL variables if question marks (?) are set at the right places.

There are three main advantages using prepared requests in your script:

Performance: While preparing a request, database server creates a return optimized path in order to collect the requested data's. Later on, when the i5_prepare prepared request is sent, it will use the path avoiding processor overload with each request sent.

Safety: While preparing a request, it is possible to set markers for entry values. Processing the prepared request with entry values, Easycom checks each entry value to make sure that their type match with the column or the description parameters.

Advanced Functionality: Markers not only allow introducing entry values in stored procedure, but also allow collecting OUTPUT and INPUT/OUTPUT recording procedure parameters using i5_bind_param function.

Warning, connections and resources are transient and disappear with each script end, then, the above notes are only in force with set of process appearing in the same script.

Parameters

query SQL request to prepare

connection Connection ID (optional)

Returns:

Returns prepared request ID in case of success, FALSE in other case.






Example

$nom = 'DUPOND';

/* Prepared request creation */

$req = i5_prepare('SELECT CVILLE, CCODE, CNOM, CPREN FROM EASYCOM/NCLIENT WHERE

CNOM=?');

if ($req) {

/* SQL variables association */

$ret = i5_bind_param($req, &$nom);

if (!$ret) trigger_error('i5_bind_param error : '.i5_errormsg(), E_USER_ERROR);

/* Request execution */

$ret = i5_execute($req);

if (!$ret) trigger_error('i5_execute error : '.i5_errormsg(), E_USER_ERROR);

/* Results variables association */

$ret = i5_bind_result($req, &$ville, &$code, &$nom, &$prenom);

if (!$ret) trigger_error('i5_bind_result error : '.i5_errormsg(), E_USER_ERROR);

/* Values reading */

$ret = i5_fetch_row($req);

if (is_bool($ret)) trigger_error('i5_fetch_row error : '.i5_errormsg(),

E_USER_ERROR);

printf('%s is in city %s ', $nom, $ville);

/* Command closing */

$ret = i5_free_query($req);

if (!$ret) trigger_error('i5_fetch_row error : '.i5_errormsg(), E_USER_ERROR);

} else {

trigger_error('i5_prepare error : '.i5_errormsg(), E_USER_ERROR);

}

See also

i5_execute

i5_bind_param

i5_setparam

i5_set_property

i5_setparam

Allocates parameter to parameterized request.

bool i5_setparam ( resource result,

int position, mixed value)

Details

Request must be prepared with i5_prepare function.

i5_setparam function is an alternative to the i5_bind_param function (automatically linked). It allows explicit value allocation to a parameter.

Parameters

stmt i5_prepare prepared request ID

position parameter index (marker) in the request

value parameter allocated value






Example

$insert = 'INSERT INTO animals (id, race, name, weight) VALUES

(?, ?, ?, ?)';

$req = i5_prepare($insert);

$animals = array(0, 'cat', 'Mistinguette', 3.2);

if ($req) {

$result = i5_execute($req, $animals);

if ($result) {

print "Mistinguette adding successful.";

} i5_setparam($req, 3, "Minouche");

i5_setparam($req, 4, 3.8);


if ($result) {

print "Hercule adding successful.";

}

See also

i5_prepare

i5_execute

i5_bind_param

i5_bind_param

Links up variables to request.

bool i5_bind_param ( resource stmt,

mixed &var1 [, mixed &var2...] )

Details

i5_bind_param is used to link up PHP variables to prepared request with i5_prepare.

Variables order is linked to request markers order. That means that it is impossible to link the last marker without linking all variables, but linkage can be limited to the n firsts.

Variables must be referenced, with "&" sign in front.

Once linkage established, the variable remains associated until request (or script…) is closed.

Referenced variables feature is deprecated in the PHP5 and higher. Parameters

stmt i5_prepare request ID

&var1 (…) Variable to link name








Example


if ($conn) {

$req = i5_prepare($conn, "INSERT INTO Language VALUES (?, ?, ?)");

if ($req) {

$liaison = i5_bind_param($req, 'ssi', &$code, &$langue, &$population);

$code = "FRA";

$langue = "français";

$population = 60669000;

$res = i5_execute($req);

if ($res) {

echo "Inserting successful…"; } }

}

}

See also

i5_bind_result

i5_prepare

i5_execute

i5_setparam

i5_bind_result

Links up variables to results set.

bool i5_bind_result ( resource result/query,


or


mixed &var1 , string Filed_Name )

Details

i5_bind_result is used to associate result columns (file or request) to variables. When i5_fetch_xxx is called to read values, Easycom places the data's in the specified variables into the parameter(s) var1, ....

There are two possible syntaxes; the first refers to a variables list.

Variables order is linked to request column order. Then, it is impossible to link up on the last field without linking all others, but linkage can be limited to the n firsts.

Second syntax works as "couple", associating a variable to a field name. In this case the function must be called many times to associate many variables.

It is impossible to set a list first and after a field name.

Les variables must be referenced, with "&" sign in front.

Note: Notice that columns must be linked before calling i5_fetch_xxx. According to column value type, PHP variable type may be automatically modified.

A column may be associated or re-associated any time, even after partially reading the result. The new linkage applies with the next i5_fetch_xxx call.

Return: True if OK, false if failed.







Parameters

query/stmt i5_prepare prepared request ID

&var1 , &var2 variables to associate referenced list

&var variable to associate, in reference

namfield request field or associated file name

Returns TRUE if link is activate, FALSE in case it fails.

Example

/* Preparing the request */

$req = i5_prepare("SELECT Code, Name FROM Pays ORDER BY Name

LIMIT 5");

if (!is_bool($req)) {


If ($ret === FALSE){

$msg = i5_errormsg();

trigger_error("Error : , ".$msg , E_USER_ERROR);

}

/* Associating variables to result */

$ret = i5_bind_result($query, $col1, $col2);




}

/* Values */

$tabResult = i5_fetch_assoc($req);

while (!is_bool($tabResult)) {

printf("%s %s ", $col1, $col2);


}

/* Request closing */

i5_free_query($req);

}

See also

i5_query

i5_prepare

i5_execute

i5_bind_param

i5_setparam

i5_execute

Executes SQL prepared request (stored procedure).

bool i5_execute ( resource Stmt

[,mixed/array param1] )

Details

i5_execute executes an SQL request prepared with i5_prepare.

If the SQL request returns a result set, i.e. a SELECT, a line can be collected (as a table or object) from the query resource with i5_fetch_xxx.

If the request creates results sets (CALL statement), i5_next_result function moves pointer to the next available set. If option I5_OPTIONS_AUTOMATIC_NEXT_RESULT wasn’t set to "1" during connection, you need to call i5_next_result() to get the first result set.

i5_execute is much more efficient than i5_query if the same request has to be run several times with only few parameter changes. See i5_prepare for a short statement on using i5_prepare and i5_execute advantages versus i5_query.

A request may contain markers, identified with "?" sign. These markers can be linked to PHP variables (seer i5_bind_param), the results may be linked to PHP variables using i5_bind_result function.

Request or stored parameters may also be allocated using i5_setparam function and collected using i5_getparam function (for IN/OUT or OUT parameters.

Parameters

stmt i5_prepare returned request ID

param1 Input value parameter matching with marker

params Stored request input parameters table including variables markers

Returns:

Returns a Boolean and update stmt resource in case of success FALSE if it fails.




I5_ERR_PHP_BINDPARAM 276 Internal error; please contact Aura Equipement; error number 276


Example

The following example prepares a four markers INSERT request, set first time values, calls i5_execute function and then modifies the values before a second call.

$insert = 'INSERT INTO EASYCOM/S_CUSTOMER (CUST_iD, COMPANY, FIRSTNAME, LASTNAME)

VALUES (?, ?, ?, ?)';


if (is_bool($req)) trigger_error('i5_prepare error : '.i5_errormsg(),

E_USER_ERROR);

$newRecord = array(9000, 'Aura', 'walter', 'tribolet');

$result = i5_execute($req, $newRecord);

if (!$result) trigger_error('i5_execute error : '.i5_errormsg(), E_USER_ERROR);

print 'Walter adding sucessful. ';

$newRecord = array(9001, 'Aura', 'benoit', 'anquetin');

$result = i5_execute($req, $newRecord);

if (!$result) trigger_error('i5_execute error : '.i5_errormsg(), E_USER_ERROR);

print 'Benoit adding successful.';

See also

i5_prepare

i5_bind_param

i5_bind_result

i5_next_result

Moves pointer to next result.

bool i5_next_result ( resource Stmt )

Details

i5_next_result function is used with prepared requests (or stored procedures) likely to return several results.

It returns TRUE if another result is available and moves the pointer.

The next call to i5_fetch_xxx type function will read again a results set, it is impossible to return to the first results set.

If option I5_OPTIONS_AUTOMATIC_NEXT_RESULT wasn’t set to "1" during connection, you need to call i5_next_result() after i5_execute() call, to get the first result set.

Parameters

stmt i5_prepare returned request ID

Returns:






Example

Example

$stmt = i5_prepare('call EASYCOM/S_ORD_SUM'); if (is_bool($stmt)) trigger_error("i5_prepare error : ".i5_errormsg(), E_USER_ERROR); $ret = i5_execute($stmt); if (!$ret) trigger_error("i5_execute error : ".i5_errormsg(), E_USER_ERROR); $stmt2 = i5_next_result($stmt); if (is_bool($stmt2)) trigger_error("i5_next_result error : ".i5_errormsg(), E_USER_ERROR); $rec = i5_fetch_row($stmt2, I5_READ_NEXT); if (is_bool($rec))

trigger_error("i5_fetch_row error : ". i5_errormsg(), E_USER_ERROR); echo "First CLIENT : ";print_r($rec);echo " "; $ret = i5_free_file($stmt2); if (!$ret) trigger_error("i5_free_file error : ".i5_errormsg(), E_USER_ERROR); $ret = i5_free_file($stmt); if (!$ret) trigger_error("i5_free_file error : ".i5_errormsg(), E_USER_ERROR);

See also

i5_prepare

i5_execute

i5_affected_rows

Returns allocated lines number of last SQL INSERT, UPDATE and DELETE type operation.

int i5_affected_rows ( resource connection )

Details

Returns last request UPDATE, DELETE or INSERT type modified, deleted, inserted total lines number. It may be a parameterized (i5_execute) or a simple (i5_query).

i5_affected_rows function operates only on requests witch modify table. To retrieve SELECT request returned lines number, it is better to use i5_num_rows request.

In case of invalid last request, function returns –1.

Warning! i5_affected_rows function must be called immediately after (i5_query or i5_execute) request is performed.

Parameters


Returns: lines number (integer) or –1 in case of invalid request.

Example

$query = "INSERT INTO Cities2 SELECT * FROM Cities WHERE Code LIKE

?";


$req = i5_prepare($query);


/* Variable inserting */

$code = 'A%';

i5_bind_param($req, "s", $code);

/* Request execution */





} printf("Lines inserted: %d\n", i5_affected_rows($req));

/* Process closing*/

i5_close($req);

}

See also

i5_num_rows

i5_free_query

Frees SQL request result.

bool i5_free_query ( resource query )

Details

Removes a query type resource (i5_query or i5_execute) from memory

i5_free_query needs only to be called if you fear that your script requires too much memory, when a request returns very large results or if a large requests number are processed and may overload the web server memory. Its use is recommended as cleaner.

All memory resources required by a script are freed as the script ended.

Parameters

query Request ID







Example

$sql = "SELECT * FROM BIGTABLE"; $query = i5_query($sql); ... $res = i5_free_query($query); ...

See also

i5_query

i5_execute

i5_free_file

Fetching & Setting data

i5_num_rows

Returns lines number from a results set.

int i5_num_rows ( resource result/query )

Details

Retrieves lines number in results set. This command is available only to SELECT requests or file opened with i5_open.

To retrieve lines number involved with an INSERT, UPDATE or DELETE request, use i5_affected_rows function.

Parameter

result File or request ID

Returns lines number in case of success or FALSE if it fails.

Error returned




Example

$sql = 'SELECT CNOM, CVILLE FROM EASYCOM/P$CLIENT ORDER by CCODE ';

$result = i5_query($sql);

if (is_bool($result)) trigger_error("i5_query error : ".i5_errormsg(),

E_USER_ERROR);

if ($result) {

/* Find out lines number in results set */

$nb_lines = i5_num_rows($result);

printf("Results set has %d lines. ", $nb_lines);

$obj = i5_fetch_object($result);

printf("%s (%s) ", $obj->CNOM, $obj->CVILLE);

}

See also

i5_affected_rows

i5_fetch_row

i5_fetch_arrays

i5_fetch_assoc

i5_fetch_object

Each of these functions fetch a result row from a result set or a file, and returns the data in various formats.

array i5_fetch_row ( resource result, int option )

array i5_fetch_array ( resource result, int option )

array i5_fetch_assoc ( resource result, int option )

object i5_fetch_object ( resource result, int option )

Details

i5_fetch_xxxx functions move the pointer according to the specified option, read the data from the record set or file, and fill up the result array.

To change the current cursor position in the result set or file, use functions i5_seek or i5_data_seek,before to fetch the row.

Warning: i5_fetch_xxx() does not read blob fields. See i5_getblob function.

Parameter

result Result set or Open file ID

option Cursor movement option.

Valid options are:

I5_READ_NEXT Read next record, or the record requested by a previous call to i5_seek() or i5_data_seek(). If the previous function call for the result set or the file, was i5_seek() or i5_data_seek(), then i5_fetch_xxxx reads the record requested by this previous function. Otherwise, the function reads the next record in the result set or file.

I5_READ_PREV Read previous record

I5_READ_FIRST Read the first record

I5_READ_LAST Read the last record

I5_READ_SAME Read the current record. Cursor position is not moved.

I5_READ_SEEK Read current record

Any attempt to read out of file limits will return NULL and create an error I5_ERR_BEOF type.

Returns:

Function i5_Fetch_xxx() return an array or FALSE in case of error.

The format of array returned varies with the called function:

i5_fetch_row Get a result row as an enumerated array.

I5_fetch_array Fetch a result row as an associative array, and numeric array.

i5_fetch_assoc Fetch a result row as an associative array.

i5_fetch_object Fetch a result row as an object.

Error returned






I5_ERR_PHP_GETPARAM 275 specific message

Example

/* Page selection and reading */



E_USER_ERROR);











}

echo ' i5_fetch_array : ';


$tab = i5_fetch_array($file, I5_READ_SEEK);

while ($tab) {

printf('%s (%s) : ', $tab['CPREN'], $tab['CNOM']);


$tab = i5_fetch_array($file, I5_READ_NEXT);

}



while ($tab) {



}

See also

i5_result

i5_getblob

i5_seek

i5_data_seek

i5_fetch_array

i5_fetch_arrays

i5_fetch_assoc

i5_fetch_object






Details




Parameter



Valid options are:








Returns:







Error returned







Example




E_USER_ERROR);











}




while ($tab) {




}



while ($tab) {



}

See also

i5_result

i5_getblob

i5_seek

i5_data_seek

i5_fetch_assoc

i5_fetch_arrays

i5_fetch_assoc

i5_fetch_object






Details




Parameter



Valid options are:








Returns:







Error returned







Example




E_USER_ERROR);











}




while ($tab) {




}



while ($tab) {



}

See also

i5_result

i5_getblob

i5_seek

i5_data_seek

i5_fetch_object

i5_fetch_arrays

i5_fetch_assoc

i5_fetch_object






Details




Parameter



Valid options are:








Returns:







Error returned







Example




E_USER_ERROR);











}




while ($tab) {




}



while ($tab) {



}

See also

i5_result

i5_getblob

i5_seek

i5_data_seek

i5_result

Gets one field of the result.

mixed i5_result ( resource result, int/string field )

Detail

i5_result returns a cell content. Argument may be field index or its name.

Opposite to fetch functions that fetch the full line, i5_result returns a current line cell value for the specified name or position field.

The field value is read from the current record fetched by a previous call to i5_fetch_xxx function.

Parameters

result Resource describing file or other record set.

field Integer or string identifying the field position or name.

Returns:

Field's contents in current record.





Example

$file = i5_open("EASYCOM/CLIENTS");

/* Searches for the first wholesaler name beginning with DU */ $seek = array("FAMILY" => "WHOLESALERS", "NAME" => "DU"); $ret = i5_seek($file, ">=", $seek);

/* Fetches all values */ $rec == i5_fetch_row($file, I5_READ_SEEK)

/* Fetches a single field */ $ca = i5_result($file, "CA");

See also

i5_fetch_array

i5_fetch_assoc

i5_fetch_row

i5_fetch_object

i5_getblob

i5_getblob

Fetches binary data's from BLOB field type.

string i5_getblob ( resource result, int Field_Index )

or

string i5_getblob ( resource result, string Field_Name )

Details

i5_getblob function applies to SELECT type (i5_query or i5_execute) requests containing one or more BLOB type fields.

In the same way that i5_result function reads a unique field value, i5_getblob function allows to fetch binary data's.

The blob field value is read from the current record fetched by a previous call to i5_fetch_xxx function.

If field name or position do not matches with BLOB type, i5_getblob returns FALSE.

Warning: to read a blob it is necessary to be in transaction. To write a blob, file must also be journalized.

Parameters

result File ID

position BLOB field index

namfield BLOB field name

Returns:

Returns string with BLOB binary chain or FALSE in case of fault.





I5_ERR_PHP_SPOOL_FILE_FOPEN 269 Internal Error on tempory file(x); code error : -1.

Example

$sql = "SELECT BLOB_COLUMN FROM BLOB_TABLE;";

$res = i5_query($sql);

$line = i5_fetch_row($res);

/* $line[0] contains blob ID */

$blob_data = i5_getblob($line[0], $res);

/* the blob can be displayed or processed */ …

See also

i5_setblob

i5_setblob

Writes binary data's in a BLOB type field.

bool i5_setblob ( resource result,

int position, string blob )

Details

Writes a characters chain containing binary data's in a type BLOB file.

This function only applies to parameterized requests resources and is used the same way as i5_setparam function.

Warning, a blob can only be read in a transaction. To write a blob, a journalized file is also required.

Parameters

stmt Parameterized request ID

position Parameter index

blob Binary chain content

Returns:






Example

$ret = i5_transaction(I5_ISOLEVEL_CHG);

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

/* Writing jpeg file content in blob */

$sql = "INSERT INTO easycom/s_employee (LASTNAME, FIRSTNAME, PHOTO, EMPNO,

PHONEEXT, HIREDATE, SALARY) VALUES (?,?,?, 999, '+033', '1974-04-14', 1000)";

$req_prepa = i5_prepare($sql);

if (is_bool($req_prepa))

trigger_error("i5_prepare error : ".i5_errormsg(), E_USER_ERROR);

$name = "DUPONT";

$prenom = "HENRY";

$URL = realpath("./")."\inconnu.jpg";

$file_image = fopen($URL, 'r');

$contents = fread($file_image, filesize($URL));

$ret0 = i5_setparam($req_prepa, 0, $name);

if (!$ret0) trigger_error("i5_setparam error : ".i5_errormsg(), E_USER_ERROR);

$ret1 = i5_setparam($req_prepa, 1, $prenom);

if (!$ret1) trigger_error("i5_setparam error : ".i5_errormsg(), E_USER_ERROR);

$ret2 = i5_setblob($req_prepa, 2, $contents);

if (!$ret2) trigger_error("i5_setblob error : ".i5_errormsg(), E_USER_ERROR);

$ret = i5_execute($req_prepa);

if ($ret)

echo "Blob writing successful. ";

else trigger_error("i5_execute error : ".i5_errormsg(), E_USER_ERROR);

$ret = i5_commit();

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

See also

i5_setparam

i5_getblob

i5_setparam

Allocates parameter to parameterized request.

bool i5_setparam ( resource result,

int position, mixed value)

Details

Request must be prepared with i5_prepare function.

i5_setparam function is an alternative to the i5_bind_param function (automatically linked). It allows explicit value allocation to a parameter.

Parameters

stmt i5_prepare prepared request ID

position parameter index (marker) in the request

value parameter allocated value






Example

$insert = 'INSERT INTO animals (id, race, name, weight) VALUES

(?, ?, ?, ?)';

$animals = array(0, 'cat', 'Mistinguette', 3.2);

if ($req) {


if ($result) {

print "Mistinguette adding successful.";

} i5_setparam($req, 3, "Minouche");

i5_setparam($req, 4, 3.8);


if ($result) {

print "Hercule adding successful.";

}

See also

i5_prepare

i5_execute

i5_bind_param

i5_getparam

Retrieves a request parameter or stored procedure value.

Mixed i5_getparam ( resource stmt, int position )

Details

i5_getparam function allows to retrieve an in/out type parameter value or an out stored procedure parameter prepared with (i5_prepare) and executed with (i5_execute).

It's an alternative to using automated linkage between parameters and PHP variables with i5_bind_param function.

Parameters

query i5_prepare returned request ID

position Parameter index (marker)

Returns:

Returns parameter value or FALSE in case it fails.





Example

$stmt = i5_prepare("CALL EASYCOM/S_ORD_SUM(?,?,?)"); if (is_bool($stmt)) trigger_error("i5_prepare error : ".i5_errormsg(), E_USER_ERROR); $res = i5_execute($stmt, array(1351)); if (!$res) trigger_error("i5_execute error : ".i5_errormsg(), E_USER_ERROR); // Taking into account that OP1 and STR2 are IN/OUT

$P0 = i5_getparam($stmt, 0); $P1 = i5_getparam($stmt, 1); $P2 = i5_getparam($stmt, 2);

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

See also

i5_prepare

i5_execute

i5_bind_param

i5_setparam

i5_bookmark

Returns the ID of the current record.

int i5_bookmark ( resource result/file )

Details

A bookmark is an ID (in fact the record number) allowing to mark the current record in order to be able to comeback to it later using i5_data_seek function.

Parameters


Returns: The ID of the current record that can be used with i5_data_seek() to position on this record again.





Example


/* Looking for MARTIN */

$seek = array("MARTIN"); /* Looking for martin pierre*/

//$seek = array("MARTIN ", "PIERRE"); $ret = i5_seek($file, "=", $seek); $rec = i5_fetch_row($file, I5_READ_SEEK); /* Set a bookmark on current record */

$dupont = i5_bookmark($file); [... others treatments on the file ...] /* Direct return to back to DUPONT record */

$ret = i5_data_seek($file, $dupont); $rec = i5_fetch_row($file, I5_READ_SEEK); print_r($rec);echo " ";

See also

i5_data_seek

i5_seek

i5_bind_param

Links up variables to request.

bool i5_bind_param ( resource stmt,


Details

i5_bind_param is used to link up PHP variables to prepared request with i5_prepare.

Variables order is linked to request markers order. That means that it is impossible to link the last marker without linking all variables, but linkage can be limited to the n firsts.

Variables must be referenced, with "&" sign in front.

Once linkage established, the variable remains associated until request (or script…) is closed.

Referenced variables feature is deprecated in the PHP5 and higher. Parameters

stmt i5_prepare request ID

&var1 (…) Variable to link name








Example


if ($conn) {

$req = i5_prepare($conn, "INSERT INTO Language VALUES (?, ?, ?)");

if ($req) {

$liaison = i5_bind_param($req, 'ssi', &$code, &$langue, &$population);

$code = "FRA";

$langue = "français";

$population = 60669000;

$res = i5_execute($req);

if ($res) {

echo "Inserting successful…"; } }

}

}

See also

i5_bind_result

i5_prepare

i5_execute

i5_setparam

i5_bind_result

Links up variables to results set.



or


mixed &var1 , string Filed_Name )

Details

i5_bind_result is used to associate result columns (file or request) to variables. When i5_fetch_xxx is called to read values, Easycom places the data's in the specified variables into the parameter(s) var1, ....

There are two possible syntaxes; the first refers to a variables list.

Variables order is linked to request column order. Then, it is impossible to link up on the last field without linking all others, but linkage can be limited to the n firsts.

Second syntax works as "couple", associating a variable to a field name. In this case the function must be called many times to associate many variables.

It is impossible to set a list first and after a field name.

Les variables must be referenced, with "&" sign in front.

Note: Notice that columns must be linked before calling i5_fetch_xxx. According to column value type, PHP variable type may be automatically modified.

A column may be associated or re-associated any time, even after partially reading the result. The new linkage applies with the next i5_fetch_xxx call.

Return: True if OK, false if failed.







Parameters

query/stmt i5_prepare prepared request ID

&var1 , &var2 variables to associate referenced list

&var variable to associate, in reference

namfield request field or associated file name

Returns TRUE if link is activate, FALSE in case it fails.

Example

$req = i5_prepare("SELECT Code, Name FROM Pays ORDER BY Name

LIMIT 5");






}

/* Associating variables to result */

$ret = i5_bind_result($query, $col1, $col2);




}

/* Values */


while (!is_bool($tabResult)) {

printf("%s %s ", $col1, $col2);


}

/* Request closing */

i5_free_query($req);

}

See also

i5_query

i5_prepare

i5_execute

i5_bind_param

i5_setparam

i5_seek

Moves current position to a specific record in file.

Syntax N° 1


int/string operator

[, array keyvalue ]


Syntax N° 2


int/string operator

[, int bookmark ] )

Details

This function moves result pointer to the record witch indexed values meet table specified parameters.

This function is typically used to search in a file according to a key (simple or composite). It locates the record that fills the specified requirement for a defined index.

See functions i5_range_from and i5_range_to to select a range of records.

i5_seek moves the pointer without reading the result, next call to i5_fetch_xxxx will return the line.

Parameters


operator Comparison operator. Position is set to first record satisfying the operator.

Operator can be specified as a symbolic or string value.

Symbolic value String value Description

I5_EQ "=" Equal

I5_GE ">" Greater than

I5_GT ">=" Greater or Equal

I5_LT "<" Less than

I5_LE "<=" Less or Equal

I5_FIRST "FIRST" First record: No key value is required.

I5_LAST "LAST" Last record: No key value is required.

I5_BOOKMARK "BOOKMARK" Go to record number

Keyvalue values of the keys to locate to. If the key is composed by multiple fields, each entry in array "keyvalue" contains the value for one field.

Last_field_len Length of the last field. When the key is composed by multiple fields, parameter "Last_field_len" represents the number of characters to consider for the last given field, when looking for the record.

If "Last_field_len" is omitted, the last given key field will be considered in its full size.

If "Last_field_len" has special value I5_ACTUAL_SIZE, the current contain size of the cell in "keyvalue" array, will be considered for the last field.

Returns:


Error returned








Example


/* Looking for MARTIN */ $seek = array("MARTIN"); /* Looking for martin pierre*/ //$seek = array("MARTIN ", "PIERRE"); $ret = i5_seek($file, "=", $seek); $rec = i5_fetch_row($file, I5_READ_SEEK); /* Set a bookmark on current record */ $dupont = i5_bookmark($file); [... others treatments on the file ...] /* Direct return to back to DUPONT record */

$ret = i5_data_seek($file, $dupont); $rec = i5_fetch_row($file, I5_READ_SEEK); print_r($rec);echo " ";

See also

i5_data_seek

i5_fetch_xxx

i5_match

i5_data_seek

Seeks to a specific record of the result.

bool i5_data_seek ( resource result, int Record_Number )

Details

i5_data_seek function moves internal result pointer associated to results set, presented as result ( open file or request ID), to Record_Number specified line.

If the result set comes from a file, it's an absolute record number that may not be record position.

If it's a request, it's the n th record in the result set.

Record_Number parameter is a numeric value, from 1 to number of rows in result set..

This function may be used with a result obtained from i5_query, i5_open or i5_execute.

Parameters

result i5 file resource.

record_number Number of the record to seek to, starting from 1.







Example


if (is_bool($query)) {

$rech = i5_data_seek($query, 1) // first record

$record = i5_fetch_row($query, I5_READ_SEEK)

(…)

}

See also

i5_seek

i5_match

Check if current record match the latest requested key value.

bool i5_match ( resource file

[, int key_fields_count ]


Details

The key value for the current record is compared to the key value provided to the latest i5_seek function call.

Parameters


key_fields_count When the access key is composed by multiple fields, "key_fields_count" represents the count of fields to consider when comparing the key values.

If "key_fields_count" is omitted, the size of the key given on the latest call to i5_seek will be applied.

last_field_len When the access key is composed by multiple fields, "last_field_len" represents the size to consider for the last key field, when comparing the key values.

If "last_field_size" is omitted, the size original size of the key field is applied.

Returns:

True if match, false otherwise.

Error returned





Example


/* Looking for MARTIN */ $seek = array("MARTIN"); /* Looking for martin pierre*/ //$seek = array("MARTIN ", "PIERRE"); $ret = i5_seek($file, "=", $seek); $rec = i5_fetch_row($file, I5_READ_SEEK); if (is_bool($rec))

trigger_error("i5_fetch_row error : ".i5_errormsg(), E_USER_ERROR);

$ret = i5_match($file); if ($ret) echo "Record found "; else echo "Record no found "; /* Set a bookmark on current record */ $dupont = i5_bookmark($file); [... others treatments on the file ...] /* Direct return to back to DUPONT record */ $ret = i5_data_seek($file, $dupont); if (!$ret)

trigger_error("i5_data_seek error : ".i5_errormsg(), E_USER_ERROR);

$rec = i5_fetch_row($file, I5_READ_SEEK); if (is_bool($rec))

trigger_error("i5_fetch_row error : ".i5_errormsg(), E_USER_ERROR); print_r($rec);echo " ";

See also

i5_seek

i5_fetch_xxx

Columns & parameters information

i5_num_fields

Get the numbers of fields for resource.

int i5_num_fields ( resource result/query )

Parameters


Returns:

Number of fields.




Example

$file = i5_open("EASYCOM/s_customer");

if (is_bool($file))

trigger_error("i5_open error : ".i5_errormsg(), E_USER_ERROR);

echo "s_customer file have ". i5_num_fields($file) . " fields";

i5_free_file($file);

See also

i5_info

i5_num_rows

i5_get_keys

Gets the number of each field composing the key.

array i5_get_keys ( resource file )

Parameters

fileHdl File handle returned by i5_open.

Returns:

An array with the number of each field that is composing the key, if the function succeeds.

False is returned in case of error. For getting the code and error message call i5_error function.

Example

$hdlFile = i5_open ("EASYCOM/SP_DET_OR", I5_OPEN_READWRITE); if (IS_BOOL($hdlFile)) trigger_error("i5_open error : ".i5_errormsg(),

E_USER_ERROR); $ret = i5_get_keys($hdlFile); if (IS_BOOL($ret)) trigger_error("i5_get_keys error : ".i5_errormsg(),

E_USER_ERROR); echo "Keys : ";print_r($ret);echo " ";

i5_list_fields

Gets list of fields for resource.

array i5_list_fields ( resource result/file )

Details

Returns an indexed table showing each file field name or SQL request. Table size allows knowing fields number. This number can be known directly using i5_num_fields function.

Parameters


Returns:

Array containing field names, in order.





Example

<?php


if ($conn) {

$res = i5_query("SELECT * FROM animals");

$fields = i5_list_fields($res);

$nb_fields = count($fields);

echo "ANIMALS table contains ".$nb_fields." columns.\n";

$fich = i5_open("EASYCOM/SP_CUST");

$fields = i5_list_fields($fich);

$nb_fields = count($fields);

echo "SP_CUST file contains ".$nb_fields." fields.";

}

See also

i5_field_name

i5_field_len

i5_field_scale

i5_field_type

i5_info

i5_field_len

Gets field length.

int i5_field_len ( resource result/file,

int/string field )

Parameters

result Resource describing file or other record set


Returns: Field's length.





Example

$result = i5_query("SELECT * FROM LATABLE");

$fields = i5_num_fields($result);

$lines = i5_num_rows($result);

echo "The table contains" . $fields . " columns and " . $lines .

" line(s)\n";

echo "Columns are as follow:\n";

for ($i=0; $i < $fields; $i++) {

$type = i5_field_type($result, $i);

$name = i5_field_name($result, $i);

$len = i5_field_len($result, $i);

echo $type . " " . $name . " " . $len. "\n";

}

See also

i5_field_name

i5_field_type

i5_field_scale

i5_info

i5_field_name

Get field name.

string i5_field_name ( resource result/file,

int field )

Details

i5_field_name function give the x file or request field name.

Parameters


filed Integer identifying the field position.






Example




echo "The table contains " . $fields . " columns and " . $lines

. " line(s)\n";


for ($i=0; $i < $fields; $i++) {





}

See also

i5_field_len

i5_field_scale

i5_field_type

i5_info

i5_field_type

Gets field type.

string i5_field_type ( resource result/file,

int/string field )

Details

Fields types are different by nature in I5 and PHP environment. To known an I5 exact field type use i5_info function and fetch ASTYPE key value in the returned table.

i5_field_type function returns a character chain containing the type.

This value may be: "int", "bool", "float", "string" or "blob".

Note:

To know AS400 field type, call i5_info function and fetch "ASTYPE" key:

$info = i5_info($res, "CODE");

echo "Type AS CODE " . $info["ASTYPE"];

Parameters

result Resource describing file or other record set .


Returns: Field's type string.






Example




echo "The table contains " . $fields . " columns and" . $lines .

" line(s)\n";


for ($i=0; $i < $fields; $i++) {





}

See also

i5_fied_name

i5_field_len

i5_field_scale

i5_info

i5_field_scale

Gets field scale - number of digits for numeric fields.

int i5_field_scale ( resource result/file,

int/string field )

Details

For real type fields (packed or zoned), returns decimal places.

If field is integer, function returns 0.

If it's not a numeric type field, function returns –1.

Note:

Similar information may be found using i5_info function retrieving "ASDEC" key:

$info = i5_info($res, "NUMERIC");

echo "Number of decimals " . $info["ASDEC"];

Parameters

result Resource describing file or other record set .


Returns: The number of digits of the field. If the field is not numeric, returns –1.





Example

$info = i5_info($res, "NUMERIC");

echo "Decimal place " . $info["ASDEC"];

$file = i5_open("EASYCOM/MATHS");

echo i5_field_scale($file, "TEXT"). " "; // -1

echo i5_field_scale($file, "INTEGER"). " "; // 0

echo i5_field_scale($file, "DEC10_2"). " "; // 2

See also

i5_fied_name

i5_field_len

i5_field_type

i5_info

i5_info

Gets information about the file/record.

array i5_info ( resource result/file,

[ int/string field ] )

Details

A direct functions set is available to find out about field main properties and file fields number:

i5_field_name for name,

i5_field_len for size,

i5_field_scale For decimal place,

i5_field_type For (PHP) type.

i5_num_fields Fields number

i5_info function allows getting additional information's, either at field level giving accurate index or field name or either at file level.

Defining an index or a field name as calling parameters, the following associative table is obtained:

PcType PC field type

PcLen PC field length

AsType Returns type name from the following list: CHAR, SHORT, LONG, FLOAT, DOUBLE, BIN, PACKED, ZONED, DATE or TIME.

AsLen AS side field length in byte

AsDec AS side decimal place

allowNull returns TRUE if field accepts NULL values

Name Field name

comment Field comment

heading1 First column header

heading2 Second column header

heading3 Third column header

varLen returns TRUE if field is of variable length

In lack of field name or position in calling parameters, an associated table is returned with the file following information's:

KEYNBR Keys number

FIELDNBR Fields number

UNIQUE Returns TRUE if key is unique

SELOMIT Returns TRUE if key is of SELECT/OMIT type

KEYED Returns TRUE if key is of KEY/ARRSEQ type

Parameters








Example

$res = i5_open("easycom/s_customer");

/* File information */

$info_file = i5_info($res);

echo "CLIENTS file have " . $info_file["KEYNBR"] ." keys. ";

/* Field information */

$info = i5_info($res, "ZIP");

echo "CODE type AS " . $info["AsType"] ." ";

echo "CODE comment " . $info["comment"] ." ";

if ($info["varLen"])

echo "CODE field length is variable";

See also

i5_field_len

i5_field_name

i5_field_type

i5_num_fields

i5_num_rows

data Queues

i5_dtaq_prepare

Opens a data queue with optional description.

ressource i5_dtaq_prepare ( string name, array description

[, int key]


Parameters

name The queue name.

description PHP-format program description.


key Key size - for keyed DataQ, value given in the KEYLEN parameter of the CRTDTAQ command


Returns:









I5_ERR_PHP_BAD_TYPE_KEYNAME 271 The name property n°-1 must be a string.

I5_ERR_PHP_ELEMENT_MISSING 304 An element of the array has a wrong type within function_name(type) function.


I5_ERR_PHP_BAD_DEF 305 You cannot define an occurence number; and an occurence reference for the same parameter -1.

I5_ERR_PHP_BAD_KEYNAME 306 Name x is not a property name for a program description



Example

/* Connection */

$Hdlcon = i5_connect($adresse,$user, $mdp, $jobName);

/* Open the DATA QUEUE */

$description = array("Name"=>"DATA", "Type"=>I5_TYPE_CHAR,

"Length"=>"50");

$data = i5_dtaq_prepare("*LIBL/DTAQ_FIFO", $description);

if ($data == false){

$erreur = i5_error();

print_r ($erreur);

}

$msg='';

$lecture = false;

/* Writing in the data queue */

if (isset($_POST["write"])) {

$donnees = $_POST["data"];

$ret = i5_dtaq_send($data, "", $donnees);

if ($ret) {

$msg="Ecriture faite";

}

}

/* reading of the data queue */

if (isset($_POST["read"])) {

$rec = i5_dtaq_receive($data);

if (is_bool($rec)) {


if ($erreur[0]==14) {

$msg="La Data Queue est vide";

} else {

print_r($erreur);

}

} else {

$lecture = true;

}

}

i5_dtaq_send

Puts data to the data queue.

bool i5_dtaq_send ( resource queue, string key ,

mixed data )

Parameters

queue Resource received from dtaq_open.

key Key value to look for.

data Data to put into the queue.

The data should conform to the description format, and can be either in flat array or key->value pair array.







I5_ERR_PHP_NOT_DTAQ_KEY 313 No key defined.

Example

/* Connexion */


/* Ouverture de la DATA QUEUE */


"Length"=>"50");




print_r ($erreur);

}

$msg='';

$lecture = false;

/* Ecriture de la data queue */




if ($ret) {


}

}

/* Lecture dans la data queue */





if ($erreur[0]==14) {


} else {

print_r($erreur);

}

} else {

$lecture = true;

}

}

i5_dtaq_receive

Reads data from the data queue.

mixed i5_dtaq_receive ( resource queue,

[, string/int operator, string key ]

[, int timeout])

Parameters

queue Resource received from dtaq_open

operator "EQ"

"GT"

"LT"

"GE"

"LE"

key Key value to look for

timeout Timeout value in seconds

Returns:

False if could not read because of error or timeout, the data read from the queue otherwise.





Example

/* Connexion */


/* Ouverture de la DATA QUEUE */


"Length"=>"50");




print_r ($erreur);

}

$msg='';

$lecture = false;

/* Ecriture de la data queue */




if ($ret) {


}

}

/* Lecture dans la data queue */





if ($erreur[0]==14) {


} else {

print_r($erreur);

}

} else {

$lecture = true;

}

}

i5_dtaq_close

Free program resource handle.

bool i5_dtaq_close ( resource queue )

Parameters

queue Resource received from dtaq_open.






Example

Example 1:

$description = array("Name" => "DATA", "TYPE" => I5_TYPE_CHAR,

"length" => 50);

$dtaqHdl_KEY = i5_dtaq_prepare("EACDEMO/DTAQ_KEY",

$description);

$ret = i5_dtaq_put($dtaqHdl_KEY, "mykey", "the dataqueue test

data");

var_dump($ret);

if(!$ret) var_dump(i5_error());

$ret = i5_dtaq_read($dtaqHdl_KEY, "EQ", "mykey");

var_dump($ret);

Example 2:

$descriptionC = array("DSName"=>"PS", "DSParm" =>array(

array("Name"=>"PS1", "Type"=>I5_TYPE_CHAR, "Length"=>"10"),

array("Name"=>"PS2", "Type"=>I5_TYPE_PACKED, "Length"=>"10.4"),

array("Name"=>"PS3", "Type"=>I5_TYPE_CHAR, "Length"=>"10")

)

);

$dtaqHdl_KEY = i5_dtaq_prepare("EACDEMO/DTAQ_KEY",

$descriptionC, 10);

$parameter = array("PS1"=>"test1", "PS2"=>13.1415,

"PS3"=>"test2");

$key = "abcd";

$ret = i5_dtaq_put($dtaqHdl_KEY, $key, $parameter);

var_dump($ret);

$ret = i5_dtaq_read($dtaqHdl_KEY, "EQ", $key);

var_dump($ret);

Data Areas

i5_data_area_create

Creates data area of given size.

bool i5_data_area_create ( string name, int size


Parameters

name Name of the data area

size Size in bytes of the data area

connection Connection – result of i5_connect

Return:








Example

$ret = i5_data_area_create ("QTEMP/MYDTA" , 50); if (!$ret) trigger_error("i5_data_area_create error : ".i5_errormsg(),

E_USER_ERROR); $ret = i5_data_area_write ("QTEMP/MYDTA" , "MSG:Hello Word"); if (!$ret) trigger_error("i5_data_area_write error : ".i5_errormsg(),

E_USER_ERROR); $ret = i5_data_area_read ("QTEMP/MYDTA", 1, 4); if (!$ret) trigger_error("i5_data_area_read error : ".i5_errormsg(),

E_USER_ERROR); echo "Type data: $ret " ; $ret = i5_data_area_read ("QTEMP/MYDTA"); if (!$ret) trigger_error("i5_data_area_read error : ".i5_errormsg(),

E_USER_ERROR); echo "Message: $ret "; $ret = i5_data_area_delete ("QTEMP/MYDTA"); if (!$ret) trigger_error("i5_data_area_delete error : ".i5_errormsg(),

E_USER_ERROR);

i5_data_area_read

Reads data from the area.

string i5_data_area_read ( string name,

[, int offset, int length]


Parameters

name Name of the data area.

Offset Offset for the data.

Length Length of the data to read, -1 means whole area.

Connection Connection – result of i5_connect

If not offset is specified, all the area is read.

Returns: String data if read successful, false if read failed (including when offset is wrong).






I5_ERR_PHP_DATAREA_READ 296 The command returned an error: x.


I5_ERR_PHP_BAD_DTAARA_LENGTH 315 Data area x should be from -1 to -2

Example


E_USER_ERROR); $ret = i5_data_area_write ("QTEMP/MYDTA" , "MSG:Hello Word"); if (!$ret) trigger_error("i5_data_area_write error : ".i5_errormsg(),




E_USER_ERROR);

i5_data_area_write

Writes data to the area.

bool i5_data_area_write ( string name, string value

[, int offset, int length]


Parameters

Name Name of the data area.

Value Value to write.

Offset Offset for the data.

Length Length of the data to read.


If not offset is specified, all the area is written. If value is shorter than length it is padded to the length. If it's longer it is truncated.

Returns:









Example


E_USER_ERROR); $ret = i5_data_area_write ("QTEMP/MYDTA" , "MSG:Hello Word");

if (!$ret) trigger_error("i5_data_area_write error : ".i5_errormsg(),




E_USER_ERROR);

i5_data_area_delete

Deletes the data area.

bool i5_data_area_delete ( string name,


Parameters

name Name of the data area.


Return:









Example


E_USER_ERROR);

$ret = i5_data_area_write ("QTEMP/MYDTA" , "MSG:Hello Word"); if (!$ret) trigger_error("i5_data_area_write error : ".i5_errormsg(),




E_USER_ERROR);

Jobs

i5_job_list

Open active job list.

resource i5_job_list ( [ array elements [,

resource connection]])

Parameters

elements JobName, JobUser, JobNumber, JobType, Direction (default is current job)


Use i5_job_list_read function to retrieve the job entries from this handle.

Returns:

The resource for fetching job list if OK and false if failed.









Example

$HdlSpl = i5_job_list(array(I5_USERNAME => "QPGMR"));

if (is_bool($HdlSpl))

trigger_error("i5_job_list error : ".i5_errormsg(), E_USER_ERROR);

$continue = true;

while ($continue){

$ret = i5_job_list_read($HdlSpl);

if (is_bool($ret)){

$continue = false;

break;

}

if (count($ret) > 0){

print_r($ret[1]);echo " ";

} else {

echo "Nothing to display ";

}

}

$ret = i5_job_list_close($HdlSpl);

if (!$ret)

trigger_error("i5_job_list_close error : ".i5_errormsg(),

E_USER_ERROR);

See also

Active Job (i5_job_list) array elements constants

i5_job_list_read

Get an array for an active job entry.

array i5_job_list_read ( resource list )

Parameters

list Resource returned by i5_job_list function

Returns: Array with the job entry element if OK, false if failed.

I5_ERR_BEOF 14 End or begin of file reached





Example




$continue = true;

while ($continue){


if (is_bool($ret)){

$continue = false;

break;

}



} else {


}

}


if (!$ret)


E_USER_ERROR);

i5_job_list_close

Close handle received from i5_job_list().

bool i5_job_list_close ( resource list )

Parameters

handle Job list handle as returned by i5_job_list()






Example




$continue = true;

while ($continue){


if (is_bool($ret)){

$continue = false;

break;

}



} else {


}

}


if (!$ret)


E_USER_ERROR);

Active Job (i5_job_list) array elements constants

I5_JOB_ACT_JOB_STS

I5_JOB_ALW_MULTI_THREADS

I5_JOB_ACT_ENDJOB_STS

I5_JOB_BRKMSG

I5_JOB_CANCEL_KEY

I5_JOB_CCSID

I5_JOB_CNTRYID

I5_JOB_USRPRF

I5_JOB_COMPLETION_STS

I5_JOB_POOL_ID

I5_JOB_CHAR_ID_CTRL

I5_JOB_PROCESS_UNIT_TIME

I5_JOB_PROCESS_UNIT_TIME_DB

I5_JOB_DATETIME_ACTIVE

I5_JOB_DATETIME_IN

I5_JOB_DATETIME_SCHED

I5_JOB_DATETIME_JOBQ

I5_JOB_DATFMT

I5_JOB_DATSEP

I5_JOB_DBCS_CAP

I5_JOB_DDM_HANDLE

I5_JOB_DFTWAIT

I5_JOB_DEVRCYACN

I5_JOB_DEVNAME

I5_JOB_DFTCCSID

I5_JOB_DECFMT

I5_JOB_DATETIME_END

I5_JOB_ENDSEV

I5_JOB_ENDSTS

I5_JOB_EXITKEY

I5_JOB_FUNC_NAME

I5_JOB_FUNC_TYPE

I5_JOB_SIGNED_JOB

I5_JOB_GRPPRFNAME

I5_JOB_GRPPRFNAME_SUP

I5_JOB_INQMSGRPLY

I5_JOB_ACCOUNT_CODE

I5_JOB_DATE

I5_JOB_DESC_NAME

I5_JOB_QUEUE_NAME

I5_JOB_QUEUE_PTY

I5_JOB_SWITCHES

I5_JOB_JOBMSGQFL

I5_JOB_JOBMSGQ_SIZE

I5_JOB_USRID

I5_JOB_USRID_SETTING

I5_JOB_END_REASON

I5_JOB_LOG_PENDING

I5_JOB_TYPE_ENHANCED

I5_JOB_LANGID

I5_JOB_LOGLVL

I5_JOB_LOGCLPGM

I5_JOB_LOGSEV

I5_JOB_LOGTEXT

I5_JOB_MODE_NAME

I5_JOB_MAX_PROC_UNIT_TIME

I5_JOB_MAX_TMP_STG_K

I5_JOB_MAX_THREADS

I5_JOB_MAX_TMP_STG_M

I5_JOB_MEM_POOL_NAME

I5_JOB_MSGRPL

I5_JOB_INTERACTIVE_TRS

I5_JOB_DB_LCKWAIT

I5_JOB_ MCH_LCKW

I5_JOB_NONDB_LCKW

I5_JOB_AUX_IOREQ

I5_JOB_OUTQ_NAME

I5_JOB_OUTQ_PTY

I5_JOB_PRTTEXT

I5_JOB_PRTDEVNAME

I5_JOB_PURGE

I5_JOB_PRD_RETCODE

I5_JOB_PROG_RETCODE

I5_JOB_PENDING_SGNSET

I5_JOB_PROCESS_ID

I5_JOB_RESPONSE_TIME

I5_JOB_RUNPTY

I5_JOB_ROUTING_DATA

I5_JOB_STRSEQ

I5_JOB_STS_MSGHDL

I5_JOB_STS_JOBQ

I5_JOB_SBMJOB

I5_JOB_SBMMSGQ

I5_JOB_SBSD

I5_JOB_SYSPOOLID

I5_JOB_SPCLENV

I5_JOB_SGNBLK_MASK

I5_JOB_SGNSTS

I5_JOB_SVRTYPE

I5_JOB_SPLFILE_ACTION

I5_JOB_TIMSEP

I5_JOB_TIMESLICE

I5_JOB_TIMESLICE_END

I5_JOB_TMPSTGK

I5_JOB_TIME_DB_LCKW

I5_JOB_TIME_MCH_LCKW

I5_JOB_TIME_NONDB_LCKW

I5_JOB_THREADCNT

Spools

i5_spool_list

Create an spool file lists, of certain output queue or for all queues.

resource i5_spool_list ( [ array description,

resource connection])

Parameters

description The data by which the spool files will be filtered, array with following keys:

- username - username that created the job

- outq - qualified name for the output queue containing the spool file

- userdata - the user-supplied key data for the spool file

All keys are optional and can be provided together


Returns: Resource if OK, false if failed







I5_ERR_PHP_UNAVIABLE_PASE 298 This feature is not available on i5/OS environment.


Example

/* Connexion */ $Hdlcon = i5_connect($adresse,$user, $mdp, $jobName); $msg=''; $lecture = false;

/* Ecriture dans la data area */ if (isset($_POST["display"])) { $donnees = $_POST["data"]; $ret = i5_data_area_write("EASYCOM/MYDTA", $donnees); if ($ret) { $msg="Ecriture faite"; } } else { $HdlSpl = i5_spool_list(array(I5_USERNAME=>"QPGMR")); if (is_bool($HdlSpl)){ $ret = i5_errno(); print_r($ret); }

i5_spool_list_read

Gets spool file data from the queue.

array i5_spool_list_read

(

resource spool_list )

Detail

The data will be formated using SPLF0300 format. See following link for more details:

http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp?topic=/apis/QUSLSPL.htm

Parameters

Spool_list resource received from i5_spool_list

Returns: Next spool file data array in the list, or false if queue is empty.






Example

while ($continue){ $ret = i5_spool_list_read($HdlSpl); if (is_bool($ret)){ $continue = false; break; }

i5_spool_list_close

Free spool list resourse.

void i5_spool_list_close ( resource spool_list )

Parameters

queue resource received from i5_spool_list

Returns:






i5_spool_get_data

Get the data from the spool file.

string i5_spool_get_data ( string spool_name,

string jobname,

int job_number,

string username,

int spool_id

[, string filename]


Parameters

Spool_name The spool file name

Job_name The name of the job that created the file

Job_number The number of the job that created the file

Username The username of the job that created the file

Spool_id ID of the spool file in the queue (as returned by outq_read)

filename IFS filename to store the data. If not provided, the data is returned as string

IF Easycom server and WEB server are on the same machine, *LOCAL can be specify to not use IFS fonctionnalities of Easycom and increase performances.

In this case the function returns the data of the spool

Returns: String if no file name passed as parameter, false if function failes








User spaces

i5_userspace_create

Creates a new user space object.

bool i5_userspace_create ( Array Properties


Parameters

properties I5_INITSIZE – The initial size of the user space being created. This value must

be from 1 byte to 16, 776, 704 bytes.

I5_DESCRIPTION – user space text description

I5_INIT_VALUE – The initial value of all bytes in the user space.

I5_EXTEND_ATTRIBUT – extended attribute. The extended attribute must be a

valid *NAME. For example, an object type of *FILE has an extended attribute of

PF (physical file), LF (logical file), DSPF (display file), SAVF (save file), and so

on.

I5_AUTHORITY – The authority you give users who do not have specific private

or group authority to the user space

I5_LIBNAME – Library name where the user space is located

I5_NAME – User space name (10 char max)











Example

$property = array( I5_INITSIZE=>10, I5_DESCRIPTION=>"User space created by PHP", I5_INIT_VALUE=>"A", I5_EXTEND_ATTRIBUT=>"wal", I5_AUTHORITY=>"*ALL", I5_LIBNAME=>"QTEMP", I5_NAME=>"USERSPACE" );

$ret = i5_userspace_create($property); if (!$ret) trigger_error("i5_userspace_create error : ".i5_errormsg(),

E_USER_ERROR);

i5_userspace_prepare

Opens a user space and prepares it to be run.

resource i5_userspace_prepare ( string name,

array description


Parameters

name User space name in library/object format

description PHP-format program description.















Example

$parameter = Array( "filler0"=>"AAAA", "generic"=>10, "filler"=>"BBB", "outputsize"=>100, "offsetInput"=> 0 ); $parmOut = array("filler0"=>"filler0", "filler"=>"filler", "generic"=>"generic",

"outputsize"=>"outputsize", "offsetInput"=>"offsetInput"); $UspcHdl = i5_userspace_prepare("qtemp/USERSPACE", $description); if (is_bool($UspcHdl)) trigger_error("i5_userspace_prepare error :

".i5_errormsg(), E_USER_ERROR); $ret = i5_userspace_put($UspcHdl, $parameter); if (!$ret) trigger_error("i5_userspace_put error : ".i5_errormsg(),

E_USER_ERROR); $ret = i5_userspace_get($UspcHdl, $parmOut); if (!$ret){ trigger_error("i5_userspace_get error : ".i5_errormsg(), E_USER_ERROR); } else { echo "Filler0 : ".$filler0." "; echo "generic : ".$generic." "; echo "filler : ".$filler." "; echo "outputsize : ".$outputsize." ";

echo "offsetInput : ".$offsetInput." ";

} $ret = i5_userspace_close($UspcHdl);

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

i5_userspace_get

Retrieve user space data.

bool i5_userspace_get ( resource user_space,

array params

[, int Offset])

Parameters

User_space User Space resource returned by i5_userspace_prepare

params Parameters according to description. If params is an associative array, it associates the name of virtual fields to get, with the PHP variable to fill up with the value.

If given as flat array, then parameters are assigned in order

Offset Offset from the beginning of the user space, of the data to get.







Example




E_USER_ERROR); $ret = i5_userspace_get($UspcHdl, $parmOut); if (!$ret){ trigger_error("i5_userspace_get error : ".i5_errormsg(), E_USER_ERROR); } else { echo "Filler0 : ".$filler0." "; echo "generic : ".$generic." "; echo "filler : ".$filler." "; echo "outputsize : ".$outputsize." "; echo "offsetInput : ".$offsetInput." ";

} $ret = i5_userspace_close($UspcHdl);

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

i5_userspace_put

Add user space data

bool i5_userspace_put ( resource user space,

array params

[, int Offset] )

Parameters

User space User Space resource opened by i5_userspace_prepare

params Parameters according to description. If params is an associative array, it associates the name of virtual fields to get, with the PHP variable to fill up with the value.

If given as flat array, then parameters are assigned in order

Offset Offset from the beginning of the user space, of the data to get.








Example




E_USER_ERROR); $ret = i5_userspace_get($UspcHdl, $parmOut); if (!$ret){ trigger_error("i5_userspace_get error : ".i5_errormsg(), E_USER_ERROR); } else { echo "Filler0 : ".$filler0." "; echo "generic : ".$generic." "; echo "filler : ".$filler." "; echo "outputsize : ".$outputsize." "; echo "offsetInput : ".$offsetInput." "; }

$ret = i5_userspace_close($UspcHdl);

if (!$ret) trigger_error("i5_userspace_close error : ".i5_errormsg(),

E_USER_ERROR);

Objects

i5_objects_list

Open an object list.

resource i5_objects_list ( string library

[, string name, string type ]


resource i5_objects_list ( string library [, string name [,

string type [, resource connection

]]] )

Parameters

library Library name. The following special values is allowed : *ALL, *ALLUSR, *CURLIS(I5_CURLIB), *LIBL, *USRLIBL

Name Name of objects to read.

The value can be a simple name, a generic name, or the special values of *ALL, *ALLUSR, or *IBM, default is "*ALL".

Type Object type to fetch (*ALL or I5_ALL_OBJECTS for all)


Returns: Resource for fetch if everything is OK, false on error.

Error returned






Example

$HdlList = i5_objects_list('EASYCOM', 'S*', '*FILE');

if (is_bool($HdlList)) trigger_error('i5_objects_list error : '.i5_errormsg(),

E_USER_ERROR);

$count = 0;

while($list = i5_objects_list_read($HdlList)){

print_r($list);echo ' ';

$count ++;


}

$ret = i5_objects_list_close($HdlList);

if (!$ret) trigger_error('i5_object_list_close error : '.i5_errormsg(),

E_USER_ERROR);

i5_objects_list_read

Get an array for an object list entries.

array i5_objetcs_list_read ( resource list )

Parameters

list Resource returned by i5_objects_list

Returns: Array with the object element if OK; false if failed. Field descriptions.

Error returned






Example



E_USER_ERROR);

$count = 0;



$count ++;


}



E_USER_ERROR);

i5_objects_list_close

Close handle received from i5_ objects_list ().

bool i5_objects_list_close ( resource list )

Parameters

handle Object list handle as returned by i5_ objects_list ()


Error returned





Example



E_USER_ERROR);

$count = 0;



$count ++;


}



E_USER_ERROR);

Job logs

i5_jobLog_list

Opens job log.

resource i5_jobLog_list ( [array elements,

resource connection])

Parameters

elements JobName, JobUser, JobNumber, MaxMessage, Direction (default is current job)


Use i5_jobLog_list_read function to retrieve the job entries from this handle.

Returns: The resource for fetching job log list if OK and false if failed.












Example

/*Get job informations given in the request parameters*/

$jobName = $_POST["jobName"];

$userName = $_POST["userName"];

$jobNumber = $_POST["jobNumber"];

$HdlJob = i5_jobLog_list(array(I5_JOBNAME=>$jobName,

I5_USERNAME=>$userName, I5_JOBNUMBER=>$jobNumber));

if (is_bool($HdlJob)){

$ret = i5_error();

print_r($ret);

} else {

$continue = true;

while($continue) {

$data = i5_jobLog_list_read($HdlJob);

if (is_bool($data)){

if (i5_errno() != 14){

$ret = i5_error();

print_r($ret);

}

break;

} else {

echo " - ".$data[I5_LOBJ_MSGDTA]." ";

if (isset($data[I5_LOBJ_MSGHLP]))

echo $data[I5_LOBJ_MSGHLP]." ";

}

}

}

i5_jobLog_list_close($HdlJob);

See also

Job Log Constants (i5_jobLog_list) array elements constants

i5_jobLog_list_read

Get an array for a job log entry .

array i5_jobLog_list_read ( resource list )

Parameters

list Resource returned by i5_jobLog_list function

Returns: Array with the message element if OK, false if failed.






Example








$ret = i5_error();

print_r($ret);

} else {

$continue = true;

while($continue) {



if (i5_errno() != 14){

$ret = i5_error();

print_r($ret);

}

break;

} else {




}

}

}


i5_jobLog_list_close

Close handle received from i5_jobLog_list().

bool i5_jobLog_list_close ( resource list )

Parameters

list Job list handle as returned by i5_jobLog_list()






Example








$ret = i5_error();

print_r($ret);

} else {

$continue = true;

while($continue) {



if (i5_errno() != 14){

$ret = i5_error();

print_r($ret);

}

break;

} else {




}

}

}


Job Log Constants (i5_jobLog_list) array elements constants

I5_LOBJ_MESSAGE_SEVERITY

I5_LOBJ_MESSAGE_IDENTIFIER

I5_LOBJ_MESSAGE_TYPE

I5_LOBJ_MESSAGE_FILENAME

I5_LOBJ_MESSAGE_FILELIBRARY

I5_LOBJ_DATASENT

I5_LOBJ_TIMESENT

I5_LOBJ_TIMESENT_MICRO

I5_LOBJ_ALERTOPT

I5_LOBJ_RPLDATA1

I5_LOBJ_MSG

I5_LOBJ_MSGDTA

I5_LOBJ_MSGHLP

I5_LOBJ_MSGHLPDTA

I5_LOBJ_MSGHLPDTAFMT

I5_LOBJ_DFTRPLY

I5_LOBJ_SNDNAME

I5_LOBJ_SNDTYPE

I5_LOBJ_SNDPGM

I5_LOBJ_SNDMOD

I5_LOBJ_SNDPROC

I5_LOBJ_RCVTYPE

I5_LOBJ_RCVPROG

I5_LOBJ_RCVMOD

I5_LOBJ_RCVPROC

I5_LOBJ_MSGFILE

I5_LOBJ_PROBLEMID

I5_LOBJ_RPLYSTS

I5_LOBJ_RQSSTS

I5_LOBJ_RQSLVL

I5_LOBJ_TXTCCSID

I5_LOBJ_DATACCSID

Error management

i5_errno

Returns last error number.

int i5_errno ( [resource connection] )







Details

Use i5_errormsg function to get error message.

Use i5_error to get full error information's (number, category, message and detail).

Code N° Description

I5_ERR_OK 0 No error.

I5_ERR_ERROR 1 Error occurred

I5_ERR_TOOMUCHOPENFILE 2 Too many open files


I5_ERR_INVALIDPTR 4 Invalid pointer (handle); specific message

I5_ERR_FILENOTFOUND 5 File not found

I5_ERR_FIELDNOTFOUND 6 Field not found

I5_ERR_INVALIDFIELDNBR 7 Field number invalid

I5_ERR_INVALIDKEYLEN 8 Wrong key length

I5_ERR_INVALIDKEYNBR 9 Wrong key field number

I5_ERR_NOTENABLETOUPDATE 10 File not allowed to be changed

I5_ERR_INVALIDOPENMODE 11 File open mode not valid for operation

I5_ERR_RECORDNOTFOUND 12 Record not found

I5_ERR_RECORDLOCKED 13 Record locked


I5_ERR_FILELIMITS 15 Reads out of the file (before or after EOF)

I5_ERR_NOTCONNECTED 16 Not connected

I5_ERR_INVALIDSEQ 17 Operation sequence not valid

I5_ERR_NORANGESET 18 Range not defined

I5_ERR_NOLINKDEFINED 19 Link not defined

I5_ERR_NOCURRENTRECORD 20 No current record

I5_ERR_NULLNOTALLOWED 21 Null operation not applicable (field does not support nulls)

I5_ERR_BADSESSION 22 AS/400 session not valid

I5_ERR_WRONGLOGIN 23 Bad login user or password

I5_ERR_NOTENOUGHRIGHTS 24 User rights problem

I5_ERR_INVALIDTYPE 25 INVALID TYPE

I5_ERR_INVALIDINFO 26 Info variable height not enough

I5_ERR_NOTTYPEPROPERTY 27 Bad property ID

I5_ERR_RECORDCHANGED 28 The record has changed before update

I5_ERR_ALLREADYINTRAN 29 Allready in a transaction (nested transaction are not supported)

I5_ERR_NOTINTRAN 30 Not in a transaction

I5_ERR_INCORRECTVALUE 36 unable to set the value (out of range; ...)

I5_ERR_PARAMNOTFOUND 37 Requested parameter does not exist in the description.

I5_ERR_ENDOFOCC 38 Number of occurences greater than the maximum set in the description.

I5_ERR_DESC_UNEXP 39 Unexpected error while processing description

I5_ERR_DQDESC_UNSUPP 40 Unsupported description for a data queue













I5_ERR_PHP_BAD_LEN_PROP 266 The length of the property x is too large; -2 instead of -3 max.

I5_ERR_PHP_LIST_PROP 267 This element 0¡ is not accepted.


I5_ERR_PHP_API_LENGTH 270 The length of element -1 of parameter is too big (max : -2).


I5_ERR_PHP_BOOKMARK 272 Bookmark value expected for this operator

I5_ERR_PHP_NOT_BOOKMARK 273 Bookmark value unexpected for this operator




I5_ERR_PHP_PARAM_DESC 277 specific message

I5_ERR_PHP_BLOBSIZE 278 the blob size received(-1) is different of the announced size(-2).

I5_ERR_PHP_SEEK_FIRSTLAST 279 Bookmark value expected for this operator

I5_ERR_PHP_PROPERTY_NUMBER 280 This(-1) property number is not valid.


I5_ERR_PHP_BAD_ADDNEW_CST 282 The only constant accpeted are I5_ADDNEW_NOCLEAR or I5_ADDNEW_CLEAR.

I5_ERR_PHP_NOT_RPIVATE_CONNECTION 283 The restore connection is not allowed.







I5_ERR_PHP_EMPTY_ARRAY 291 Internal error; please contact Aura Equipement; error number 291

I5_ERR_PHP_NO_KEYNAME 292 Unspecified name for array item -1.



I5_ERR_PHP_COMMAND_ERROR 295 The command returned an error: x.











I5_ERR_PHP_BAD_PROG_NAME 311 Program not found.

I5_ERR_PHP_AS400_MESSAGE 312 Internal error; please contact Aura Equipement; error number 312




I5_ERR_PHP_EMPTY_PCML 316 PCML can not be empty



Parameters


Returns last error number or FALSE if no error occurs.

Example


if($query == FALSE){

echo "SQL error code: " . i5_errno($query) . " ";

echo "Error message: " . i5_errormsg($query) . " ";}

/* Connection test */

$conn = i5_connect("MYAS","USER","PASSWORD");

if ($conn == FALSE) {

$err = i5_error();

switch ($err["cat"]) {

case I5_CAT_TCPIP:

echo "TCP/IP problem – Connection not possible";

exit;

case I5_CAT_INTERNAL:

echo " Easycom error - Connection not possible ";

}

echo "error number". i5_errno() . " ";

echo "error message". i5_errormsg() ." ";

}

/* File edition test */

$edition = i5_edit($file);

if ($edition == FALSE) {

switch (i5_errno()) {

case I5_ERR_INVALIDOPENMODE:

echo "Opens file in writing to enable modifation";

case I5_ERR_RECORDNOTFOUND:

echo "Points a record before modification";

case I5_ERR_RECORDLOCKED:

echo "Locked record...";

}

}

/* Command test */

$ret = i5_cmd("NB=CHAR(20); RTVSYSVAL SYSVAL(QSRLNBR) RTNVAR(&NB)");

if ($ret) { // correct syntax


if ($res == 0) {...} // correct execution

else {echo "Command provoked error ". $res;}

else {

echo "Check command syntax";

}

/* SQL request test */




echo "Error message: " . i5_errormsg($query) . " ";

}

}

See also

i5_errormsg

i5_error

i5_error

Retrieves error information for last action that was executed.

bool i5_error ( [resource connection] )

Details

This is the function that allows error detailed analysis. It returns an associative indexed four elements table:

num 0 error number, same in i5_errno()

cat 1 error category

msg 2 Error message, as in i5_errormsg()

desc 3 Detailed description of the error

Message and description are related to error class:

I5_CAT_SQL SQL engine error

SQL digital code included in number (i.e. 501)

SQL message included in message (i.e. SQL0501)

I5_CAT_SIGNAL Error from system signal (file not found)

then message contains CPFxxxx code

I5_CAT_MULTIREC Error with multiple recording

(all records could not be written)


Description contains a text telling how many records were really written.

I5_CAT_APPC APPC communication error

Number contains primary code.

Description contains the text "APPC error primary xxxx secondary yyyy"

I5_CAT_INTERNAL Easycom internal error (i.e. license problem)

I5_CAT_TCPIP TPC/IP communication error

I5_CAT_UNKNOWN Unknown error

I5_CAT_VBA Error in eac32vba library

I5_CAT_PHP Easycom For PHP use error

Parameters

connection Connection – result of i5_connect

Returns:

It returns an associative indexed four elements table

Specific error returned


Example


$conn = i5_connect('NOT_EXIST','user','password');


$err = i5_error();

print_r($err);echo ' ';


case I5_CAT_TCPIP:

echo ' TCP/IP problem - Connection not possible ';

break;


echo ' Easycom error - Connection not possible ';

break;

}

echo 'Error number :'. i5_errno() . ' ';

echo 'Error message :'. i5_errormsg() .' ';

}

$conn = i5_connect('p520', 'QPGMR', 'LAUNCHER');


$err = i5_error();

print_r($err);echo ' ';


case I5_CAT_TCPIP:

echo ' TCP/IP problem - Connection not possible ';

break;


echo ' Easycom error - Connection not possible ';

break;

}

echo 'Error number :'. i5_errno() . ' ';

echo 'Error message :'. i5_errormsg() .' ';

}

echo "Connected : $conn ";

$file = i5_open('EASYCOM/NCLIENT', I5_OPEN_READ);


E_USER_ERROR);

/* testing file edition */





echo 'Openning a file in writing to enable modification ';

break;


echo 'Pointing a record before modification ';

break;


echo 'Locked record... ';

break;

}

}

/* SLQ request test */

$query = i5_query("SELECT * FROM EASYCOM/NOT_EXIST");

If ($query == FALSE){


echo 'SQL error code: ' . i5_errno() . ' ';

echo 'Error message: ' . i5_errormsg() . ' ';

echo 'Error information : ';print_r($error);echo ' ';

}

See also

i5_errno

i5_errormsg

List of errors

Error category

i5_errormsg

Gets error message for last executed action.

string i5_errormsg ( [resource connection] )

Details

i5_errno and i5_errormsg functions simply returns number and error message, more complete i5_error function gives more details (category, number, message and description).

N° Code Description

0 I5_ERR_OK No error.

1 I5_ERR_ERROR Error occurred

2 I5_ERR_TOOMUCHOPENFILE Too many open files

3 I5_ERR_MEMALLOC Available memory too small

4 I5_ERR_INVALIDPTR Invalid pointer (handle)

5 I5_ERR_FILENOTFOUND File not found

6 I5_ERR_FIELDNOTFOUND Field not found

7 I5_ERR_INVALIDFIELDNBR Field number does not exist

8 I5_ERR_INVALIDKEYLEN Wrong key size

9 I5_ERR_INVALIDKEYNBR False key number

10 I5_ERR_NOTENABLETOUPDATE File can not be modified

11 I5_ERR_INVALIDOPENMODE

File opening type does not allow this operation

12 I5_ERR_RECORDNOTFOUND Record not found

13 I5_ERR_RECORDLOCKED Record locked

14 I5_ERR_BEOF File head or end

15 I5_ERR_FILELIMITS Out of file limits reading attempt (before or after EOF)

16 I5_ERR_NOTCONNECTED Not connected

17 I5_ERR_INVALIDSEQ Invalid operation sequence.

18 I5_ERR_NORANGESET Undefined range.

19 I5_ERR_NOLINKDEFINED Undefined link

20 I5_ERR_NOCURRENTRECORD No current record

21 I5_ERR_NULLNOTALLOWED NULL operation not allowed (field do not support NULL value)

22 I5_ERR_BADSESSION I5 session does not exist.

23 I5_ERR_WRONGLOGIN User name or pass word error.

24 I5_ERR_NOTENOUGHRIGHTS User rights problem.

25 I5_ERR_INVALIDTYPE Invalid type.

26 I5_ERR_INVALIDINFO Retrieving information variable too small.

27 I5_ERR_NOTTYPEPROPERTY Requested property does not exist.

28 I5_ERR_RECORDCHANGED Record changed before update.

29 I5_ERR_ALLREADYINTRAN All ready in transaction mode.

30 I5_ERR_NOTINTRAN No transaction started.

4097 I5_ERR_FIELDNULL NULL field value

Parameters


Returns:

Error message string.






Example




$err = i5_error();


case I5_CAT_TCPIP:

echo "TCP/IP problem – Connection not possible";

exit;


echo " Easycom error - Connection not possible";

}

echo "Error number". i5_errno() . " ";

echo "Error message". i5_errormsg() ." ";

/* File edition test */





echo "Opens the file in writing to enable mosification";


echo "Points a record before modification";


echo "Locked record...";

}

/* Command test */

$ret = i5_cmd("NB=CHAR(20); RTVSYSVAL SYSVAL(QSRLNBR)

RTNVAR(&NB)");

if ($ret) { // correct syntax


if ($res == 0) {...} // correct execution

else {echo "Command provoked error ". $res;}

else {

echo "Check command syntax";

}

/* SQL request test */




echo "Error message: " . i5_errormsg($query) . " ";}

See also

i5_errno

i5_error

List of errors

Code N° Description

I5_ERR_OK 0 No error.

I5_ERR_ERROR 1 Error occurred

I5_ERR_TOOMUCHOPENFILE 2 Too many open files


I5_ERR_INVALIDPTR 4 Invalid pointer (handle); specific message

I5_ERR_FILENOTFOUND 5 File not found

I5_ERR_FIELDNOTFOUND 6 Field not found

I5_ERR_INVALIDFIELDNBR 7 Field number invalid

I5_ERR_INVALIDKEYLEN 8 Wrong key length

I5_ERR_INVALIDKEYNBR 9 Wrong key field number

I5_ERR_NOTENABLETOUPDATE 10 File not allowed to be changed

I5_ERR_INVALIDOPENMODE 11 File open mode not valid for operation

I5_ERR_RECORDNOTFOUND 12 Record not found

I5_ERR_RECORDLOCKED 13 Record locked


I5_ERR_FILELIMITS 15 Reads out of the file (before or after EOF)

I5_ERR_NOTCONNECTED 16 Not connected

I5_ERR_INVALIDSEQ 17 Operation sequence not valid

I5_ERR_NORANGESET 18 Range not defined

I5_ERR_NOLINKDEFINED 19 Link not defined

I5_ERR_NOCURRENTRECORD 20 No current record

I5_ERR_NULLNOTALLOWED 21 Null operation not applicable (field does not support nulls)

I5_ERR_BADSESSION 22 AS/400 session not valid

I5_ERR_WRONGLOGIN 23 Bad login user or password

I5_ERR_NOTENOUGHRIGHTS 24 User rights problem

I5_ERR_INVALIDTYPE 25 INVALID TYPE

I5_ERR_INVALIDINFO 26 Info variable height not enough

I5_ERR_NOTTYPEPROPERTY 27 Bad property ID

I5_ERR_RECORDCHANGED 28 The record has changed before update

I5_ERR_ALLREADYINTRAN 29 Allready in a transaction (nested transaction are not supported)

I5_ERR_NOTINTRAN 30 Not in a transaction

I5_ERR_INCORRECTVALUE 36 unable to set the value (out of range; ...)

I5_ERR_PARAMNOTFOUND 37 Requested parameter does not exist in the description.

I5_ERR_ENDOFOCC 38 Number of occurences greater than the maximum set in the

description.

I5_ERR_DESC_UNEXP 39 Unexpected error while processing description

I5_ERR_DQDESC_UNSUPP 40 Unsupported description for a data queue













I5_ERR_PHP_BAD_LEN_PROP 266 The length of the property x is too large; -2 instead of -3 max.



I5_ERR_PHP_API_LENGTH 270 The length of element -1 of parameter is too big (max : -2).


I5_ERR_PHP_BOOKMARK 272 Bookmark value expected for this operator

I5_ERR_PHP_NOT_BOOKMARK 273 Bookmark value unexpected for this operator




I5_ERR_PHP_PARAM_DESC 277 specific message

I5_ERR_PHP_BLOBSIZE 278 the blob size received(-1) is different of the announced size(-2).

I5_ERR_PHP_SEEK_FIRSTLAST 279 Bookmark value expected for this operator

I5_ERR_PHP_PROPERTY_NUMBER 280 This(-1) property number is not valid.


I5_ERR_PHP_BAD_ADDNEW_CST 282 The only constant accpeted are I5_ADDNEW_NOCLEAR or

I5_ADDNEW_CLEAR.

I5_ERR_PHP_NOT_RPIVATE_CONNECTION 283 The restore connection is not allowed.

I5_ERR_PHP_ALREADY_PGMNAME 284 You cannot call this function; because it was already called or x was

called.




I5_ERR_PHP_EXECUTE 289 You cannot read a request with parameters without calling the

I5_execute function.


I5_ERR_PHP_EMPTY_ARRAY 291 Internal error; please contact Aura Equipement; error number 291

I5_ERR_PHP_NO_KEYNAME 292 Unspecified name for array item -1.



I5_ERR_PHP_COMMAND_ERROR 295 The command returned an error: x.




I5_ERR_PHP_ELEMENT_MISSING 304 An element of the array has a wrong type within function_name(type)

function.

I5_ERR_PHP_BAD_DEF 305 You cannot define an occurence number; and an occurence

reference for the same parameter -1.



I5_ERR_PHP_BAD_DS_INPUT 308 Values for 'Data Structure' parametre -1 does not match the

description.



I5_ERR_PHP_BAD_PROG_NAME 311 Program not found.

I5_ERR_PHP_AS400_MESSAGE 312 Internal error; please contact Aura Equipement; error number 312




I5_ERR_PHP_EMPTY_PCML 316 PCML can not be empty



Error category

I5_CAT_SQL SQL engine error

SQL digital code included in number (i.e. 501)

SQL message included in message (i.e. SQL0501)

I5_CAT_SIGNAL Error from system signal (file not found)


I5_CAT_MULTIREC Error with multiple recording

(all records could not be written)


Description contains a text telling how many records were really written.

I5_CAT_APPC APPC communication error

Number contains primary code.

Description contains the text "APPC error primary xxxx secondary yyyy"

I5_CAT_INTERNAL Easycom internal error (i.e. license problem)

I5_CAT_TCPIP TPC/IP communication error

I5_CAT_UNKNOWN Unknown error

I5_CAT_VBA Error in eac32vba library

I5_CAT_PHP Easycom For PHP use error

XML Easycom

Introduction to XML Easycom

XML Easycom is an interface to describe and call native IBM i Procedure and Programs, using an XML protocol.

PHP developers don’t necessarily have to take care about XML. A set of API functions is provided:

i5_XmlDefine

i5_XmlBindSrvPgm

i5_XmlCallProgram

i5_XmlLoadDefinition

i5_XmlExecRequest

Original RPG sources can be used by PHP scripts to describe data structures, procedures and programs. Example of PHP script:

$Ret = i5_XmlLoadDefinition ("RPG", 'EASYCOMXMP/QRPGLESRC,CVTNW_H');

$ret = i5_XmlBindSrvPgm ("XMPSRVPGM");

$ArrayIn = array('LIMIT'=>150, 'DECV'=>12345);

$ArrayOut = i5_XmlCallProgram ("FCVTNW", $ArrayIn, "RetVal");

echo 'Return value = '.$RetVal.' ';

XML Easycom is independent from Easycom server. It can be loaded as an extension to Easycom, or as an independent service into an IBM i job or PASE application, such as PHP.

XML Easycom server receives requests from client applications in XML format, and it returns back answer data in XML format too. Client application gets APIs to easily build requests, and retrieve results.

An application sends Xml request to XmlEasycom server to:

Bind Service Programs to the server job.

Load native program and procedure definitions from RPG or PCML source.

Execute system commands

Call native program and procedure.

A typical application bind service programs to the job once, when job is initiated, then it loads Program and Procedure definitions once, so that prototypes are known by the system when subsequent calls are issued.

An XML Easycom request consists of the following tags:

<Define> tag: Includes program and structure definitions, and procedure prototypes.

<Bind> tag: Binds a service program to the job, and makes all its procedure accessible.

<System> tag: Executes immediately a system command. This tag has no meaning when XML Easycom is an extension to Easycom Server.

<Include> Tag: Includes an XML file containing XML Easycom tags.

<Program> tag: Calls a program or procedure, passing input parameters.

XML Easycom tags can be included in one root tag: <Easycom>.

Each tag has its own attributes and tags.

Example: Bind service program, and load procedure definitions from RPG and PCML.

<?xml version="1.0" encoding="ISO-8859-1" ?>

<Easycom> <system IGNMSG="CPF2103" Command="addlible PCXML"/> <bind> <file type="*SRVPGM" name="RPGPRC01"/> </bind> <define> <file type="RPG" pf-src="CVTNW_H"/> <file type="PCML" stmf="/tmp/sr/CUST_DIM.pcml" /> <S-RPG> DS_CUST E DS extname(SP_CUST:RSP_CUST); PSPCUST PR; Result LIKEDS(DS_CUST); TERM1 5S 0; </S-RPG> </define> </Easycom>

Example: Call a program, passing input parameter value.

<?xml version="1.0" encoding="ISO-8859-1" ?> <Easycom> <Program Name="PSPCUST"> <parameterList> <Term1>01551</Term1> </parameterList> </Program> </Easycom>

Return data from Call.

<?xml version="1.0" ?> <Program name="PSPCUST"> <ParameterList> <RESULT Type="Struct"> <CUST_ID>1551</CUST_ID> <COMPANY>Marmot Divers Club</COMPANY> <FIRSTNAME>Joyce</FIRSTNAME> <LASTNAME>Marsh</LASTNAME> <CIVIL>2</CIVIL> <ADDRESS>872 Queen St.</ADDRESS> <ADDR2></ADDR2> <CITY>Kitchener</CITY> <STATE>Ontario</STATE> <ZIP>G3N 2E1</ZIP> <COUNTRY>Canada</COUNTRY> <PHONE>416-698-0399</PHONE> <FAX>426-698-0399</FAX> </RESULT> <TERM1>1551</TERM1> </ParameterList> </Program>

Simplified RPG Syntax

Simplified RPG Syntax:

Simplified RPG accepts only declaration statements. ‘D’ letter at beginning of a regular RPG declaration is omitted.

Statements are ended by a semi colon (;).

There is no column constraints.

Name [E] [DS

PR

S]

[n]T[d] [ Keywords ] ;

Name is the name of a variable, structure or procedure.

E means that the structure is externally defined by a physical file. Keyword EXTNAME is mandatory.

DS: When this keyword is present, Name is a data structure.

PR: When present, Name is a Procedure name.

S: When present, Name is a simple variable.

n is the number of digits of a simple variable.

T is the data type.

d is the precision.

Keywords are used according to regular RPG syntax.

When DS, PR and S are not specified, name is a member of the data structure or a parameter of a procedure wich definition was started by a previous statement.

/COPY directive can used in S-RPG definitions, to load external RPG source members.

PR keyword is used to declare a procedure. If the procedure maps to a program (*PGM) use standard RPG keyword EXTPGM to point to the real program. If the procedure maps to a procedure in a service program, use keyword EXTPROC to give the real procedure name, if it is different from the name used and defined by PHP.

DS keyword is used to define data structures. EXTNAME keyword can be used to define an external data structure from a physical file description. In that case, special letter E is present before DS keyword.

CONST keyword sets parameter as INPUT only.

Example of S-RPG Syntaxs.

DS_CUST E DS extname(SP_CUST:RSP_CUST); PSPCUST PR; Result LIKEDS(DS_CUST); TERM1 5S 0;

DS_A DS; MBR1 10a; MBR2 10a inz('Member 2'); MBR3 8p2; SampleDS1 PR extpgm(SampleDS1); PARM1 10a const; PARM2 8p2; PARM3 likeds(DS_A);";

RPG and PCML sources contain structure and program definitions. Definitions are maintained for the all job life.

It is recommended to not run twice a <define> for the same RPG or PCML source.

Calling Programs or Procedures

With XML Easycom, you can call programs (*PGM) and Procedures from service programs (*SRVPGM).

The prototype tells the system what to call: A Program or a Procedure.

RPG or Simplified RPG prototypes:

EXTPGM Keywords tells the system that a Program has to be called. The name of the program is given by the keyword, and can be different from the name of the prototype.

EXTPGM(PGM_NAME):

Example:

D CVTNW_PRC PR EXTPGM('CVTNWR')

CVTNWR is the name of a the program to call.

CVTNW_PRC is a virtual name used by PHP script within XML Easycom functions calls.

EXTPROC keyword tells the system that a procedure has to be called. The real name of the procedure is given by the keyword, and can be different from the name of the prototype.

EXTPROC(PROC_NAME):

Example:

D CVTNW_PRC PR EXTPROC('CVTNW')

CVTNW is the real name of the procedure to call in a service program.

CVTNW_PRC is a virtual name used by PHP script within XML Easycom functions calls.

When no keyword is used, then a procedure is called, and its name is equal to the virtual name.

Example:

D CVTNW PR

CVTNW is the real name of the procedure to call in a service program, and it is also the virtual name used by PHP script within XML Easycom functions calls.

PCML prototypes:

EntryPoint attribute in <Program> tag will tell the system if a program or a procedure needs to be called.

If EntryPoint is specified, it sets the real name of the procedure. Name sets the virtual name used winthin PHP scripts using XML Easycom.

Example:

<program name="MY_CUST_PRC" entrypoint="CUST_DIM">

When EntryPoint attribute is not set, Path attribute sets the real name of the program to call, and optionally its library.

Example:

<program name="qbnrpii" path="/QSYS.lib/QBNRPII.pgm" >

If library is not specified, program is searched in *LIBL.

Standard AS/400 naming can be used (LIBRARY/NAME).

Request XML stream

Include tag

Include tag is used to include and execute XML Easycom requests from an external XML stream fille stored in the IFS.

Include tag can be expanded with the following elements.

<include file="IFS Path to XML file" />

Attribute Value Description

File= IFS Path Path to an XML file containing XML Easycom directives to execute.

Example <?xml version="1.0" encoding="ISO-8859-1" ?> <Easycom> <include file="/AppData/Web/App_Defines.xml" /> </Easycom>

In this example, "App_Defines.xml" stream file contains:

<?xml version="1.0" encoding="ISO-8859-1" ?> <Easycom> <system IGNMSG="CPF2103" Command="addlible PCXML"/> <bind> <file type="*SRVPGM" name="RPGPRC01"/> </bind> <define> <file type="RPG" pf-src="CVTNW_H"/> <file type="PCML" stmf="/tmp/sr/CUST_DIM.pcml" /> <S-RPG> DS_CUST E DS extname(SP_CUST:RSP_CUST); PSPCUST PR; Result LIKEDS(DS_CUST); TERM1 5S 0; </S-RPG> </define> </Easycom>

Bind tag

This tag binds service programs to the current job. Exported procedure from service program become accessible for calls.

Bind tag can be expanded with the following elements.

<bind type="file type"

file="Library/File" </bind>


Type= *SRVPGM Sets the type of object to bind to the current server job.

Only *SRVPGM is allowed.

File= Service Program Name of the service program to bind to the current server job. Name is given in the form "Library/File". If library is omitted, special value *LIBL is used.

When the application has to call procedure from service programs, service programs need to be bound to the current job to make their exported procedure accessible.

For each service program, <bind> tag has to be executed only once for the XmlEasycom server job life. The service program remains bound to the job.

Example: <?xml version="1.0" encoding="ISO-8859-1" ?> <Easycom> <bind> <file type="*SRVPGM" name="RPGPRC01"/> </bind> </Easycom>

Define tag

Define tag is used to load procedure definition from external PCML stream files, from RPG ILE source files, or from immediate PCML or simplified RPG.

Define tag can be expanded with the following elements.

<define>

[ <file type="source type"

[ src-mbr="RPG source member" ]

[ stmf="RPG or PCML source" ]

/> ]

[ <pcml version="1.0"> ... </pcml> ]

[ < S-RPG > ... </S-RPG> ]

</define>


<file> tag When structure and procedure definition is stored in a source file member or a stream file, <file> sub tag is used, with following attributes:

type

src-mbr

stmf

Type= PCML RPG

Attribute of <file> tag.

Set the type of source stored in the source file member or stream file.

Possible values are:

PCML: Description is given in PCML format. PCML description is stored in the IFS file referenced to by stmf attribute.

RPG: Description is given in RPG source, stored a the source file member referenced to by src-mbr attribute, or in the stream file referenced to by stmf.

Src-mbr= Source file member Path to the file member containing RPG ILE source.

Stmf IFS path Path to PCML or RPG ILE source stored in the IFS.

<pcml> tag Using this tag, PCML description is not stored in an external file. It is directly embeded in the current XML request. <pcml> tag contains the full pcml description for structures and programs.

See example here after.

<s-rpg> tag "Simplified RPG" is like RPG. It accepts only definition statements. There is no column constraint. Each statement is terminated by a semi colon (;).

Example of <pcml> tag embedded in XML Easycom stream. <?xml version="1.0" encoding="ISO-8859-1" ?> <Easycom> <define> <pcml version="1.0">   <struct name="usri0100"> <data name="bytesReturned"type="int" length="4" usage="output"/> <data name="bytesAvailable" type="int" length="4" usage="output"/> <data name="userProfile" type="char" length="10" usage="output"/> <data name="previousSignonDate" type="char" length="7" usage="output"/> <data name="previousSignonTime" type="char" length="6" usage="output"/> <data type="byte" length="1" usage="output"/> <data name="badSignonAttempts" type="int" length="4" usage="output"/> <data name="status" type="char" length="10" usage="output"/> <data name="passwordChangeDate" type="byte" length="8" usage="output"/> <data name="noPassword" type="char" length="1" usage="output"/> <data type="byte" length="1" usage="output"/> <data name="passwordExpirationInterval" type="int" length="4"

usage="output"/> <data name="datePasswordExpires" type="byte" length="8" usage="output"/> <data name="daysUntilPasswordExpires" type="int" length="4"

usage="output"/> <data name="setPasswordToExpire" type="char" length="1" usage="output"/> <data name="displaySignonInfo" type="char" length="10" usage="output"/> </struct>

 <program name="qsyrusri" path="QSYRUSRI"> <data name="receiver" type="struct" struct="usri0100" usage="output"/> <data name="receiverLength" type="int" length="4" usage="input" init="84"/> <data name="format" type="char" length="8" usage="input" init="USRI0100"/> <data name="profileName" type="char" length="10" usage="input"

init="*CURRENT"/> <data name="errorCode" type="int" length="4" usage="input" init="0"/> </program> </pcml> </define> </Easycom>

Simplified RPG Syntax:

Simplified RPG accepts only declaration statements, and compiler directives.

See additional information about Simplified RPG.

Example of <s-rpg> tag. <?xml version="1.0" encoding="ISO-8859-1" ?> <Easycom> <define> <s-rpg> DS_CUST E DS extname(SP_CUST:RSP_CUST); PSPCUST PR; Result LIKEDS(DS_CUST); TERM1 5S 0; </s-rpg> </define> </Easycom>

RPG and PCML sources contain structure and program definitions. Definitions are maintained for the all job life.

It is recommended to not run twice a <define> for the same RPG or PCML source.

Program tag

Program tag is used to effectively call a program or procedure.

Program tag can be expanded with the following elements.

<program name="Procedure_Name"

<parameterlist>

<data_name [ usage="input" ]

[ encoding="base64" ] >input value </data_name >

</parameterlist>

</program>


name= Procedure name Name of a procedure previously defined in a <define> tag in the current or previous XML file.

<parameterlist> List of input values This sub tag includes all the values for all input parameter elements.

<data_name> Parameter or Element name

This tag has the name of the parameter or the name of the member when parmeter is a structure.

<input value> String Input value for the parameter or data structure member.

When parameter is a data structure, it is divided into members, and value is set for each member. There is no input value at data structure level.

In the following example, QObjName is a DS, divided into two members: Obj and Lib. Value is set for each member.

<parameterList> <receiverLength>4096</receiverLength> <QObjName> <Obj>CRMSRVP01</Obj> <Lib>*LIBL</Lib> </QObjName> </parameterList>

usage Input When program definition is loaded from an RPG source, input or output usage is usually not set by RPG.

This attribute can be used at execution time to tell the system we don’t expect a value on return for this parameter.

encoding Base64 When encoding is set to "base64", input value must be provided in base64 format. Value will be converted as it, from base64 to binary, without any other character conversion.

Example <?xml version="1.0" encoding="utf-8" ?> <Easycom> <Program Name="qbnrpii"> <parameterList> <receiverLength>4096</receiverLength> <QObjName> <Obj>CRMSRVP01</Obj> <Lib>*LIBL</Lib> </QObjName> </parameterList> </Program> </Easycom>

This tag is processing the effective call of the program or procedure.

System tag

Execute a system command.

<system [ ignmsg="Message iIDs" ] command="system command" </system>


ignmsg= Message IDs Sets a list of message IDs to ignore if they rise during command execution. Messages are listed, separated by a blank character.

Ex: ignmsg="CPF2103 CPF2104"

command= System command System command to execute.

This tag has no meaning when XML Easycom is loaded as an extension to Easycom. Easycom has already APIs to execute system commands.

When XML Easycom is loaded as an independent service, <system> tag can be used to change the job environment before to bind service programs, load program definitions, or call procedures.

Example: <?xml version="1.0" encoding="ISO-8859-1" ?> <Easycom> <system IGNMSG="CPF2103" Command="addlible PCXML"/> </Easycom>

Result XML stream

Result from Program Call

On return from a program call, resulting XML stream contains a <parameterlist> tag with modified parameters.

Example: Result from a program call.

Resulting XML has <parameterlist> tag.

<?xml version="1.0" ?> <Program name="FCVTNW"> <ParameterList> <LIMIT>150</LIMIT> <OUTPUT>FOUR THOUSAND, FIVE HUNDRED EIGHTY NINE DOLLARS AND FIFTY FOUR CENTS<

/OUTPUT> <DECV>4589.54</DECV> <ERROR></ERROR> </ParameterList> </Program>

Program was defined from an RPG source as follow:

D CVTNW_PRC PREXTPGM('CVTNWR') D LIMIT 3P00 D DECV 11P02 D OUTPUT 150a D ERROR 1a

Program was called using following XML Easycom request:

<?xml version="1.0" encoding="utf-8" ?> <Easycom> <Program Name="CVTNW_PRC"> <parameterList> <Limit>150</Limit> <DecV>4589.54</DecV> </parameterList> </Program> </Easycom>

Result from Procedure Call

On return from a procedure call, resulting XML stream contains a <parameterlist> tag with modified parameters, and a <returnvalue> tag if the procedure returns a direct value.

Example: Result from a procedure call with a result value as string.

Resulting XML has <returnvalue> and <parameterlist> tags

<?xml version="1.0" ?> <Program name="FCVTNW"> <ReturnValue>FOUR THOUSAND, FIVE HUNDRED EIGHTY NINE DOLLARS AND FIFTY FOUR CEN

TS</ReturnValue> <ParameterList> <LIMIT>150</LIMIT> <DECV>4589.54</DECV> <ERROR></ERROR> </ParameterList> </Program>

Procedure was defined from an RPG source as follow:

D FCVTNW PR 150a D LIMIT 3P00 D DECV 11P02 D ERROR 1a

Procedure was called using following XML Easycom request:

<?xml version="1.0" encoding="utf-8" ?> <Easycom> <Program Name="FCVTNW"> <parameterList> <Limit>150</Limit> <DecV>4589.54</DecV> </parameterList> </Program> </Easycom>

Error Messages

In case of error on XML Request execution, an XML stream is returned with a <messages> tag.

Example: A source file member couldn’t be found during a procedure definition.

<?xml version="1.0" ?> <messages> <FATAL Class="file" ErrNo="3101" File="QRPGLESRC(FCVTNW_H)">A non-

recoverable I/O error occurred.</FATAL> </messages>

Example: Database file not found while calling a program.

<?xml version="1.0" ?> <messages>

<FATAL Class="msg" MsgId="CPF5715" Msg=" File SP_CUST in library *LIBL not found." Help="Cause . . . . . : The requested function did not find the file in the

specified library. Recovery . . . : Do one of the following, and then try the req

uest again: -- Change the file or library name. --

If *LIBL was specified, add the library that contains the file to the library li

st (ADDLIBLE command)."/> </messages>

Examples

Example: QBNRPII API

QBNRPII is a system API. It returns the PCML description for each module bound in a service program.

QBNRPII is defined by a PCML stream file as follow:

<pcml version="1.0">

<struct name="QName"> <data name="Obj" type="char" length="10" /> <data name="Lib" type="char" length="10" init="*LIBL" /> </struct>

<struct name="Entry"> <data name="OffsetNextEntry" type="int" length="4" /> <data name="ModuleName" type="char" length="10" /> <data name="ModuleLib" type="char" length="10" /> <data name="InterfaceInfoCCSID" type="int" length="4" /> <data name="InterfaceInfoType"type="int" length="4" /> <data name="InterfaceInfoOffset" type="int" length="4" /> <data name="InterfaceInfoReturn" type="int" length="4" /> <data name="InterfaceInfoAvail" type="int" length="4" /> <data name="InterfaceInfo" type="char" length="InterfaceInfoReturn" offset="InterfaceInfoOffset" offsetfrom="receiver"/> <data type="byte" length="0"

offset="OffsetNextEntry" offsetfrom="receiver"/> </struct> <struct name="receiver"> <data name="BytesReturn"type="int" length="4" /> <data name="BytesAvail" type="int" length="4" /> <data name="ObjName" type="char" length="10" /> <data name="ObjLib" type="char" length="10" /> <data name="ObjType" type="char" length="10" /> <data name="filer1" type="char" length="2" /> <data name="OffsetFirstEntry" type="int" length="4" /> <data name="NumberOfEntries" type="int" length="4" /> <data type="byte" length="0"

offset="OffsetFirstEntry" offsetfrom="receiver" /> <data name="Entries" type="struct" struct="Entry" Count="NumberOfEntries" /> </struct> <program name="qbnrpii" path="/QSYS.lib/QBNRPII.pgm" > <data name="receiver" type="struct" struct="receiver"

usage="output" outputsize="receiverLength"/> <data name="receiverLength" type="int" length="4" usage="input"

init="4096" /> <data name="formatName" type="char" length="8" usage="input"

init="RPII0100" /> <data name="QObjName" type="struct" struct="QName" usage="input" /> <data name="ObjType" type="char" length="10" usage="input"

init="*SRVPGM" /> <data name="QBndModName" type="char" length="20" usage="input"

init="*ALLBNDMOD"/> <data name="errorCode" type="int" length="4" usage="input" init="0" /> </program> </pcml>

Program definition is loaded from PCML stream file by following XML Easycom request:

<?xml version="1.0" encoding="utf-8" ?> <Easycom> <define> <file stmf="/tmp/sr/qbnrpii.pcml" type="PCML" /> </define> </Easycom>

Program is called by following XML Easycom request:

<?xml version="1.0" encoding="utf-8" ?> <Easycom> <Program Name="qbnrpii"> <parameterList> <receiverLength>4096</receiverLength> <QObjName> <Obj>RPGPRC01</Obj> <Lib>SR</Lib> </QObjName> </parameterList> </Program> </Easycom>

Following XML stream is returned back:

For each module, value of "receiver.Entries.i[n].InterfaceInfo" is the PCML description os the

module entry points.

<?xml version="1.0" ?> <PCML Load... Time="2011-01-24 18:06:11.396" Clock="0"/> <end PCML Load... Time="2011-01-24 18:06:11.400" Clock="3"/> <Call... Time="2011-01-24 18:06:11.400" Clock="3"/> <Init... Time="2011-01-24 18:06:11.401" Clock="4"/> <Program name="qbnrpii"> <ParameterList> <receiver Type="Struct"> <BytesReturn>1496</BytesReturn> <BytesAvail>1496</BytesAvail> <ObjName>RPGPRC01</ObjName> <ObjLib>SR</ObjLib> <ObjType>*SRVPGM</ObjType> <filer1></filer1> <OffsetFirstEntry>48</OffsetFirstEntry> <NumberOfEntries>2</NumberOfEntries> <Program/> <Entries Type="Array" count="2"> <OffsetNextEntry>1364</OffsetNextEntry> <ModuleName>CUST_DIM</ModuleName> <ModuleLib>SR</ModuleLib> <InterfaceInfoCCSID>37</InterfaceInfoCCSID> <InterfaceInfoType>1</InterfaceInfoType> <InterfaceInfoOffset>92</InterfaceInfoOffset> <InterfaceInfoReturn>1270</InterfaceInfoReturn> <InterfaceInfoAvail>1270</InterfaceInfoAvail> <InterfaceInfo>&ltpcml version=&quot4.0&quot&gt &ltstruct name=&quotDS_CUST&q

uot&gt &ltdata name=&quotCUST_ID&quot type=&quotzoned&quot length=&quot5&quot pre

cision=&quot0&quot usage=&quotinherit&quot /&gt &ltdata name=&quotCOMPANY&quot ty

pe=&quotchar&quot length=&quot30&quot usage=&quotinherit&quot /&gt &ltdata name=&

quotFIRSTNAME&quot type=&quotchar&quot length=&quot20&quot usage=&quotinherit&quo

t /&gt &ltdata name=&quotLASTNAME&quot type=&quotchar&quot length=&quot20&quot us

age=&quotinherit&quot /&gt &ltdata name=&quotCIVIL&quot type=&quotchar&quot lengt

h=&quot1&quot usage=&quotinherit&quot /&gt &ltdata name=&quotADDRESS&quot type=&q

uotchar&quot length=&quot30&quot usage=&quotinherit&quot /&gt &ltdata name=&quotA

DDR2&quot type=&quotchar&quot length=&quot30&quot usage=&quotinherit&quot /&gt &l

tdata name=&quotCITY&quot type=&quotchar&quot length=&quot15&quot usage=&quotinhe

rit&quot /&gt &ltdata name=&quotSTATE&quot type=&quotchar&quot length=&quot20&quo

t usage=&quotinherit&quot /&gt &ltdata name=&quotZIP&quot type=&quotchar&quot len

gth=&quot10&quot usage=&quotinherit&quot /&gt &ltdata name=&quotCOUNTRY&quot type

=&quotchar&quot length=&quot20&quot usage=&quotinherit&quot /&gt &ltdata name=&qu

otPHONE&quot type=&quotchar&quot length=&quot15&quot usage=&quotinherit&quot /&gt

&ltdata name=&quotFAX&quot type=&quotchar&quot length=&quot15&quot usage=&quotin

herit&quot /&gt &lt/struct&gt &ltprogram name=&quotCUST_DIM&quot entrypoint=&quot

CUST_DIM&quot&gt &ltdata name=&quotRESULT&quot type=&quotstruct&quot struct=&quot

DS_CUST&quot count=&quot20&quot usage=&quotinputoutput&quot /&gt &ltdata name=&qu

otTOREAD&quot type=&quotint&quot length=&quot4&quot precision=&quot31&quot usage=

&quotinputoutput&quot /&gt &ltdata name=&quotIO&quot type=&quotint&quot length=&q

uot4&quot precision=&quot31&quot usage=&quotinputoutput&quot /&gt &ltdata name=&q

uotTERM1&quot type=&quotzoned&quot length=&quot5&quot precision=&quot0&quot usage

=&quotinputoutput&quot /&gt &lt/program&gt&lt/pcml&gt</InterfaceInfo> <Program/> <OffsetNextEntry>0</OffsetNextEntry> <ModuleName>CVTNW_PRC</ModuleName> <ModuleLib>SR</ModuleLib> <InterfaceInfoCCSID>37</InterfaceInfoCCSID> <InterfaceInfoType>1</InterfaceInfoType> <InterfaceInfoOffset>1408</InterfaceInfoOffset> <InterfaceInfoReturn>88</InterfaceInfoReturn> <InterfaceInfoAvail>88</InterfaceInfoAvail> <InterfaceInfo>&ltpcml version=&quot4.0&quot&gt &ltprogram name=&quotCVTNW_PR

C&quot entrypoint=&quotCVTNW_PRC&quot&gt &lt/program&gt&lt/pcml&gt</InterfaceInfo

> <Program/> </Entries> </receiver> </ParameterList> </Program>

Addenda

Display Object Description

Array with the object description returned by the i5_objects_list functions

For a detailed descriptions of the fields in the table, you can you referer to the OBJL0700 format used by QUSLOBJ API

NAME Object name used

LIBRARY Object library name used

TYPE Object type used

STATUS Information status

EXT_ATTR Extended object attribute

DESCRIP Text description

USR_ATTR User-defined attribute

FILER1 Reserved

AUX_POOL Object auxiliary storage pool (ASP) number

OWNER Object owner

DOMAIN Object domain

CRE_DAT Creation date and time

CHG_DAT Change date and time

STORAGE Storage

COMPRESS Object compression status

ALWPGMCHG Allow change by program

PGM_CHG Changed by program

AUDIT Object auditing value

SIGN_DIGIT Digitally signed

SIGNED_SYS Digitally signed by system-trusted source

SIGN_MONCE Digitally signed more than once

FILLER2 Reserved

LIB_AX_PO Library auxiliary storage pool (ASP) number

SRC_FILE Source file name

SRC_LIB Source file library name

SRC_MBR Source file member name

SRC_TIME Source file updated date and time

CREATOR Creator's user profile

SYS_NAME System where object was created

SYS_LEVEL System level

COMPILER Compiler

OBJ_LEVEL Object level

USR_CHG User changed

LIC_PGM Licensed program

PTF Program temporary fix (PTF)

APAR Authorized program analysis report (APAR)

PRIM_GRP Primary group

FILER3 Reserved

OPT_SPACE Optimum space alignment

PRIM_SPACE Primary associated space size

FILER7 Reserved

SAV_TIME Object saved date and time

RST_TIME Object restored date and time

SAV_SIZE Saved size

SAV_MLTP Saved size multiplier

SAV_SEQNBR Save sequence number

SAV_CMD Save command

SAV_VOLID Save volume ID

SAV_DEV Save device

SAV_FIL Save file name

SAV_LIB Save file library name

SAV_LABEL Save label

SAV_ACTTIM Save active date and time

JRN_STATUS Journal status

JRN_NAME Journal name

JRN_LIB Journal library name

JRN_IMG Journal images

JRN_OMITT Journal entries to be omitted

JRN_STR_DT Journal start date and time

FILER4 Reserved

USE_TIME Last-used date and time

RESET_TIME Reset date and time

USE_DAYS Days-used count

USE_INFUPD Usage information updated

OBJ_AUX_SP Object auxiliary storage pool (ASP) device name

LIB_AUX_SP Library auxiliary storage pool (ASP) device name

FILER5 Reserved

OBJ_SIZE Object size

SIZE_MLTP Object size multiplier

OVF_ASP Object overflowed auxiliary storage pool (ASP) indicator

OBJ_ASP_GP Object auxiliary storage pool (ASP) group name

LIB_ASP_GP Library auxiliary storage pool (ASP) group name

STR_JRN_NM Starting journal receiver name for apply

STR_JR_LIB Starting journal receiver library name

STR_JR_AUX Starting journal receiver library auxiliary storage pool (ASP) device name

STR_JR_A_L Starting journal receiver library auxiliary storage pool (ASP) group name

FILER6 Reserved

i5_fetch_array

Fetches a row of data from the resource.





Details

i5_fetch_array function returns current line of results set as a table. The table attributes are field names founded in the results set added with numeric indications.

In fact, it combines i5_fetch_row (indications) and i5_fetch_array (associative) functions.

i5_fetch_xxxx function moves the pointer one step forward (I5_READ_NEXT) before reading, but it is possible to specify another direction or position.

To retrieve current record, consecutive to an i5_seek or i5_data_seek, I5_READ_SEEK will read the line without moving the pointer.

I5_READ_NEXT Read the following record

I5_READ_PREV Read the precedent record



I5_READ_SEEK Read the current record

An attempt to read out of the file will return NULL and create an I5_ERR_BEOF error type.

Parameters

result Resource resulting from operation returning data

option

Flag specifying which record to fetch.

I5_READ_SEEK Current record

I5_READ_NEXT Next record

I5_READ_PREV Previous record

I5_READ_FIRST First record

I5_READ_LAST Last record

Default is I5_READ_NEXT

Returns: According to the specific fetch function used, it returns either an array or an object containing the data.

array - by index and name. assoc - by name. row - by index. object - by name as object properties.









Example

/* Selects and reads a segment */


$first = array("NAME" => "D"); $last = array("NAME" => "E"); $ret = i5_range_from($file, ">=", $first);

$ret = i5_range_to($file, "<", $last);

while ($tab = i5_fetch_array($result)) {

printf ("%s (%s)\n", $tab["FIRSTNAME"], $tab["NAME"];

printf ("%s (%s)\n", $tab[1], $tab[2];} }

$sql = "SELECT Name, Country code FROM City ID DESC ORDER";

$result = i5_query($sql)

if ($result) {

/* Reads last line */

$obj = i5_fetch_array($result, I5_READ_LAST);

/* Reads first line */

$obj = i5_fetch_array($result, I5_READ_FIRST);

/* Proceeds from beginning to end */

while ($obj = i5_fetch_array($result)) {

printf ("%s (%s)\n", $tab["FIRSTNAME"], $tab["NAME"];

printf ("%s (%s)\n", $tab[1], $tab[2];} }

/* Returns record as a table */

$sql = "SELECT * FROM CONTACTS";



echo "name: " . $tab["NAME"] . " ";

echo "First name: " . $tab["FIRSTNAME"] . " ";

echo "name: " . $tab[1] . " ";

echo "First name: " . $tab[2] . " ";

See also

i5_fetch_assoc

i5_fetch_row

i5_fetch_object

i5_result

i5_getblob

i5_fetch_assoc

Fetches result line as associative table.

Details

Returns associative table of next result line.

i5_fetch_xxxx functions (default) move the pointer one step forward (I5_READ_NEXT) before reading, but it is possible to specified another pointer direction or position.

To fetch current record, consecutive to an i5_seek or i5_data_seek, I5_READ_SEEK option will read line without moving the pointer.

I5_READ_NEXT Read the next record

I5_READ_PREV Read the previous record



I5_READ_SEEK Read the current record

An attempt to read out of the file will returns NULL and create an I5_ERR_BEOF error type.

Parameters

result File or request ID

option Easycom constant specifying scanning direction

Returns:

Returns an associated table or NULL if there is no more line or FALSE in case of error.







Example

/* selects and reads a segment */


$first = array("NAME" => "D"); $last = array("NAME" => "E"); $ret = i5_range_from($file, ">=", $first);

$ret = i5_range_to($file, "<", $last);

while ($tab = i5_fetch_assoc($result)) {

printf ("%s (%s)\n", $tab["FIRSTNAME"], $tab["NAME"];}

$sql = "SELECT Name, Country code FROM City ORDER by ID DESC";

$result = i5_query($sql)

if ($result) {

$obj = i5_fetch_assoc($result, I5_READ_LAST);


$obj = i5_fetch_assoc($result, I5_READ_FIRST);

/* Proceeds from beginning to end */

while ($obj = i5_fetch_assoc($result)) {

printf ("%s (%s)\n", $tab["NAME"], $tab["PRENOM"];}

/* Returns the record as an associative table */

$sql = "SELECT * FROM CONTACTS";


$rec = i5_fetch_assoc($res);

echo "Name: " . $tab["NAME"] . " ";

echo "First name: " . $tab["FIRSTNAME"] . " ";

See also

i5_fetch_array

i5_fetch_row

i5_fetch_object

i5_result

i5_getblob

i5_fetch_object

Returns result line as object or NULL if there is no more line.





Details

i5_fetch_object function returns results set current line as an object. Its attributes represent fields names founded in the results set.

If there is no more result, i5_fetch_object function returns NULL.

i5_fetch_xxxx functions (default) move the pointer one step forward (I5_READ_NEXT) before reading, it is possible to specify another move direction or position.

To fetch current record consecutive to i5_seek or i5_data_seek, I5_READ_SEEK option will read the line without moving pointer.

I5_READ_NEXT Read following record


I5_READ_FIRST Read first record

I5_READ_LAST Read last record

Any attempt to read out of the file will return NULL and activate an I5_ERR_BEOF error type.

Parameters

result connection ID

option Easycom constant setting move direction

Returns:

Returns an object with record values or NULL if there is no more line or FALSE in case it fails.







Example

/* Makes and reads a selection */

$file = i5_open("EASYCOM/NCLIENT");

$first = array("NAME" => "D"); $last = array("NAME" => "E");


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

trigger_error("i5_range_from error : ".i5_errormsg(), E_USER_ERROR);

$ret = i5_range_to($file, FALSE, $last);

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

trigger_error("i5_range_to error : ".i5_errormsg(), E_USER_ERROR);

$obj = i5_fetch_object($file, I5_READ_FIRST);

while (!is_bool($obj) && ($obj != NULL)) {

echo "Name : ".$obj->CNOM." (".$obj->CCODE.") ";

$obj = i5_fetch_object($file);

}

/* SQL request */

$sql = "SELECT LASTNAME, COUNTRY, ZIP FROM easycom/s_customer ORDER by cust_id

DESC";

$result = i5_query($sql); if (is_bool($result)) trigger_error("i5_query error : ".i5_errormsg(), E_USER_ERROR);


$obj = i5_fetch_object($result, I5_READ_LAST);

printf("Last : %s (%s) ", $obj->LASTNAME, $obj->ZIP);


$obj = i5_fetch_object($result, I5_READ_FIRST);

printf("First : %s (%s) ", $obj->LASTNAME, $obj->ZIP);

/* Scrolling from begining to end */

while (!is_bool($obj) && $obj != NULL) {

printf("%s (%s) ", $obj->LASTNAME, $obj->ZIP);


}

See also

i5_fetch_array

i5_fetch_row

i5_fetch_assoc

i5_result

i5_getblob

i5_link

Activates linkage between master file and detail file.

bool i5_link ( resource result_master, array keys_master,

resource result_detail, array keys_detail )

Details

i5_link function activates linkage between a master file and a detail file, both files must be opened. Each master file reading will automatically activate a detail file reading.

Only one link can be activated. If i5_link function is called again, first link will be cancelled.

A detail file can only be linked to one master file, but several detail files can be linked to the same master file.

To deactivate link, i5_nolink function.must be called.

This function automates filter on detail file, it's similar to set a range on one or more key values directly fetched from the master file.

Parameters

result_master master file ID

result_detail Detail file ID

keys_master Master file keys table

keys_detail Detail file keys table

Returns:






Example

$invoices = i5_open('easycom/s_order'); if (is_bool($invoices))

trigger_error('i5_open master error : '.i5_errormsg(), E_USER_ERROR); $lines = i5_open('easycom/s_detail'); if (is_bool($lines)) trigger_error('i5_open detail error : '.i5_errormsg(), E_USER_ERROR); /* Two fields linkage */

$keys_invoice = array('ORDER_ID'); $keys_lines = array('ORDER_ID'); /*For index with two field*/

//$keys_invoice = ('DATE', 'NUMBER'); //$keys_lines = ('DATE', 'NUMFACT'); $lien = i5_link($lines, $keys_lines, $invoices, $keys_invoice); if (!$lien) trigger_error('i5_link detail error : '.i5_errormsg(), E_USER_ERROR);

$fac = i5_fetch_row($invoices, I5_READ_FIRST); if (is_bool($fac)) trigger_error('i5_fetch_row Master error : '.i5_errormsg(), E_USER_ERROR); echo 'Invoice lines are: '; $lig = i5_fetch_assoc($lines, I5_READ_FIRST); if (is_bool($lig)) trigger_error('i5_fetch_row detail error : '.i5_errormsg(), E_USER_ERROR); while (!is_bool($lig)) { echo $lig['PARTNO']. ' ' . $lig['QUANTITY'] . ' '; $lig = i5_fetch_assoc($lines, I5_READ_NEXT); } $ret = i5_nolink($lines); if (!$ret) trigger_error('i5_nolink Master error : '.i5_errormsg(), E_USER_ERROR);

See also

i5_nolink

i5_nolink

Deactivates active master / detail link activated with i5_link

bool i5_nolink ( resource result_detail )

Details

i5_nolink function is used to cancel an activated link with i5_link function.

It applies to detail file, wich will not be then, automatically filtered with a master file reading.

To reactivate a link, call i5_link function again.

Parameters

result File ID







Example

$invoices = i5_open('easycom/s_order'); if (is_bool($invoices)) trigger_error('i5_open master error : '.i5_errormsg(), E_USER_ERROR); $lines = i5_open('easycom/s_detail'); if (is_bool($lines)) trigger_error('i5_open detail error : '.i5_errormsg(), E_USER_ERROR); /* Two fields linkage */

$keys_invoice = array('ORDER_ID'); $keys_lines = array('ORDER_ID'); /*For index with two field*/

//$keys_invoice = ('DATE', 'NUMBER'); //$keys_lines = ('DATE', 'NUMFACT'); $lien = i5_link($lines, $keys_lines, $invoices, $keys_invoice); if (!$lien) trigger_error('i5_link detail error : '.i5_errormsg(), E_USER_ERROR);

$fac = i5_fetch_row($invoices, I5_READ_FIRST); if (is_bool($fac)) trigger_error('i5_fetch_row Master error : '.i5_errormsg(), E_USER_ERROR); echo 'Invoice lines are: '; $lig = i5_fetch_assoc($lines, I5_READ_FIRST); if (is_bool($lig)) trigger_error('i5_fetch_row detail error : '.i5_errormsg(), E_USER_ERROR); while (!is_bool($lig)) { echo $lig['PARTNO']. ' ' . $lig['QUANTITY'] . ' '; $lig = i5_fetch_assoc($lines, I5_READ_NEXT); } $ret = i5_nolink($lines); if (!$ret) trigger_error('i5_nolink Master error : '.i5_errormsg(), E_USER_ERROR);

See also

i5_link

easycom for php - aura equipements easycom...

Documents