diff --git a/functions/ifx.xml b/functions/ifx.xml index 99043efc43..d71adc20e7 100644 --- a/functions/ifx.xml +++ b/functions/ifx.xml @@ -6,135 +6,158 @@ The Informix driver for Informix (IDS) 7.x, SE 7.x, Universal Server (IUS) 9.x and IDS 2000 is implemented in "ifx.ec" and - "php3_ifx.h" in the informix extension directory. - IDS 7.x support is fairly complete, with full support for BYTE - and TEXT columns. IUS 9.x support is partly finished: the new - data types are there, but SLOB and CLOB support is still under construction. + "php3_ifx.h" in the informix extension directory. IDS 7.x support + is fairly complete, with full support for BYTE and TEXT + columns. IUS 9.x support is partly finished: the new data types + are there, but SLOB and CLOB support is still under construction. - Configuration notes - - You need a version of ESQL/C to compile the PHP Informix driver. - ESQL/C versions from 7.2x on should be OK. ESQL/C is now part of - the Informix Client SDK. - - Make sure that the "INFORMIXDIR" variable has been set, and that - $INFORMIXDIR/bin is in your PATH before you run the "configure" script. - - The configure script will autodetect the libraries and include - directories, if you run "configure --with_informix=yes". You can - overide this detection by specifying "IFX_LIBDIR", "IFX_LIBS" and - "IFX_INCDIR" in the environment. The configure script will also - try to detect your Informix server version. It will set the - "HAVE_IFX_IUS" conditional compilation variable if your Informix - version >= 9.00. - - - - Runtime considerations - - Make sure that the Informix environment variables INFORMIXDIR and - INFORMIXSERVER are available to the PHP ifx driver, and that the - INFORMIX bin directory is in the PATH. Check this by running a script - that contains a call to phpinfo() before you - start testing. The phpinfo() output should list - these environment variables. This is true for both CGI php and Apache - mod_php. You may have to set these environment variables in your - Apache startup script. - - - The Informix shared libraries should also be - available to the loader (check LD_LINBRARY_PATH or ld.so.conf/ldconfig). - - - - Some notes on the use of BLOBs (TEXT and BYTE columns) - - BLOBs are normally addressed by BLOB identifiers. - Select queries return a "blob id" for every BYTE and TEXT column. - You can get at the contents with "string_var = ifx_get_blob($blob_id);" if - you choose to get the BLOBs in memory (with : "ifx_blobinfile(0);"). - If you prefer to receive the content of BLOB columns in a file, use - "ifx_blobinfile(1);", and "ifx_get_blob($blob_id);" will get - you the filename. Use normal file I/O to get at the blob contents. - - For insert/update queries you must create these "blob id's" yourself - with "ifx_create_blob(..);". You then plug the blob id's into an array, - and replace the blob columns with a question mark (?) in the query string. - For updates/inserts, you are responsible for setting the blob contents with - ifx_update_blob(...). - - The behaviour of BLOB columns can be altered by configuration variables - that also can be set at runtime : - - - configuration variable : ifx.textasvarchar - - configuration variable : ifx.byteasvarchar - - - runtime functions : - - ifx_textasvarchar(0) : use blob id's for select queries with TEXT columns - - ifx_byteasvarchar(0) : use blob id's for select queries with BYTE columns - - ifx_textasvarchar(1) : return TEXT columns as if they were - VARCHAR columns, so that you don't need to use - blob id's for select queries. - - ifx_byteasvarchar(1) : return BYTE columns as if they were VARCHAR - columns, so that you don't need to use blob id's for - select queries. - - - configuration variable : ifx.blobinfile - - runtime function : - - ifx_blobinfile_mode(0) : return BYTE columns in memory, the blob id - lets you get at the contents. - - ifx_blobinfile_mode(1) : return BYTE columns in a file, the blob id - lets you get at the file name. - - If you set ifx_text/byteasvarchar to 1, you can use TEXT and BYTE columns - in select queries just like normal (but rather long) VARCHAR fields. - Since all strings are "counted" in PHP, this remains "binary safe". - It is up to you to handle this correctly. The returned data can contain - anything, you are responsible for the contents. - - If you set ifx_blobinfile to 1, use the file name returned by - ifx_get_blob(..) to get at the blob contents. - Note that in this case YOU ARE RESPONSIBLE FOR DELETING THE TEMPORARY - FILES CREATED BY INFORMIX when fetching the row. - Every new row fetched will create new temporary files for every - BYTE column. - - The location of the temporary files can be influenced by the environment - variable "blobdir", default is "." (the current directory). - Something like : putenv(blobdir=tmpblob"); will ease the cleaning up of - temp files accidentally left behind (their names all start with "blb"). - - - - Automatically trimming "char" (SQLCHAR and SQLNCHAR) data - - This can be set with the configuration variable - - ifx.charasvarchar : if set to 1 trailing spaces will be automatically - trimmed, to save you some "chopping". + Configuration notes + + You need a version of ESQL/C to compile the PHP Informix driver. + ESQL/C versions from 7.2x on should be OK. ESQL/C is now part of + the Informix Client SDK. + + + Make sure that the "INFORMIXDIR" variable has been set, and that + $INFORMIXDIR/bin is in your PATH before you run the "configure" + script. + + + The configure script will autodetect the libraries and include + directories, if you run "configure --with_informix=yes". You can + overide this detection by specifying "IFX_LIBDIR", "IFX_LIBS" and + "IFX_INCDIR" in the environment. The configure script will also + try to detect your Informix server version. It will set the + "HAVE_IFX_IUS" conditional compilation variable if your Informix + version >= 9.00. - - NULL values - - The configuration variable ifx.nullformat (and the runtime function - ifx_nullformat) when set to true will return NULL - columns as the string "NULL", when set to false they return the empty - string. This allows you to discriminate between NULL columns and - empty columns. + Runtime considerations + + Make sure that the Informix environment variables INFORMIXDIR and + INFORMIXSERVER are available to the PHP ifx driver, and that the + INFORMIX bin directory is in the PATH. Check this by running a + script that contains a call to phpinfo() + before you start testing. The phpinfo() + output should list these environment variables. This is true for + both CGI php and Apache mod_php. You may have to set these + environment variables in your Apache startup script. + + + The Informix shared libraries should also be available to the + loader (check LD_LINBRARY_PATH or ld.so.conf/ldconfig). + + + + + Some notes on the use of BLOBs (TEXT and BYTE columns) + + + BLOBs are normally addressed by BLOB identifiers. Select queries + return a "blob id" for every BYTE and TEXT column. You can get + at the contents with "string_var = ifx_get_blob($blob_id);" if + you choose to get the BLOBs in memory (with : + "ifx_blobinfile(0);"). If you prefer to receive the content of + BLOB columns in a file, use "ifx_blobinfile(1);", and + "ifx_get_blob($blob_id);" will get you the filename. Use normal + file I/O to get at the blob contents. + + + For insert/update queries you must create these "blob id's" + yourself with "ifx_create_blob;". You then + plug the blob id's into an array, and replace the blob columns + with a question mark (?) in the query string. For + updates/inserts, you are responsible for setting the blob + contents with ifx_update_blob. + + + The behaviour of BLOB columns can be altered by configuration + variables that also can be set at runtime : + + + configuration variable : ifx.textasvarchar + + + configuration variable : ifx.byteasvarchar + + + runtime functions : + + + ifx_textasvarchar(0) : use blob id's for select queries with TEXT + columns + + + ifx_byteasvarchar(0) : use blob id's for select queries with BYTE + columns + + + ifx_textasvarchar(1) : return TEXT columns as if they were + VARCHAR columns, so that you don't need to use blob id's for + select queries. + + + ifx_byteasvarchar(1) : return BYTE columns as if they were + VARCHAR columns, so that you don't need to use blob id's for + select queries. + + + configuration variable : ifx.blobinfile + + + runtime function : + + + ifx_blobinfile_mode(0) : return BYTE columns in memory, the blob + id lets you get at the contents. + + + ifx_blobinfile_mode(1) : return BYTE columns in a file, the blob + id lets you get at the file name. + + + If you set ifx_text/byteasvarchar to 1, you can use TEXT and BYTE + columns in select queries just like normal (but rather long) + VARCHAR fields. Since all strings are "counted" in PHP, this + remains "binary safe". It is up to you to handle this + correctly. The returned data can contain anything, you are + responsible for the contents. + + + If you set ifx_blobinfile to 1, use the file name returned by + ifx_get_blob(..) to get at the blob contents. Note that in this + case YOU ARE RESPONSIBLE FOR DELETING THE TEMPORARY FILES CREATED + BY INFORMIX when fetching the row. Every new row fetched will + create new temporary files for every BYTE column. + + + The location of the temporary files can be influenced by the + environment variable "blobdir", default is "." (the current + directory). Something like : putenv(blobdir=tmpblob"); will ease + the cleaning up of temp files accidentally left behind (their + names all start with "blb"). + + + + Automatically trimming "char" (SQLCHAR and SQLNCHAR) data + + This can be set with the configuration variable + + + ifx.charasvarchar : if set to 1 trailing spaces will be + automatically trimmed, to save you some "chopping". + + + + NULL values + + The configuration variable ifx.nullformat (and the runtime + function ifx_nullformat) when set to true + will return NULL columns as the string "NULL", when set to false + they return the empty string. This allows you to discriminate + between NULL columns and empty columns. @@ -158,32 +181,38 @@ Returns a connection identifier on success, or FALSE on error. - + + ifx_connect establishes a connection to an - Informix server. All of the arguments are optional, and if they're - missing, defaults are taken from values supplied in - configuration file + Informix server. All of the arguments are optional, and if + they're missing, defaults are taken from values supplied in configuration file (ifx.default_host for the host (Informix libraries will use - INFORMIXSERVER environment value if not defined), ifx.default_user - for user, ifx.default_password for the password (none if not defined). - + INFORMIXSERVER environment value if not defined), + ifx.default_user for user, ifx.default_password for the password + (none if not defined). + + In case a second call is made to ifx_connect with the same arguments, no new link will be established, but instead, the link identifier of the already opened link will be returned. - + + The link to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling ifx_close. - - See also ifx_pconnect, and - ifx_close. + + + See also ifx_pconnect, and + ifx_close. Connect to a Informix database $conn_id = ifx_pconnect ("mydb@ol_srv1", "imyself", "mypassword"); - + + @@ -196,36 +225,44 @@ $conn_id = ifx_pconnect ("mydb@ol_srv1", "imyself", "mypassword"); Description int ifx_pconnect - string database - - string userid - - string password - + string + database + + string + userid + + string + password + Returns: A positive Informix persistent link identifier on success, - or false on error + or false on error + ifx_pconnect acts very much like - ifx_connect with two major differences. + ifx_connect with two major differences. + This function behaves exactly like ifx_connect when PHP is not running as an Apache module. First, when connecting, the function would first try to find a (persistent) link that's already open with the same host, username and password. If one is found, an identifier for it - will be returned instead of opening a new connection. + will be returned instead of opening a new connection. + Second, the connection to the SQL server will not be closed when the execution of the script ends. Instead, the link will remain open for future use (ifx_close will not - close links established by ifx_pconnect). + close links established by ifx_pconnect). + - This type of links is therefore called 'persistent'. + This type of links is therefore called 'persistent'. + - See also: - ifx_connect. + See also: ifx_connect. + @@ -238,26 +275,31 @@ $conn_id = ifx_pconnect ("mydb@ol_srv1", "imyself", "mypassword"); Description int ifx_close - int link_identifier - + int + link_identifier + - Returns: always true. + Returns: always true. + ifx_close closes the link to an Informix database that's associated with the specified link identifier. If the link identifier isn't specified, the last opened link is - assumed. + assumed. + Note that this isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's - execution. + execution. + ifx_close will not close persistent links - generated by ifx_pconnect. + generated by ifx_pconnect. + See also: ifx_connect, and - ifx_pconnect. + ifx_pconnect. Closing a Informix connection @@ -265,7 +307,8 @@ $conn_id = ifx_connect ("mydb@ol_srv", "itsme", "mypassword"); ... some queries and stuff ... ifx_close($conn_id); - + + @@ -279,46 +322,58 @@ ifx_close($conn_id); int ifx_query string query - int link_identifier - - int cursor_type - - mixed blobidarray - + int + link_identifier + + int + cursor_type + + mixed + + blobidarray + + Returns: A positive Informix result identifier on success, or false on error. - + + A "result_id" resource used by other functions to retrieve the query results. Sets "affected_rows" for retrieval by the ifx_affected_rows function. - + + ifx_query sends a query to the currently active database on the server that's associated with the specified link identifier. If the link identifier isn't specified, the last opened link is assumed. If no link is open, the function tries to establish a link as if ifx_connect was called, and use it. - + + Executes query on connection - conn_id. For "select-type" queries a cursor - is declared and opened. The optional cursor_type - parameter allows you to make this a "scroll" and/or "hold" - cursor. It's a bitmask and can be either IFX_SCROLL, IFX_HOLD, or both - or'ed together. Non-select queries are "execute immediate". - IFX_SCROLL and IFX_HOLD are symbolic constants and as such shouldn't - be between quotes. I you omit this parameter the cursor is a normal - sequential cursor. - + conn_id. For "select-type" queries a + cursor is declared and opened. The optional + cursor_type parameter allows you to make + this a "scroll" and/or "hold" cursor. It's a bitmask and can be + either IFX_SCROLL, IFX_HOLD, or both or'ed together. Non-select + queries are "execute immediate". IFX_SCROLL and IFX_HOLD are + symbolic constants and as such shouldn't be between quotes. I you + omit this parameter the cursor is a normal sequential cursor. + + For either query type the number of (estimated or real) affected - rows is saved for retrieval by ifx_affected_rows. - + rows is saved for retrieval by + ifx_affected_rows. + + If you have BLOB (BYTE or TEXT) columns in an update query, you can add a blobidarray parameter containing the corresponding "blob ids", and you should replace those columns with a "?" in the query text. - + + If the contents of the TEXT (or BYTE) column allow it, you can also use "ifx_textasvarchar(1)" and "ifx_byteasvarchar(1)". This allows you to treat TEXT (or BYTE) columns just as if they were @@ -329,11 +384,13 @@ ifx_close($conn_id); situation), select queries will return BLOB columns as blob id's (integer value). You can get the value of the blob as a string or file with the blob functions (see below). - - See also: - ifx_connect. + + + See also: ifx_connect. - Show all rows of the "orders" table as a html table + + Show all rows of the "orders" table as a html table + ifx_textasvarchar(1); // use "text mode" for blobs $res_id = ifx_query("select * from orders", $conn_id); @@ -365,7 +422,8 @@ if (! $res_id) { // free result id ifx_free_result($res_id); - + + @@ -380,7 +438,9 @@ ifx_free_result($res_id); int ifx_prepare string query int conn_id - int cursor_def + int + cursor_def + mixed blobidarray @@ -388,41 +448,50 @@ ifx_free_result($res_id); ifx_do. Sets affected_rows for retrieval by the ifx_affected_rows function. - + + Prepares query on connection conn_id. For "select-type" queries a - cursor is declared and opened. The optional cursor_type - parameter allows you to make this a "scroll" and/or "hold" - cursor. It's a bitmask and can be either IFX_SCROLL, IFX_HOLD, or both - or'ed together. - + cursor is declared and opened. The optional + cursor_type parameter allows you to make + this a "scroll" and/or "hold" cursor. It's a bitmask and can be + either IFX_SCROLL, IFX_HOLD, or both or'ed together. + + For either query type the estimated number of affected rows is saved for retrieval by ifx_affected_rows. - + + If you have BLOB (BYTE or TEXT) columns in the query, you can add a blobidarray parameter containing the corresponding "blob ids", and you should replace those columns with a "?" in the query text. - + + If the contents of the TEXT (or BYTE) column allow it, you can also use "ifx_textasvarchar(1)" and "ifx_byteasvarchar(1)". This allows you to treat TEXT (or BYTE) columns just as if they were ordinary (but long) VARCHAR columns for select queries, and you don't need to bother with blob id's. - + + With ifx_textasvarchar(0) or ifx_byteasvarchar(0) (the default situation), select queries will return BLOB columns as blob id's (integer value). You can get the value of the blob as a string or file with the blob functions (see below). - - See also: ifx_do. + + + See also: ifx_do. + - + ifx_do - Execute a previously prepared SQL-statement + + Execute a previously prepared SQL-statement + Description @@ -432,16 +501,21 @@ ifx_free_result($res_id); Returns TRUE on success, FALSE on error. - + + Executes a previously prepared query or opens a cursor for it. - + + Does NOT free result_id on error. - + + Also sets the real number of ifx_affected_rows for non-select statements for retrieval by ifx_affected_rows - - See also: ifx_prepare. There is a example. + + + See also: ifx_prepare. There is a example. + @@ -459,21 +533,34 @@ ifx_free_result($res_id); The Informix error codes (SQLSTATE & SQLCODE) formatted as follows : - + + x [SQLSTATE = aa bbb SQLCODE=cccc] - + + where x = space : no error - E : error - N : no more data - W : warning - ? : undefined - + + + E : error + + + N : no more data + + + W : warning + + + ? : undefined + + If the "x" character is anything other than space, SQLSTATE and SQLCODE describe the error in more detail. - + + See the Informix manual for the description of SQLSTATE and SQLCODE - + + Returns in a string one character describing the general results of a statement and both SQLSTATE and SQLCODE associated with the most recent SQL statement executed. The format of the string is @@ -483,8 +570,9 @@ ifx_free_result($res_id); some warning), 'E' (an error happened when executing the statement) or 'N' (the statement didn't return any data). - See also: - ifx_errormsg + + + See also: ifx_errormsg @@ -498,21 +586,24 @@ ifx_free_result($res_id); Description string ifx_errormsg - int errorcode + int + errorcode + Returns the Informix error message associated with the most recent Informix error, or, when the optional "errorcode" param is present, the error message corresponding to "errorcode". - + + See also: ifx_error - - + + printf("%s\n<br>", ifx_errormsg(-201)); - - + + @@ -531,26 +622,32 @@ printf("%s\n<br>", ifx_errormsg(-201)); result_id is a valid result id returned by ifx_query or ifx_prepare. - + + Returns the number of rows affected by a query associated with result_id. - + + For inserts, updates and deletes the number is the real number (sqlerrd[2]) of affected rows. For selects it is an estimate (sqlerrd[0]). Don't rely on it. The database server can never - return the actual number of rows that will be returned by a SELECT - because it has not even begun fetching them at this stage (just after - the "PREPARE" when the optimizer has determined the query plan). - + return the actual number of rows that will be returned by a + SELECT because it has not even begun fetching them at this stage + (just after the "PREPARE" when the optimizer has determined the + query plan). + + Useful after ifx_prepare to limit queries to reasonable result sets. - + + See also: ifx_num_rows Informix affected rows -$rid = ifx_prepare ("select * from emp where name like " . $name, $connid); +$rid = ifx_prepare ("select * from emp + where name like " . $name, $connid); if (! $rid) { ... error ... } @@ -559,15 +656,17 @@ if ($rowcount > 1000) { printf ("Too many rows in result set (%d)\n<br>", $rowcount); die ("Please restrict your query<br>\n"); } - - + + ifx_getsqlca - Get the contents of sqlca.sqlerrd[0..5] after a query + + Get the contents of sqlca.sqlerrd[0..5] after a query + Description @@ -579,31 +678,37 @@ if ($rowcount > 1000) { result_id is a valid result id returned by ifx_query or ifx_prepare. - - Returns a pseudo-row (assiociative array) with sqlca.sqlerrd[0] ... sqlca.sqlerrd[5] - after the query associated with result_id. - - For inserts, updates and deletes the values returned are those as set by the server - after executing the query. This gives access to the number of affected - rows and the serial insert value. For SELECTs the values are those saved after - the PREPARE statement. This gives access to the *estimated* number of - affected rows. The use of this function saves the overhead of executing - a "select dbinfo('sqlca.sqlerrdx')" query, as it retrieves the values - that were saved by the ifx driver at the appropriate moment. - - Retrieve Informix sqlca.sqlerrd[x] values - + + Returns a pseudo-row (assiociative array) with sqlca.sqlerrd[0] + ... sqlca.sqlerrd[5] after the query associated with + result_id. + + + For inserts, updates and deletes the values returned are those as + set by the server after executing the query. This gives access to + the number of affected rows and the serial insert value. For + SELECTs the values are those saved after the PREPARE + statement. This gives access to the *estimated* number of + affected rows. The use of this function saves the overhead of + executing a "select dbinfo('sqlca.sqlerrdx')" query, as it + retrieves the values that were saved by the ifx driver at the + appropriate moment. + + + Retrieve Informix sqlca.sqlerrd[x] values + /* assume the first column of 'sometable' is a serial */ -$qid = ifx_query("insert into sometable values(0, '2nd column', 'another column' ", $connid); +$qid = ifx_query("insert into sometable + values (0, '2nd column', 'another column' ", $connid); if (! $qid) { ... error ... } $sqlca = ifx_getsqlca ($qid); $serial_value = $sqlca["sqlerrd1"]; echo "The serial value of the inserted row is : " . $serial_value<br>\n"; - - + + @@ -617,33 +722,39 @@ echo "The serial value of the inserted row is : " . $serial_value<br>\n"; array ifx_fetch_row int result_id - mixed position - + mixed + position + Returns an associative array that corresponds to the fetched row, or false if there are no more rows. - + + Blob columns are returned as integer blob id values for use in ifx_get_blob unless you have used ifx_textasvarchar(1) or ifx_byteasvarchar(1), in which case blobs are returned as string values. Returns FALSE on error - + + result_id is a valid resultid returned by ifx_query or ifx_prepare (select type queries only!). - + + position is an optional parameter for a "fetch" operation on "scroll" cursors: "NEXT", "PREVIOUS", "CURRENT", "FIRST", "LAST" or a number. If you specify a number, an "absolute" row fetch is executed. This parameter is optional, and only valid for SCROLL cursors. - + + ifx_fetch_row fetches one row of data from the result associated with the specified result identifier. The row is returned as an array. Each result column is stored in an array offset, starting at offset 0, with the column name as key. - + + Subsequent calls to ifx_fetch_row would return the next row in the result set, or false if there are no more rows. @@ -682,25 +793,30 @@ ifx_free_result ($rid); ifx_htmltbl_result - Formats all rows of a query into a HTML table + + Formats all rows of a query into a HTML table + Description int ifx_htmltbl_result int result_id - string html_table_options + string + html_table_options + Returns the number of rows fetched or FALSE on error. - + + Formats all rows of the result_id query into a html table. The optional second argument is a string of <table> tag options - - Informix results as HTML table - + + Informix results as HTML table + $rid = ifx_prepare ("select * from emp where name like " . $name, $connid, IFX_SCROLL); if (! $rid) { @@ -718,8 +834,8 @@ if (! ifx_do($rid) { ifx_htmltbl_result ($rid, "border=\"2\""); ifx_free_result($rid); - - + + @@ -771,7 +887,8 @@ for ($i = 0; $i < count($types); $i++) { Returns an associative array with fieldnames as key and the SQL fieldproperties as data for a query with result_id. Returns FALSE on error. - + + Returns the Informix SQL fieldproperies of every field in the query as an associative array. Properties are encoded as: "SQLTYPE;length;precision;scale;ISNULLABLE" where SQLTYPE = the @@ -808,14 +925,15 @@ for ($i = 0; $i < count($properties); $i++) { Returns the number of columns in query for result_id or FALSE on error - + + After preparing or executing a query, this call gives you the number of columns in the query. - + ifx_num_rows Count the rows already fetched a query @@ -943,15 +1061,19 @@ for ($i = 0; $i < count($properties); $i++) { Creates an blob object. - + + type: 1 = TEXT, 0 = BYTE - + + mode: 0 = blob-object holds the content in memory, 1 = blob-object holds the content in file. - + + param: if mode = 0: pointer to the content, if mode = 1: pointer to the filestring. - + + Return FALSE on error, otherwise the new blob object-id. @@ -971,7 +1093,8 @@ for ($i = 0; $i < count($properties); $i++) { Duplicates the given blob object. bid is the ID of the blob object. - + + Returns FALSE on error otherwise the new blob object-id. @@ -1094,7 +1217,9 @@ for ($i = 0; $i < count($properties); $i++) { ifx_nullformat - Sets the default return value on a fetch row + + Sets the default return value on a fetch row + Description @@ -1271,7 +1396,6 @@ for ($i = 0; $i < count($properties); $i++) { -