PHP Toolkit Functions
PHP Toolkit Functions
In this Topic ShowHide
All PHP Toolkit functions start with prefix "i5".
Connection Management
i5_connect
resource i5_connect(string server, string user, string password[, array options]).
- Description: Connects to the AS/400 server.
- Return Values: AS/400 connection resource or false on failure.
- Arguments:
-
- server - Name of the server to connect to. This can be either a symbolic name or an IP.
- user - Username to use for connecting.
Note: Username QSECOFR cannot be used in this function.
- password - Password for the username
- options - Connection options.
Example:
$conn = i5_connect("1.2.3.4", "MYUSER", "MYPWD");
if (!$conn) {
die(i5_errormsg());
}
Connection Options:
I5_OPTIONS_JOBNAME - job name (machine name by default)
I5_OPTIONS_SQLNAMING - Enables using dotted (.) or slashed (/) notation in SQL requests
I5_OPTIONS_DECIMALPOINT - Enables using dot or comma as decimal separator
I5_OPTIONS_CODEPAGEFILE - Enables using specific code page (CCSID)
I5_OPTIONS_ALIAS - Enables naming a connection. If the name is used in another i5_connect, then the other i5_connect will use the same connection.
I5_OPTIONS_INITLIBL - Specified libraries are added to the beginning of the initial library list.
I5_OPTIONS_LOCALCP - Sets the local code page used by PHP application.
I5_OPTIONS_RMTCCSID - Sets the EBCDIC CCSID
i5_pconnect
resource i5_pconnect(string server, string user, string password[, array options]).
- Description: Returns a persistent connection to the i5/OS server. This function acts like i5_connect(), with the following differences:
- The connection does not disappear after the web request completion. It will keep job environment information such as library lists, etc.
- The connection can be reused for another web request if the request contains the same server id, user and password used in the previous web request.
- If the previous connection doesn’t exist, a new connection will be created, and will be kept open until the PHP script ends.
- A subsequent call to i5_close() will not close the connection.
- Use i5_pclose() to close the connection opened by i5_pconnect() function.
- Return Values: i5/OS connection resource or false on failure.
- Arguments:
-
- server - Name of the server to connect to. This can be either a symbolic name or an IP.
- user - Username to use for connecting.
Note: Username QSECOFR cannot be used in this function.
- password - Password for the username
- options - Connection options.
Example - Basic Connection
/* Basic connection to i5/OS */
$conn = i5_pconnect("i.2.3.4","USER","PWD", array(i5_OPTIONS_IDLE_TIMEOUT=>120))
or die(i5_errormsg());
echo " Connection OK <BR>";
/* Connection error detail in case of failure */
$conn = i5_pconnect("i.2.3.4","MYUSER","MYPWD");
if (!$conn) {
$error = i5_error();
echo " Error during connection\n";
echo "<BR> Error number: ".$error["num"];
echo "<BR> Error category: ".$error["cat"];
echo "<BR> Error message: ".$ error ["msg"];
echo "<BR> Error description: ".$ error ["desc"];
trigger_error("I5 persistent connection fails", E_USER_ERROR);
}
else {
echo " Connection OK ";
$isnew = i5_get_property(I5_NEW_CONNECTION);
if ($isnew) ) {
echo " New connection. Do some job initialization \n";
}
}
/* leaves connection without closing it. */
/* Make it available for another script. */
$ret = i5_close($conn);
if($ret){
echo " I5 disconnected";
}
else
{
$ret = i5_errormsg($conn);
}
Example - Private Connection
<?php
/* Private connection to i5/OS */
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.
$retcon = i5_pconnect ('SYSTEMI', "USER", "pwd",
array(
I5_OPTIONS_PRIVATE_CONNECTION => $conId,
I5_OPTIONS_IDLE_TIMEOUT=>"60"));
if (is_bool($retcon) && $retcon == FALSE)
{
$errorTab = i5_error();
if ($errorTab['cat'] == 6 && $errorTab['num'] == -12){
echo "Connection ID no longer active<BR>";
$_SESSION['connectionID'] = 0;
} else
print_r($errorTab);
}
else
{
if ($conId == 0)
{
//Session varaible was 0: Get connection ID and store it in session variable.
$ret = i5_get_property(I5_PRIVATE_CONNECTION, $retcon);
if (is_bool($ret) && $ret == FALSE)
{
$errorTab = i5_error();
print_r($errorTab);
}
else
{
// Connection ID is stored in session variable
$_SESSION['connectionID'] = $ret;
}
}
}
?>
Connection Options:
- I5_OPTIONS_IDLE_TIMEOUT - sets the time ( in seconds) to raise an event when the connection can be closed by another connection request (i5_connect or i5_pconnect). If this option is not used the connection job will remain open.
- I5_OPTIONS_PRIVATE_CONNECTION - Set the ID of the persistent connection to reuse.
- I5_OPTIONS_JOBNAME - job name (machine name by default).
- I5_OPTIONS_SQLNAMING - Enables using dotted (.) or slashed (/) notation in SQL requests.
- I5_OPTIONS_DECIMALPOINT - Enables using dot or comma as decimal separator.
- I5_OPTIONS_CODEPAGEFILE - Enables using specific code page (CCSID).
- I5_OPTIONS_ALIAS - Enables naming a connection. If the name is used in another i5_connect, then the other i5_connect will use the same connection.
- I5_OPTIONS_INITLIBL - Specified libraries are added to the beginning of the initial library list.
- I5_OPTIONS_LOCALCP - Sets the local code page used by PHP application.
- I5_OPTIONS_RMTCCSID - Sets the EBCDIC CCSID
i5_pclose
bool i5_close([resource connection]).
- Description: Closes the persistent connection to i5/OS server..
- Return Values: Boolean success value.
- Arguments:
- connection - Result of i5_pconnect
Example:
/* Basic connection to i5/OS */
$conn = i5_pconnect("("i.2.3.4","USER","PWD")
if ($conn) {
echo "Connection succeeds <BR>";
[treatments...]
$closing = i5_pclose($conn);
if ($closing) {
echo "Disconnection succeeds";
}
}
i5_get_property
int/string i5_get_property(int Property, [resource connection]).
- Description: Gets a connection status for a connection opened either by i5_pconnect () or i5_connect ()
- Return Values:
-
- - 0 : The connection to i5/OS was already opened by the previous PHP script via i5_pconnect().
- - 1 : New connection which was not used by another PHP script.
- Arguments:
-
- Property - I5_NEW_CONNECTION
- connection - Result of i5_pconnect or i5_connect ()
Example:
$isnew = i5_get_property(I5_NEW_CONNECTION, $conn);
i5_close
bool i5_close([resource connection]).
- Description: Closes connection to AS/400 server.
- Return Values: Boolean success value.
- Arguments: connection - Result of i5_connect
i5_adopt_authority
bool i5_adopt_authority(string username, string password, [resource connection]).
- Description: Changes authority of the connection to a specific user. All actions will be executed as this user from now on.
- Return Values: Boolean success value.
- Arguments:
-
- username - Name of the user to change to
- password - Password for the user
- connection - Connection - result of i5_connect
i5_error
bool i5_error([resource connection]).
- Description: Retrieves error information for last action that was executed.
- Return Values: If there was no error, returns false. Otherwise, returns an array with the following elements:
-
- 0 - error number, as in i5_errno().
- 1 - error category.
- 2 - error message, as in i5_errmsg().
- 3 - detailed description of the error.
- Arguments: connection - Connection - result of i5_connect
i5_errormsg
string i5_errormsg([resource connection]).
- Description: Gets error message for last executed action.
- Return Values: Error message string.
- Arguments: connection - Connection - result of i5_connect.
Back to Top
CL Calls
i5_command
bool i5_command(string command[, array inputs, array outputs, resource connection]).
- Description: Calls CL command.
- Return Values: Boolean success value.
- Arguments:
-
- inputs - Array of name => value parts, name describing the call input parameters.
Names should match i5 cl command parameter names.
If the array is empty or not provided, no input parameters are given. If the value is integer, integer is passed, if the value is string, quoted string is passed. If the value is an array, the list of contained values is passed.
Note: The output parameter is required if the input parameter is specified.
- outputs - Array which describes output parameters of the command. If not provided, no output parameters are defined.
Key of the array defined i5 cl command parameter name.
"rc" is a predefined name containing the result of the command.
Value can be string. If so - it defines a php variable name to accept the parameter or array; it should have 2 elements:
-
A php variable name to accept the parameter.
-
Description of the parameter
Note: The input parameter is required if the output parameter is specified.
-
- connection - Connection - result of i5_connect.
Example:
i5_command("rtvjoba", array(), array("curlib" => "curl",.
"user"=>"user",.
"usrlibl" => "userlib",.
"syslibl" => array("syslib", "char(165)"), .
).
);.
print "User : $user<br>" ;.
print "User library : $userlib<br>" ;.
print "System libs list : $syslib<br>" ;.
print "Current library : $curl<br>" ;.
Back to Top
Program Calls
i5_program_prepare
resource i5_program_prepare(string name[, array description][, resource connection]).
- Description: Opens a program and prepares it to be run.
- Return Values: Resource if open succeeded, false if open failed.
- Arguments:
-
- name - Program name. If a service procedure call is made, the procedure name is given in parentheses, e.g. Lib/Service_Program(PROC)
- description - PHP-format program description. This should be provided if the program is not described on server.
See PHP Toolkit Data Description for more information.
- connection - Result of i5_connect
i5_program_prepare_PCML
resource i5_program_prepare_PCML (array description[, resource connection]).
- Description: Opens a program PCML file and prepares it to be run.
- Return Values: Resource if open succeeded, false if open failed.
- Arguments:
- description - PCML file’s program and parameters information
- connection - Result of i5_connect
The program information file (in PCML format) can be created by compiling the RPG program.
Example:
CRTBNDRPG PGM(EACDEMO/TESTSTRUC) SRCFILE(EACDEMO/QRPGLESRC) SRCMBR(TESTSTRUC) PGMINFO(*PCML) INFOSTMF('/www/zendSvr/htdocs/teststruc.pcml')
The PCML file will contain the program parameters info. There are two ways you can assign the program parameters to i5-program_prepare_PCML description:
Copy the content of PCML file to you PHP script and assign the i5_program_prepare_PCML description array to the PCML content. See PCML Example 1 (below).
Assign i5_program_prepare description array to the PCML file located in the same PHP program directory. See PCML Example 2 (below.
PCML Example 1:
$description = "<pcml version=\"4.0\">
<!-- RPG module: TESTSTRUC -->
<!-- created: 2006-10-12-11.46.56 -->
<!-- source: EACDEMO/QRPGLESRC(TESTSTRUC) -->
<!-- 5 -->
<struct name=\"S2\">
<data name=\"ZOND2\" type=\"zoned\" length=\"10\" precision=\"5\" usage=\"inherit\" />
<data name=\"PACK2\" type=\"packed\" length=\"19\" precision=\"5\" usage=\"inherit\" />
<data name=\"PACK3\" type=\"packed\" length=\"19\" precision=\"5\" usage=\"inherit\" />
<data name=\"ALPH2\" type=\"char\" length=\"20\" usage=\"inherit\" />
</struct>
<!-- 1 -->
<struct name=\"S1\">
<data name=\"ZOND\" type=\"zoned\" length=\"10\" precision=\"5\" usage=\"inherit\" />
<data name=\"PACK1\" type=\"packed\" length=\"19\" precision=\"5\" usage=\"inherit\" />
<data name=\"ALPH1\" type=\"char\" length=\"10\" usage=\"inherit\" />
</struct>
<program name=\"TESTSTRUC\" path=\"/QSYS.LIB/EACDEMO.LIB/TESTSTRUC.PGM\">
<data name=\"CODE\" type=\"char\" length=\"10\" usage=\"output\" />
<data name=\"S1\" type=\"struct\" struct=\"S1\" usage=\"inputoutput\" />
<data name=\"S2\" type=\"struct\" struct=\"S2\" usage=\"inputoutput\" />
<data name=\"PACK\" type=\"packed\" length=\"1\" precision=\"1\"
usage=\"output\" />
<data name=\"CH10\" type=\"char\" length=\"19\" usage=\"output\" />
<data name=\"CH11\" type=\"char\" length=\"20\" usage=\"output\" />
<data name=\"CH12\" type=\"char\" length=\"29\" usage=\"output\" />
<data name=\"CH13\" type=\"char\" length=\"33\" usage=\"output\" />
</program>
</pcml>
";
PCML Example 2:
($description = file_get_contents("/www/zendSvr/htdocs/teststruc.pcml"))
or trigger_error("Error while opening PCML file", E_USER_ERROR);
i5_program_call
bool i5_program_call(resource program, array params[, array retvals]).
Example:
$prog = i5_program_prepare("DEMOPGM");.
if(i5_program_call($prog, array(1,2,"abc"))) {.
$result = i5_fetch_assoc($prog);.
print "result is $result['retval']<br>";.
} else {.
print "Program call failed.<br>";.
}.
Note:
Use i5_COMMAND in order to invoke a program without parameters. For example, i5_command("call LIB_NAME/PROGRAM_NAME").
i5_program_close
void i5_program_close(resource program).
- Description: Frees program resource handle.
- Return Values: Boolean success value.
- Arguments: program - Program resource opened by program_open.
Back to Top
Data Retrieval
i5_fetch_array
array i5_fetch_array(resource result [, int option ] ).
array i5_fetch_assoc(resource result [, int option ] ).
object i5_fetch_object(resource result [, int option ] ).
array i5_fetch_row(resource result [, int option] ).
- Description: Fetches a row of data from the resource.
- Return Values: 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.
- Arguments:
-
- result - Resource resulting from operation returning data
- option - Flag specifying which record to fetch.
- Current record - I5_READ_SEEK
- Next record - I5_READ_NEXT
- Previous record - I5_READ_PREV
- First record - I5_READ_FIRST
- Last record - I5_READ_LAST
- Default is I5_READ_NEXT
i5_info
array i5_info ( resource result [, int/string field ] ).
- Description: Gets information about the file/record.
- Return Values: An array with information about record. If there is no way to return whole information; false is returned when the field parameter is omitted.
- Arguments:
- result - Resource describing file or other record set
- field - Integer or string identifying the field. If this parameter is omitted, whole file information is given (when possible).
i5_field_len
int i5_field_len ( resource result, int/string field ).
- Description: Gets field length.
- Return Values: field's length.
- Arguments:
- result - Resource describing file or other record set
- field - Integer or string identifying the field position or name.
i5_field_name
int i5_field_name ( resource result, int field ).
- Description: Get field name.
- Return Values: field's length.
- Arguments:
- result - Resource describing file or other record set
- field - Integer identifying the field position.
i5_field_scale
int i5_field_scale ( resource result, int/string field ).
- Description: Gets field scale - number of digits for numeric fields.
- Return Values: The number of digits of the field. If the field is not numeric, returns -1.
- Arguments:
- result - Resource describing file or other record set
- field - Integer or string identifying the field position or name.
i5_field_type
string i5_field_type ( resource result , int/string field ).
- Description: Gets field type.
- Return Values: Field's type string.
- Arguments:
- result - Resource describing file or other record set .
- field - Integer or string identifying the field position or name.
i5_list_fields
array i5_list_fields ( resource result ).
- Description: Gets list of fields for resource.
- Return Values: Array containing field names, in order.
- Arguments:
- result - Resource describing file or other record set.
i5_num_fields
int i5_num_fields ( resource result ).
- Description: Get the numbers of fields for resource.
- Return Values: Number of fields.
- Arguments:
- result - Resource describing file or other record set.
i5_result
mixed i5_result ( resource result, int/string field]).
- Description: Gets one field of the result.
- Return Values: Field's contents in current record.
- Arguments:
- result - Resource describing file or other record set.
- field - Integer or string identifying the field position or name.
Back to Top
Native File Access
i5_open
resource i5_open (string fileName [, int mode ][,resource connection]).
- Description: Opens native i5 file.
- Return Values: Resource, if "open" is successful, false otherwise.
- Arguments:
-
- name - File name, may include library
- mode - File mode to use:
-
- I5_OPEN_READ - default
- I5_OPEN_READWRITE
- I5_OPEN_COMMIT
- I5_OPEN_SHRRD
- I5_OPEN_SHRUPD
- I5_OPEN_SHRNUPD
- I5_OPEN_EXCLRD
- I5_OPEN_EXCL
- connection - Connection - result of i5_connect
Note:
OPEN_READ or I5_OPEN_READWRITE modes are required to be combine with other modes. For example, $ret = i5_open ("LIB/FILE", I5_OPEN_READWRITE | I5_OPEN_EXCL);
i5_addnew
bool i5_addnew ( resource file [, int mode] ).
- Description: 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.
- Return Values: Resource if open succeeded, false if "open" failed.
- Arguments:
-
- file - Opened i5 file.
- mode - I5_ADDNEW_CLEAR: clears all record fields (default).
- I5_ADDNEW_NOCLEAR: does not clear all record fields
i5_edit
bool i5_edit ( resource file [, int mode] ).
- Description: 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.
- Return Values: Boolean success value. Returns false if the record is already being edited by other used.
- Arguments:
-
- file - i5 file resource.
- 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.
i5_delete
bool i5_delete ( resource file ).
- Description: Remove current record.
- Return Values: Boolean success value. Return is false if the record is already being edited by other used.
- Arguments:
-
- file - i5 file resource.
- i5_cancel_edit
- bool i5_cancel_edit ( resource result ).
i5_setvalue
bool i5_setvalue (resource file, int/string field, mixed value).
bool i5_setvalue (resource file, array values ).
- Description: Changes the value of the current record. The record should be in edit mode after i5_edit() or created by i5_addnew().
- Return Values: Boolean success value.
- Arguments:
-
- file - i5 file resource.
- field - Field identifier by name or position.
- value - Value for the field.
- values - Set of key=>value parts describing fields to change and their new values.
i5_update
bool i5_update ( resource file ).
- Description: Commits changes done to the file record after i5_edit() or i5_addnew() into the file.
- Return Values: Boolean success value.
- Arguments: file - i5 file resource.
i5_range_from
bool i5_range_from ( resource file,bool included,array values).
- Description: 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.
- Return Values: Boolean success value.
- Arguments:
-
- 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.
i5_range_to
bool i5_range_to (resource result,bool included, array values ).
- Description: 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.
- Return Values: Boolean success value.
- Arguments:
-
- 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.
i5_range_clear
bool i5_range_clear (resource file).
- Description: Removes range. Reverses the action of range_from() and range_to().
- Return Values: Boolean success value.
- Arguments: file - i5 file resource
i5_data_seek
bool i5_data_seek (resource result, int record_number).
- Description: Seeks to a specific record of the result.
- Return Values: Boolean success value.
- Arguments:
-
- file - i5 file resource.
- Record_number - Number of the record to seek to, starting from 0.
i5_seek
bool i5_seek (resource file, int/string operator, array keyValue).
- Description: Goes to a specific record in query/file.
- Return Values: Boolean success value.
- Arguments:
-
- file - i5 file resource
- operator - Comparison operator. Position is set to first record satisfying the operator. Available operators:
- I5_EQ "="
- I5_GT ">"
- I5_LT "<"
- I5_GE ">="
- I5_LE "<="
- keyValue - values of the keys to compare
i5_bookmark
int i5_bookmark (resource file).
- Description: Return Values the ID of the current record.
- Return Values: The ID of the current record that can be used with i5_data_seek() to position on this record again.
- Arguments: file - i5 file resource.
i5_free_file
bool i5_free_file (resource file).
- Description: Closes file handle and frees file resources.
- Return Values: Boolean success value.
- Arguments:
-
- file - i5 file resource.
- Additional functions to the existing API.
i5_new_record
bool i5_new_record (resource file, array data).
- Description: Creates a new record in the file and inserts data into it.
- Return Values: Boolean success value.
- Arguments:
-
- file - Opened i5 file resource.
- data - Array of data fields conforming to file description.
- Can be either a flat array or key-value pairs, e.g., i5_setvalue arguments.
i5_update_record
bool i5_update_record (resource file, array data).
- Description: Updates the current row with given data.
- Return Values: Boolean success value.
- Arguments:
-
- file - Opened i5 file resource.
- data - Array of data fields conforming to file description.
- Can be either flat array or key-value pairs, like i5_setvalue arguments.
Example:
$file = i5_open("API/TESTFILE", I5_OPEN_READWRITE);.
$rec = i5_fetch_row($file, I5_READ_FIRST);.
i5_update_record($file, array("CODE" => "C-02", "NOM" => "DUPONT", "TYPE" => 3));.
i5_new_record($file, array('C-105', 'DUPOND', 'Jean', 'Avenue du Qubec', 'Les Ulis', 3, 'FR'));.
i5_delete_record
bool i5_delete_record(resource file).
-
Description: Removes current record.
-
Return Values: Boolean success value. False value is returned if the record is already being edited by other used.
-
Arguments: File - Opened i5 file resource.
Example:
$file = i5_open("API/TESTFILE", I5_OPEN_READWRITE);.
i5_new_record($file, array('C-105', 'DUPOND', 'Jean', 'Avenue du Qubec', 'Les Ulis', 3, 'FR'));.
$rec = i5_fetch_row($file, I5_READ_FIRST);.
i5_update_record($file, array("CODE" => "C-02", "NOM" => "DUPONT", "TYPE" => 3));.
i5_delete_record($file);
i5_get_keys
array i5_get_keys(resource file).
- Description: Gets information about key fields in the file.
- Return Values: An array of integers specifying positions for key fields in the file. Can then use i5_info to discover descriptions of these fields.
- Arguments:
-
- file - Opened i5 file resource.
Back to Top
SQL File Access
i5_query
resource i5_query ( string query [, resource connection] )
- Description: Executes an SQL statement directly
- Return Values: For SELECT request returns resource if statement was executed successfully and FALSE in case of error. For INSERT, UPDATE and DELETE requests returns TRUE if statement was executed successfully and FALSE in case of error.
Note:
i5_query function is suitable for SQL requests without parameters. If you plan to issue the same SQL statement with different parameters, consider using i5_prepare() and i5_execute().
- Arguments:
- Query - SQL request string such as SELECT, INSERT, DELETE, UPDATES and etc
- connection - result of i5_connect
Example:
$query = i5_query("SELECT * FROM EACDEMO/SP_CUST");
if(!$query) {
echo "Error code: " . i5_errno()."
";
echo "Error message: " . i5_errormsg()."
";
}
else {
/* Read records and display */
echo "<table border=1>";
$i = 0;
while ($values = i5_fetch_row($query, I5_READ_NEXT) AND ($i < 10)) {
$i++;
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>";
}
i5_free_query($query);
i5_prepare
resource i5_prepare ( string query [, resource connection] )
- Description: Prepares an SQL statement to be executed
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, PHP Toolkit 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.
- Return Values: Returns a statement resource if the SQL statement was successfully parsed and prepared by the database server. FALSE if the database server returned an error.
- Arguments:
-
- query - SQL request to prepare
- connection - result of i5_connect
i5_bind_result
bool i5_bind_result ( resource result/query, mixed &var1 [,mixed &var2 ...] )
-Or-
bool i5_bind_result ( resource result/query, mixed &var, string namefield )
- Description: Binds a PHP variable to an SQL statement parameter in a statement resource returned by i5_prepare().
- Returns TRUE on success or FALSE on failure.
- Arguments:
-
- query/stmt - 5_prepare prepared request ID
- var1 , &var2 - variables to associate referenced list
- namfield - request field or associated file name
i5_execute
bool i5_execute ( resource stmt [,params] )
- Description: Executes a prepared SQL statement
i5_execute executes an SQL request prepared with i5_prepare. If the SQL statement returns a result set, for example, a SELECT statement or a CALL to a stored procedure that returns one or more result sets, you can retrieve a row as an array from the stmt resource using i5_fetch_array, i5_fetch_assoc or i5_fetch_row. If the request creates several results sets, i5_next_result function moves pointer to the next available 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.. Refer to i5_prepare for a brief discussion of the advantages of using i5_prepare and i5_execute rather than 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.
- Return Values: Returns Boolean and updated stmt resource in case of success FALSE if it fails
- Arguments:
-
- stmt - A prepared statement returned from i5_prepare
- params - Input parameters matching any parameter markers contained in the prepared statement.
Example:
$town = "Paris";
/* Prepare a request */
$req = i5_prepare("SELECT area FROM cities WHERE Name=?");
if ($req) {
/* Associate SQL variables */
i5__bind_param($req, $town);
/* Execute the request */
i5_execute($req);
/* Associate the results variables */
i5_bind_result($req, $region);
/* Read records */
i5_fetch_row($req);
printf("%s is in area %s\n", $town, $region);
i5_getblob
string i5_getblob( resource result, int position )
-Or-
string i5_getblob( resource result, string namefield )
- Description: Reads binary data from a BLOB field type.
This function applies to SELECT type (i5_queryi5_query or i5_executei5_execute) requests containing one or more BLOB type fields.
Note:
Reading and writing a blob requires a transaction.
- Return Values: String with BLOB binary chain or FALSE on failure
- Arguments:
-
- result - File ID
- position - BLOB field index
- namfield - BLOB field name
Example:
/* Specify isolation level UR (COMMIT(*CHG)) */
i5_query( "SET TRANSACTION ISOLATION LEVEL UR" );
/* One of the select filed is a blob column. */
$sql = "SELECT FLD1, FLD2, BLOB_COLUMN FROM BLOB_TABLE";
$res = i5_query($sql);
$line = i5_fetch_row($res, I5_READ_NEXT);
/* element $line[2] contains blob ID */
$blob_data = i5_getblob($res, 2);
/* now the blob can be displayed or processed */
i5_setblob
bool i5_setblob ( resource stmt, int position, string blob )
- Description: Writes a binary data in a BLOB field type.
This function only applies to parameterized requests resources and is used the same way as i5_setparam function.
Note:
Writing a blob requires a transaction.
- Return Values: TRUE on success or FALSE on failure
- Arguments:
-
- result - Parameterized file ID
- position - Parameter index
- blob - Binary chain content
Example:
/* Writing jpeg file content in blob */
$sql = "INSERT INTO CONTACTS (NAME, PRENOM, PHOTO) VALUES
(?,?,?)";
$req_prepa = i5_prepare($sql);
if ($req_prepa) {
$name = "DUPONT";
$prenom = "HENRY";
$file_image = fopen("hdupont.jpg", 'r');
$photo = fread($file_image, filesize($file_image));
$ret0 = i5_setparam($req_prepa, 0, $name);
$ret1 = i5_setparam($req_prepa, 1, $prenom);
$ret2 = i5_setblob($req_prepa, 2, $photo);
$ret = i5_execute($req_prepa);
if ($ret) {echo "Blob writing successful.\n";}
}
i5_bind_param
bool i5_bind_param ( resource stmt, mixed &var1 [, mixed &var2…])
- Description: Binds a PHP variable to an SQL statement parameter in a statement resource returned by i5_prepare().
- Return Values: TRUE on success or FALSE on failure.
- Arguments:
-
- stmt - i5_prepare prepared request ID
- &var1 (…) - Variable to link name
Example:
$conn = i5_connect("MY_i5", "USER", "PASSWORD");
if ($conn) {
$sql = "SELECT * FROM EACDEMO/SP_CUST WHERE CUST_ID >
? FOR FETCH ONLY";
$stmt = i5_prepare($sql);
$lower_limit=1000;
$ret = i5_bind_param( $stmt, &$lower_limit );
$result = i5_execute($stm);
if (!$result) {
echo 'The SQL execute failed ';
echo 'SQLSTATE value: ' . i5_errno();
echo ' Message: ' . i5_errormsg();
}
else
{
//read records using i5_fetch_row(($stmt, I5_READ_NEXT )
}
}
i5_setparam
bool i5_setparam ( resource stmt, int position, mixed value)
- Description: Allocates parameter to parameterized request.
This function is an alternative to i5_bind_param function (automatically linked). It allows explicit value allocation to a parameter.
Note:
Request must be prepared with i5_prepare function.
- Return Values: TRUE on success or FALSE on failure
- Arguments:
-
- stmt - i5_prepare prepared request ID
- position - parameter index (marker) in the request
- value - parameter allocated value
Example 1:
$insert = 'INSERT INTO my_library/animals (id, race, name, weight)
VALUES (?, ?, ?, ?)';
$req = i5_prepare($insert); $animals = array(1, 'cat', 'Mistinguette', 3.2); if ($req) {
$result = i5_execute($req, $animals);
if ($result) {
print "Mistinguette adding successful.<br>";
}
i5_setparam($req, 2, "Hercule");
i5_setparam($req, 3, 3.8);
$result = i5_execute($req);
if ($result) {
print "Hercule adding successful.<br>";
}
Example 2 - Calling stored procedures with IN parameter
The stored procedure in the following example accepts one parameter:
-
-
Create table
-
An input (IN) parameter that accepts the name of the first animal as input
-
An input-output (INOUT) parameter that accepts the name of the second animal as input and returns the string TRUE if an animal in the database matches that name
-
An output (OUT) parameter that returns the sum of the weight of the two identified animals
In addition, the stored procedure returns a result set consisting of the animals listed in alphabetic order starting at the animal corresponding to the input value of the first parameter and ending at the animal corresponding to the input value of the second parameter.
<?php
//
//CREATE TABLE SQL_LIB/TEST2 (A DATE NOT NULL WITH DEFAULT)
//
//
//create procedure SQL_LIB/test_a1(in parm1 date)
//language SQL
//begin
//
//set transaction isolation level UR;
//insert into SQL_LIB/TEST2 values(parm1) ;
//commit;
//end;
$user = 'USER';
$password = 'PASS';
$conn_resource = i5_connect('127.0.0.1',$user,$password );
echo "Begin <br>";
if (!$conn_resource) {
echo i5_errormsg();
exit();
}
$sql = "CALL SQL_LIB/TEST_A1(?)";
$stmt= i5_prepare($sql);
$val = '2007-05-22';
$ret = i5_paramdesc($stmt, I5_TYPE_CHAR, 0, 10, 0, I5_INOUT);
$ret = i5_setparam($stmt, 0, $val);
$result = i5_execute($stmt );
if($result === false){
echo "Execute Error:". i5_errno()." Msg:".i5_errormsg()."<br>";
//echo $err;
}
else {
"<br>executed";
}
echo "<br>end";
?>
i5_paramdesc
bool i5_paramdesc(resource result, int ASType, int sequence, int length, int decimals, int usage).
- Description: Stored procedures parameters descriptions
- Return Values: TRUE on success or FALSE on failure
- Arguments:
-
- Result - i5_prepare prepared request ID
- ASType – Parameter type (e.g. I5_TYPE_PACKED, I5_TYPE_CHAR)
- Sequence – Parameter sequential number (starting from 0)
- Length – Parameter length
- Decimals – Number of decimal position for the numeric parameter type
- Usage – Parameter input/output (I5_IN, I5_OUT our I5_INOUT)
Example:
$storedProcedure = "CALL LIBRARY/PROGRAM(?,?)";
$result =i5_prepare($storedProcedure);
if(!$result)
{
echo("Prepare failed");
exit();
}
// Describe first parameter
$ret = i5_paramdesc($result, I5_TYPE_CHAR, 0, 10, 0, I5_IN);
$val = "ZENDCORE";
$ret = i5_setparam($result, 0, $val);
if(!$ret)
{
echo("Set Param failed");
exit();
}
// Describe second parameter
$ret = i5_paramdesc($result, I5_TYPE_CHAR, 1, 10, 0, I5_INOUT);
$val2 = " ";
$ret = i5_setparam($result, 1, $val2);
if(!$ret)
{
echo("Set Param failed");
exit();
}
$hdl = i5_execute($result);
i5_free_query
bool i5_free_query ( resource query )
- Description: Frees SQL request result
Removes a query type resource (i5_query or i5_execute) from memory
This function needs only to be called if 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. It is recommended to use this function to free memory resource used by SQL request. All memory resources are freed when the SQL request is ended.
- Return Values: TRUE on success or FALSE on failure
- Arguments: query - query resource
Back to Top
Transactions
i5_transaction
bool i5_transaction ( int mode [, resource connection] )
- Description: Starts transaction.
- Return Values: Returns TRUE if transaction has started, FALSE in case of error
- Arguments:
-
- mode - Transaction modes:
-
- I5_ISOLEVEL_CHG - READ UNCOMMITED, READ WRITE (UR)
- Modified records remain locked.
- Modifications are showed
- I5_ISOLEVEL_CS - READ COMMITED (CS)
- Read records are locked.
- Modified records remain locked.
- Changes are not showed
-
I5_ISOLEVEL_ALL - REPEATABLE READ (RS)
- Read records remain locked.
- Modified records remain locked.
- Modifications are not showed.
-
I5_ISOLEVEL_NONE - No transactions
- Each record is commited immediately
- connection - result of i5_connect
Example:
<?php
$conn = i5_connect("MY_i5", "USER", "PASSWORD");
if ($conn) {
$res = i5_query("SELECT count(*) FROM animals");
$rec = i5_fetch_array($res );
echo $rec[0] . "\n";
/* Start a transaction */
i5_transaction(I5_ISOLEVEL_NONE, $conn);
/* Add records to 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";
i5_commit
bool i5_commit( [string comment] [resource connection])
- Description: Commits an in-progress transaction.
- Return Values: TRUE if transaction is valid, FALSE in case of error.
- Arguments:
-
- comment - a transaction comment that will be added to the journal
- Connection - result of i5_connect
Example:
$conn = i5_connect("MY_i5", "USER", "PASSWORD");
if ($conn) {
$res = i5_query("SELECT count(*) FROM animals");
$rec = i5_fetch_array($res );
echo $rec[0] . "\n";
/* Start a transaction */
i5_transaction(I5_ISOLEVEL_NONE);
/* Insert records to ANIMALS table*/
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";
/* Commit the changes */
i5_commit($conn);
$res = i5_query("SELECT count(*) FROM animals");
$rec = i5_fetch_array($res);
echo $rec[0] . "\n";
i5_close($conn);
}
i5_rollback
bool i5_rollback ( [resource connection] )
- Description: Rolls back a transaction.
- Return Values: TRUE on success or FALSE on failure
- Arguments:
- connection - result of i5_connect
Example:
<?php
$conn = i5_connect("127.0.0.1", "USER", "PASSWORD");
if ($conn) {
/* Start a transaction*/
$tran = i5_transaction(I5_ISOLEVEL_CHG);
$res = i5_query("SELECT count(*) FROM my_library/animals");
$rec = i5_fetch_array($res );
echo $rec[0] . "
\n";
/* Delete all records from the ANIMALS table */
$res = i5_query("DELETE FROM my_library/animals");
$res = i5_query("SELECT count(*) FROM my_library/animals");
$err = i5_error();
$rec = i5_fetch_array($res);
echo $rec[0] . "
\n";
/* Cancel the DELETE operation */
i5_rollback($conn);
$res = i5_query("SELECT count(*) FROM my_library/animals");
$rec = i5_fetch_array($res);
echo $rec[0] . "
\n";
i5_close($conn);
}
?>
Back to Top
Data Queues
i5_dtaq_prepare
resource i5_dtaq_prepare(string name, array description [,int key][,resource connection])
- Description: Opens a data queue with optional description.
- Return Values: Resource if OK, false if failed.
- Arguments:
-
- name - The queue name
- description - Data description in format defined by program¬_prepare. For more, see PHP Toolkit Data Description.
- key - key size - for keyed DataQ
- connection - Connection - result of i5_connect
i5_dtaq_receive
mixed i5_dtaq_receive(resource queue[, string/int operator, string key][, int timeout])
- Description: Reads data from the data queue.
- Return Values: False if could not read because of error or timeout, the data read from the queue otherwise.
- Arguments:
-
- queue - resource received from dtaq_open
- operator:
- "EQ"
- "GT"
- "LT"
- "GE"
- "LE"
- key- key value to look for
- timeout - timeout value in seconds
i5_dtaq_send
bool i5_dtaq_send(resource queue, string key, mixed data)
- Description: Puts data to the data queue.
- Return Values: False if could not be written because of error, true otherwise.
- Arguments:
-
- queue - resource received from dtaq_open
- key - key value to look for
- data - data to put into the queue
The data should conform to the description format, and can be either in flat array or key->value pair array.
i5_dtaq_close
bool i5_dtaq_close(resource queue)
- Description: Free program resource handle.
- Return Values: Bool success value.
- Arguments: queue - resource received from dtaq_open
Example 1:
<?php
$description = array("Name"=>"DATA", "Type"=>I5_TYPE_CHAR, "Length"=>50);
$dtaqHdl_KEY = i5_dtaq_prepare("EACDEMO/DTAQ_KEY", $description, 5);
$ret = i5_dtaq_send($dtaqHdl_KEY, "mykey", "the dataqueue test data");
var_dump($ret);
if(!$ret) var_dump(i5_error());
$ret = i5_dtaq_receive($dtaqHdl_KEY, "EQ", "mykey");
var_dump($ret);
?>
Example 2:
<?php
$descriptionC = array("DSName"=>"PS", "DSParm"=>array(
array("Name"=>"PS1", "Type"=>I5_TYPE_CHAR, "Length"=>"10"),
array("Name"=>"PS2", "Type"=>I5_TYPE_PACKED, "Length"=>"10.4"),
array("Name"=>"PS3", "Type"=>I5_TYPE_CHAR, "Length"=>"10")
)
);
$dtaqHdl_KEY = i5_dtaq_prepare("EACDEMO/DTAQ_KEY", $descriptionC, 10);
$parameter = array("PS1"=>"test1", "PS2"=>13.1415, "PS3"=>"test2");
$key = "abcd";
$ret = i5_dtaq_send($dtaqHdl_KEY, $key, $parameter);
var_dump($ret);
$ret = i5_dtaq_receive($dtaqHdl_KEY, "EQ", $key);
var_dump($ret);
?>
Back to Top
System Values
i5_get_system_value
string i5_get_system_value(string name[, resource connection]).
- Description: Retrieves system value
- Return Values: System value, false if not found.
- Arguments:
-
- name - Name of the system value.
- connection - Connection - result of i5_connect.
Example:
print "Date is: ".i5_get_system_value("QDATE");.
Back to Top
User Spaces
i5_userspace_create
bool i5_userspace_create(properties[, resource connection]).
- Description: Creates a new user space object.
- Return Values: Boolean success value
- Arguments:
-
- properties -
-
- I5_INITSIZE - The initial size of the user space being created. This value must be from 1 byte to 16, 776, 704 bytes.
- I5_DESCRIPTION - user space description
- I5_INIT_VALUE - The initial value of all bytes in the user space.
- I5_EXTEND_ATTRIBUT - extended attribute. The extended attribute must be a valid *NAME. For example, an object type of *FILE has an extended attribute of PF (physical file), LF (logical file), DSPF (display file), SAVF (save file), and so on.
- I5_AUTHORITY - The authority you give users who do not have specific private or group authority to the user space
- I5_LIBNAME - Library name where the user space is located
- I5_NAME - User space name (10 char max)
- connection - Result of i5_connect
i5_userspace_prepare
resource i5_userspace_prepare(string name, array description [, resource connection]).
- Description: Opens a user space and prepares it to be run.
- Return Values: Resource if open succeeded, false if open failed.
- Arguments:
-
- name - User space name in library/object format
- description - Data description in format defined by program_prepare. See PHP Toolkit Data Description.
- connection - Result of i5_connect
i5_userspace_get
resource i5_userspace_get(resource user space, array params)
- Description: Retrieve user space data.
- Return Values: Boolean success value.
- Arguments:
-
- user space - User Space resource opened by i5_userspace_prepare
- params - Parameters according to description. If given as flat array, then parameters are assigned in order
i5_userspace_put
bool i5_userspace_put(resource user space, params)
- Description: Add user space data
- Return Values: Boolean success value.
- Arguments:
-
- user - space User Space resource opened by i5_userspace_prepare
- params - Parameters according to description. If given as flat array, then parameters are assigned in order
Back to Top
Job Log List
i5_jobLog_list
resource i5_jobLog_list( [array elements, resource connection] )
- Description: Opens job log.
- Return Values: The resource for fetching job log list if OK and false if failed.
- Arguments:
-
- elements - JobName, JobUser, JobNumber, MaxMessage, Direction (default is current job)
- connection - Result of i5_connect
Use i5_jobLog_list_read function to retrieve the job entries from this handle.
i5_jobLog_list_read
array i5_jobLog_list_read(resource list)
- Description: Get an array for a job log entry.
- Return Values: Array with the message element if OK, false if failed.
- Arguments: list - Resource returned by i5_jobLog_list function
i5_jobLog_list_close
bool i5_jobLog_list_close (resource handle)
- Description: Close handle received from i5_jobLog_list().
- Return Values: Boolean success value
- Arguments: handle - Job list handle as returned by i5_jobLog_list()
Back to Top
Active Job List
i5_job_list
resource i5_job_list( [array elements, resource connection] )
- Description: Open active job list.
- Return Values: The resource for fetching job list if OK and false if failed.
- Arguments:
-
- elements - JobName, JobUser, JobNumber, JobType, Direction (default is current job)
- connection - Result of i5_connect
Use i5_job_list_read function to retrieve the job entries from this handle.
i5_job_list_read
array i5_job_list_read(resource list)
- Description: Get an array for an active job entry.
- Return Values: Array with the job entry element if OK, false if failed.
- Arguments: List - Resource returned by i5_job_list function
i5_job_list_close
bool i5_job_list_close (resource handle)
-
Description: Close handle received from i5_job_list().
-
Return Values: Boolean success value
-
Arguments:
-
handle - Job list handle as returned by 15_job_list()
Back to Top
Data Areas
i5_data_area_create
bool i5_data_area_create(string name, int size[, resource connection]).
- Description: Creates data area of given size
- Return Values: Boolean success value.
- Arguments:
-
- name - Name of the data area.
- size - Size in bytes of the data area.
- connection - result of i5_connect .
i5_data_area_read
string data_area_read(string name[, int offset, int length][, resource connection]).
- Description: Reads data from the area
- Return Values: String data if read successful, false if read failed (including when offset is wrong).
- Arguments:
-
- name - Name of the data area.
- offset - Offset for the data.
- length - Length of the data to read, -1 means whole area.
- connection - Connection - result of i5_connect.
If no offset is specified, all the area is read.
i5_data_area_write
bool data_area_write(string name, string value[, int offset, int length][, resource connection]).
- Description: Writes data to the area
- Return Values: Boolean success value.
- Arguments:
-
- name - Name of the data area.
- value - Value to write.
- Offset - Offset for the data.
- length - Length of the data to read.
- connection - result of i5_connect
If no offset is specified, all the area is written. If value is shorter than length it is padded to the length. If it's longer it is truncated.
i5_data_area_delete
bool data_area_delete(string name[, resource connection]).
- Description: Delete the data area
- Return Values: Boolean success value.
- Arguments:
-
- name - Name of the data area.
- connection - Connection - result of i5_connect.
Back to Top
Spooled File
i5_spool_list
resource i5_spool_list([array description][, resource connection])
- Description: Create an spool file lists, of certain output queue or for all queues.
- Return Values: resource if OK, false if failed
- Arguments:
-
- description - The data by which the sppol files will be filtered, array with following keys:
- username - username that created the job
- outq - qualified name for the output queue containing the spool file
- userdata - the user-supplied key data for the spool file. All keys are optional and can be provided together
- connection - result of i5_connect.
i5_spool_list_read
array i5_spool_list_read(resource spool_list)
i5_spool_list_close
void i5_spool_list_close(resource spool_list)
- Description: Free spool list resource
- Return Values: Boolean success value
- Arguments: Queue - resource received from i5_spool_list
i5_spool_get_data
string i5_spool_get_data(string spool_name, string jobname, string username, integer job_number, integer spool_id [,string filename])
- Description: Get the data from the spool file.
- Return Values: String if no file name passed as parameter, false if function failes
- Arguments:
-
- spool_name - The spool file name
- job_name - The name of the job that created the file
- job_number - The number of the job that created the file
- username - The username of the job that created the file
- spool_id - ID of the spool file in the queue (as returned by outq_read)
- filename - IFS filename to store the data. If not provided, the data is returned as string
Back to Top
Object Listing
i5_objects_list
resource i5_objects_list(string library, [string name, string type, resource connection])
- Description: Open an object list.
- Return Values: Resource for fetch if everything is OK, false on error.
- Arguments:
-
- library - Library name (can be also *CURLIB or I5_CURLIB)
- name - Name or wildcard of objects to read, default is ”r;all”.
- type - Object type to fetch (*ALL or I5_ALL_OBJECTS for all)
- connection - Connection - result of i5_connect
i5_objects_list_read
array i5_objects_list_read (resource list)
- Description: Get an array for an object list entries.
- Return Values: Array with the object element if OK; false if failed.
- Arguments: List - Resource returned by i5_objects_list
i5_ objects_list _close
bool i5_ objects_list_close (resource handle)
- Description: Close handle received from i5_ objects_list ().
- Return Values: Boolean success value
- Arguments: handle - Object list handle as returned by i5_ objects_list ()