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++, …
170
Embed
Easycom For PHP - AURA Equipements Easycom Storeeasycomstore.com/Data/WebHelp/Easycom_PHP/EasycomForPHP.pdf · Select "Easycom For PHP" ... mysql_fetch_row mysql_affected_rows odbc_fetch_into
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
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:
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
libI5comm5_1_064.so For PHP 5.1 64 Bits
libI5comm5_2_0.so For PHP 5.2 32 Bits
libI5comm5_2_064.so For PHP 5.2 64 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:
• 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.
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".
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.
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 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 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".
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.
Return :
AS/400 connection resource or false on failure. The connection resource will be given on input to subsequent function calls. If only one connection is open by the script, the connection resource is optional on subsequent function calls.
Error returned
I5_ERR_MEMALLOC 3 Not enough memory
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_NBPARAM_BAD 263 Wrong parameter count
I5_ERR_PHP_PRIVATE_CONNECTION_NOT_FOUND 285 the -1 connection has not been found.
I5_ERR_PHP_LOCALHOST_NOT_PERMIT 286 you must specify the AS/400 address
Details
This function acts like i5_connect(), except for the following differences :
- If a connection to the same AS/400 server, same user profile and password, already exists within the current web server process, and if it is available, it will be reused.
- If such a connection doesn’t exist, a new one is created, and kept 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<BR>";
} else {
echo "No connection ID stored.<BR>";
}
// I5_OPTIONS_PRIVATE_CONNECTION connection is private for the session
// I5_OPTIONS_IDLE_TIMEOUT After a delay with no activity, the job will end.
echo " New connection. Do some job initialization <BR>";
/* leaves connection without closing it. */
/* Make it available for another script. */
$ret = i5_close($conn);
if (!$ret) trigger_error("i5_pclose error : ".i5_errormsg(), E_USER_ERROR);
} else {
$ret = i5_pclose($conn);
if (!$ret) trigger_error("i5_pclose error : ".i5_errormsg(), E_USER_ERROR);
}
}
echo " I5 disconnected<BR>";
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 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.
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
options Connection options in an associative array.
See below details about connection options.
Option Description
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".
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: True if OK, false if failed.
I5_ERR_MEMALLOC 3 Not enough memory
I5_ERR_PHP_HDLCONN 257 This resource has no connection active.
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
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.
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()
Returns: True if OK, false if failed.
Error returned
I5_ERR_DESC_WRONG_DATAOP 41 Wrong operation on a data field of a description
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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");
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.
connection Connection resource - result from i5_connect() or i5_pconnect()
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
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.
Modified records remain locked.
Changes are not showed.
I5_ISOLEVEL_ALL RS REPEATABLE READ
Read records remain locked.
Modified 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'");
$res = i5_query("SELECT count(*) FROM animals");
$rec = i5_fetch_array($res);
echo $res[0] . "\n";
/* Transaction and DELETE request validation */
i5_commit($conn);
$res = i5_query("SELECT count(*) FROM animals");
$rec = i5_fetch_array($res);
echo $rec[0] . "\n";
i5_close($conn);
}
?>
?>
See also
i5_commit
i5_rollback
i5_commit
Validates current transaction.
bool i5_commit ( string comment
[, resource connection] )
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
connection Connection ID
Returns: TRUE if transaction is valid, FALSE in case of error.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_HDLCONN 257 This resource has no connection active.
I5_ERR_PHP_RESOURCE_BAD 261 No resource found .
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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
Example
$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);
/* 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)");
$res = i5_query("SELECT count(*) FROM animals");
$rec = i5_fetch_array($res);
echo $rec[0] . "\n";
/* Transaction and DELETE request validation */ i5_commit($conn);
$res = i5_query("SELECT count(*) FROM animals");
$rec = i5_fetch_array($res);
echo $rec[0] . "\n";
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
connection Connection ID(optional)
Returns:
True if OK, false if failed.
I5_ERR_DESC_WRONG_DATAOP 41 Wrong operation on a data field of a description
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.
Connection Easycom Connection - Result of i5_connect() or i5_pconnect().
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.
This function loads Procedure or Program definitions from an immediate PCML or simplified RPG source.
bool i5_XmlDefine ( string Source_type
, string Source_String
[, resource Connection ] )
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
Connection Easycom Connection - Result of i5_connect() or i5_pconnect().
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.
This function loads Procedure or Program definitions from RPG or PCML source files.
bool i5_XmlLoadDefinition ( string Source_type
, string Source_File
[, resource Connection ] )
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.
Connection Easycom Connection - Result of i5_connect() or i5_pconnect().
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.
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");
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.
connection Result of i5_connect
Returns: Resource if open succeeded, false if open failed.
I5_ERR_DESC_WRONG_DATAOP 41 Wrong operation on a data field of a description
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 ";".
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
connection Connection ID(optional)
Returns:
True if OK, false if failed.
I5_ERR_DESC_WRONG_DATAOP 41 Wrong operation on a data field of a description
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_VARIABLE 281 You can't use the I5_bind_param function and specify parameters
I5_ERR_PHP_EMPTY_NAME 314 Object name can not be empty
Example
$ret = i5_get_system_value('QSYSLIBL');
echo 'QSYSLIBL: ' .$ret. '<BR>';
$ret = i5_get_system_value('QSRLNBR');
echo 'Serial number: '.$ret.'<BR>';
Native database access
i5_open
Opens native i5 file.
resource i5_open ( string filename [, int mode ]
[, resource connection])
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:
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.
I5_ERR_DESC_WRONG_DATAOP 41 Wrong operation on a data field of a description
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
bool i5_seek ( resource file ,
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:
True if OK, false if failed.
Error returned
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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 "<BR>";
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 ]
[, int Last_field_len ] )
Details
The key value for the current record is compared to the key value provided to the latest i5_seek function call.
Parameters
File i5 file resource.
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
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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); if (is_bool($rec))
$ret = i5_match($file); if ($ret) echo "Record found<BR>"; else echo "Record no found<BR>"; /* 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)
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.
"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: True if OK, false if failed.
Error returned
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_VARIABLE 281 You can't use the I5_bind_param function and specify parameters
Example
$file = i5_open('EASYCOM/NCLIENT');
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 : <BR>';
i5_seek($file, I5_FIRST);
while ($tab = i5_fetch_row($file)) {
printf('%s (%s)<BR>', $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.
"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:
True if OK, false if failed.
Error returned
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_VARIABLE 281 You can't use the I5_bind_param function and specify parameters
Example
$file = i5_open('EASYCOM/NCLIENT');
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 : <BR>';
i5_seek($file, I5_FIRST);
while ($tab = i5_fetch_row($file)) {
printf('%s (%s)<BR>', $tab[3], $tab[2]);
}
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:
True if OK, false if failed.
Error returned
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_VARIABLE 281 You can't use the I5_bind_param function and specify parameters
Example
$file = i5_open('EASYCOM/NCLIENT');
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 : <BR>';
i5_seek($file, I5_FIRST);
while ($tab = i5_fetch_row($file)) {
printf('%s (%s)<BR>', $tab[3], $tab[2]);
}
$ret = i5_range_clear($file);
if (!$ret) trigger_error('i5_range_clear error : '.i5_errormsg(), E_USER_ERROR);
Frees i5_open opened file resources and closes it on I5
Parameters
file I5 file resource
Additional functions to the existing API.
Returns: True if OK, false if failed.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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:
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.
Returns: True if OK, false if failed.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
$table = array('C-105', 'DUPOND', 'Jean', 'Avenue du Québec',
'Les Ulis', 3, 'FR');
$ret= i5_setvalue($ret, $table);
$ret = i5_update($res);
}
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_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_DTAQ_BADKEY 309 The key is not correct.
Sends SQL request and possibly collects results set.
resource i5_query ( string query
[, resource connection])
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.
I5_ERR_DESC_WRONG_DATAOP 41 Wrong operation on a data field of a description
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
Example:
/* Straight request execution */
$query = i5_query('SELECT * FROM EASYCOM/SP_CUST');
if(is_bool($query)){
echo "Error code: " . i5_errno() . "<br>";
echo "Error message: " . i5_errormsg() . "<br>";
}
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 "<td>" .$values[1]. "</td>";
echo "<td>" .$values[2]. "</td>";
echo "<td>" .$values[3]. "</td>";
echo "<td>" .$values[4]. "</td>";
echo "<td>" .$values[5]. "</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
[, resource connection] )
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.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_HDLCONN 257 This resource has no connection active.
I5_ERR_PHP_RESOURCE_BAD 261 No resource found .
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
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);
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
Returns: True if OK, false if failed.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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);
$result = i5_execute($req, $animals);
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
Returns: True if OK, false if failed.
I5_ERR_PHP_HDLBAD 258 Bad connection handle
I5_ERR_PHP_RESOURCE_BAD 261 No resource found .
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_CALL_BINDPARAM 274 The I5_bind_result function can be called only once
I5_ERR_PHP_VARIABLE 281 You can't use the I5_bind_param function and specify parameters
Example
$conn = i5_connect("MY_AS", "USER", "PASSWORD");
if ($conn) {
$req = i5_prepare($conn, "INSERT INTO Language VALUES (?, ?, ?)");
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.
I5_ERR_PHP_HDLBAD 258 Bad connection handle
I5_ERR_PHP_RESOURCE_BAD 261 No resource found .
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_CALL_BINDPARAM 274 The I5_bind_result function can be called only once
I5_ERR_PHP_VARIABLE 281 You can't use the I5_bind_param function and specify parameters
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)) {
$ret = i5_execute($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);
If ($ret === FALSE){
$msg = i5_errormsg();
trigger_error("Error : , ".$msg , E_USER_ERROR);
}
/* Values */
$tabResult = i5_fetch_assoc($req);
while (!is_bool($tabResult)) {
printf("%s %s<BR>", $col1, $col2);
$tabResult = i5_fetch_assoc($req);
}
/* 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_HDLBAD 258 Bad connection handle
I5_ERR_PHP_RESOURCE_BAD 261 No resource found .
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_VARIABLE 281 You can't use the I5_bind_param function and specify parameters
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 (?, ?, ?, ?)';
$req = i5_prepare($insert);
if (is_bool($req)) trigger_error('i5_prepare error : '.i5_errormsg(),
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:
True if OK, false if failed.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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))
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
connection Connection ID(optional)
Returns: lines number (integer) or –1 in case of invalid request.
Example
$query = "INSERT INTO Cities2 SELECT * FROM Cities WHERE Code LIKE
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
Returns: True if OK, false if failed.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_CALL_BINDPARAM 274 The I5_bind_result function can be called only once
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
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
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.<BR>", $nb_lines);
$obj = i5_fetch_object($result);
printf("%s (%s)<BR>", $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_MEMALLOC 3 Not enough memory
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_GETPARAM 275 specific message
Example
/* Page selection and reading */
$file = i5_open('EASYCOM/NCLIENT');
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);
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_MEMALLOC 3 Not enough memory
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_GETPARAM 275 specific message
Example
/* Page selection and reading */
$file = i5_open('EASYCOM/NCLIENT');
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);
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_MEMALLOC 3 Not enough memory
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_GETPARAM 275 specific message
Example
/* Page selection and reading */
$file = i5_open('EASYCOM/NCLIENT');
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);
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_MEMALLOC 3 Not enough memory
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_GETPARAM 275 specific message
Example
/* Page selection and reading */
$file = i5_open('EASYCOM/NCLIENT');
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);
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.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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 )
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
Returns: True if OK, false if failed.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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);
$result = i5_execute($req, $animals);
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.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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
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
file I5 file resource
Returns: The ID of the current record that can be used with i5_data_seek() to position on this record again.
I5_ERR_PHP_HDLBAD 258 Bad connection handle
I5_ERR_PHP_RESOURCE_BAD 261 No resource found .
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
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 */
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
Returns: True if OK, false if failed.
I5_ERR_PHP_HDLBAD 258 Bad connection handle
I5_ERR_PHP_RESOURCE_BAD 261 No resource found .
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_CALL_BINDPARAM 274 The I5_bind_result function can be called only once
I5_ERR_PHP_VARIABLE 281 You can't use the I5_bind_param function and specify parameters
Example
$conn = i5_connect("MY_AS", "USER", "PASSWORD");
if ($conn) {
$req = i5_prepare($conn, "INSERT INTO Language VALUES (?, ?, ?)");
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.
I5_ERR_PHP_HDLBAD 258 Bad connection handle
I5_ERR_PHP_RESOURCE_BAD 261 No resource found .
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_CALL_BINDPARAM 274 The I5_bind_result function can be called only once
I5_ERR_PHP_VARIABLE 281 You can't use the I5_bind_param function and specify parameters
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)) {
$ret = i5_execute($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);
If ($ret === FALSE){
$msg = i5_errormsg();
trigger_error("Error : , ".$msg , E_USER_ERROR);
}
/* Values */
$tabResult = i5_fetch_assoc($req);
while (!is_bool($tabResult)) {
printf("%s %s<BR>", $col1, $col2);
$tabResult = i5_fetch_assoc($req);
}
/* 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
bool i5_seek ( resource file ,
int/string operator
[, array keyvalue ]
[, int Last_field_len ] )
Syntax N° 2
bool i5_seek ( resource file ,
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:
True if OK, false if failed.
Error returned
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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 */
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.
Returns: True if OK, false if failed.
I5_ERR_PHP_HDLBAD 258 Bad connection handle
I5_ERR_PHP_RESOURCE_BAD 261 No resource found .
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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
Example
$query = i5_query("SELECT * FROM EASYCOM/SP_CUST");
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 ]
[, int Last_field_len ] )
Details
The key value for the current record is compared to the key value provided to the latest i5_seek function call.
Parameters
File i5 file resource.
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
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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); if (is_bool($rec))
$ret = i5_match($file); if ($ret) echo "Record found<BR>"; else echo "Record no found<BR>"; /* 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)
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
result Resource describing file or other record set.
Returns:
Array containing field names, in order.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
result Resource describing file or other record set
field Integer or string identifying the field position or name.
Returns: Field's length.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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
result Resource describing file or other record set
filed Integer identifying the field position.
Returns: Field's length.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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_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 .
field Integer or string identifying the field position or name.
Returns: Field's type string.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_VARIABLE 281 You can't use the I5_bind_param function and specify parameters
I5_ERR_PHP_ELEMENT_MISSING 304 An element of the array has a wrong type within function_name(type) function.
I5_ERR_PHP_BAD_KEYNAME 306 Name x is not a property name for a program description
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
[, resource connection])
Parameters
name User space name in library/object format
description PHP-format program description.
See: PHP Data Description
connection Result of i5_connect
Returns: Resource if open succeeded, false if open failed.
I5_ERR_DESC_WRONG_DATAOP 41 Wrong operation on a data field of a description
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.
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.
echo ' TCP/IP problem - Connection not possible ';
break;
case I5_CAT_INTERNAL:
echo ' Easycom error - Connection not possible ';
break;
}
echo 'Error number :'. i5_errno() . '<BR>';
echo 'Error message :'. i5_errormsg() .'<BR>';
}
$conn = i5_connect('p520', 'QPGMR', 'LAUNCHER');
if ($conn == FALSE) {
$err = i5_error();
print_r($err);echo '<BR>';
switch ($err["cat"]) {
case I5_CAT_TCPIP:
echo ' TCP/IP problem - Connection not possible ';
break;
case I5_CAT_INTERNAL:
echo ' Easycom error - Connection not possible ';
break;
}
echo 'Error number :'. i5_errno() . '<BR>';
echo 'Error message :'. i5_errormsg() .'<BR>';
}
echo "Connected : $conn<BR>";
$file = i5_open('EASYCOM/NCLIENT', I5_OPEN_READ);
if (is_bool($file)) trigger_error('i5_open error : '.i5_errormsg(),
E_USER_ERROR);
/* testing file edition */
$edition = i5_edit($file);
if ($edition == FALSE) {
switch (i5_errno()) {
case I5_ERR_INVALIDOPENMODE:
echo 'Openning a file in writing to enable modification<BR>';
break;
case I5_ERR_RECORDNOTFOUND:
echo 'Pointing a record before modification<BR>';
break;
case I5_ERR_RECORDLOCKED:
echo 'Locked record...<BR>';
break;
}
}
/* SLQ request test */
$query = i5_query("SELECT * FROM EASYCOM/NOT_EXIST");
If ($query == FALSE){
$error = i5_error();
echo 'SQL error code: ' . i5_errno() . '<br>';
echo 'Error message: ' . i5_errormsg() . '<br>';
echo 'Error information : ';print_r($error);echo '<BR>';
}
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
connection Connection - result of i5_connect.
Returns:
Error message string.
I5_ERR_DESC_WRONG_DATAOP 41 Wrong operation on a data field of a description
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.
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;
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.
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>
Attribute Value Description
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.
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>
Attribute Value Description
<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"> <!-- PCML source for calling "Retrieve user Information" (QSYRUSRI) API --> <!-- Format USRI0150 - Other formats are available --> <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 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.
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.
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<
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
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:
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.
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_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_FIRST Read the first record
I5_READ_LAST Read the last 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.
I5_ERR_MEMALLOC 3 Not enough memory
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
I5_ERR_PHP_LIST_PROP 267 This element 0¡ is not accepted.
I5_ERR_PHP_CALL_BINDPARAM 274 The I5_bind_result function can be called only once
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
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_FIRST Read the first record
I5_READ_LAST Read the last 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.
I5_ERR_MEMALLOC 3 Not enough memory
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
Returns result line as object or NULL if there is no more line.
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_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_PREV Read previous record
I5_READ_FIRST Read first record
I5_READ_LAST Read last record
I5_READ_SEEK Read current 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.
I5_ERR_MEMALLOC 3 Not enough memory
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
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:
True if OK, false if failed.
I5_ERR_PHP_HDLDFT 256 No default connection found.
I5_ERR_PHP_OPTIONSTYPE 259 The type of " I5_OPTIONS_ALIAS" option must be x and not x
I5_ERR_PHP_OPTIONSNUMBER 260 Option number -1 is unknown.
I5_ERR_PHP_TYPEPARAM 262 Type of element x in parameter -1 must be y. Type z was provided.
Example
$invoices = i5_open('easycom/s_order'); if (is_bool($invoices))