From 9cbb34ac2a785c32ef7bdeda788959ad7b0afc5b Mon Sep 17 00:00:00 2001 From: Mehdi Achour Date: Sat, 3 Feb 2007 22:17:50 +0000 Subject: [PATCH] Ws, prepare for new doc style git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@228914 c90b9560-bf6c-de11-be94-00142212c4b1 --- .../sesam/functions/sesam-affected-rows.xml | 86 ++-- reference/sesam/functions/sesam-commit.xml | 80 ++-- reference/sesam/functions/sesam-connect.xml | 110 ++--- .../sesam/functions/sesam-diagnostic.xml | 168 ++++---- .../sesam/functions/sesam-disconnect.xml | 94 ++--- reference/sesam/functions/sesam-errormsg.xml | 58 +-- reference/sesam/functions/sesam-execimm.xml | 102 ++--- .../sesam/functions/sesam-fetch-array.xml | 178 ++++---- .../sesam/functions/sesam-fetch-result.xml | 182 ++++----- reference/sesam/functions/sesam-fetch-row.xml | 298 +++++++------- .../sesam/functions/sesam-field-array.xml | 380 +++++++++--------- .../sesam/functions/sesam-field-name.xml | 68 ++-- .../sesam/functions/sesam-free-result.xml | 38 +- .../sesam/functions/sesam-num-fields.xml | 66 ++- reference/sesam/functions/sesam-query.xml | 124 +++--- reference/sesam/functions/sesam-rollback.xml | 76 ++-- reference/sesam/functions/sesam-seek-row.xml | 194 +++++---- .../sesam/functions/sesam-settransaction.xml | 226 +++++------ 18 files changed, 1256 insertions(+), 1272 deletions(-) diff --git a/reference/sesam/functions/sesam-affected-rows.xml b/reference/sesam/functions/sesam-affected-rows.xml index 29b6809aa9..915ba751f4 100644 --- a/reference/sesam/functions/sesam-affected-rows.xml +++ b/reference/sesam/functions/sesam-affected-rows.xml @@ -1,40 +1,38 @@ - + - - - sesam_affected_rows - - Get number of rows affected by an immediate query - - - - Description - - intsesam_affected_rows - stringresult_id - - - result_id is a valid result id returned by - sesam_query. - - - Returns the number of rows affected by a query associated with - result_id. - - - The sesam_affected_rows function can only - return useful values when used in combination with "immediate" - SQL statements (updating operations like - INSERT, UPDATE and - DELETE) because SESAM does not deliver any - "affected rows" information for "select type" queries. The - number returned is the number of affected rows. - - - - <function>sesam_affected_rows</function> example - + + + sesam_affected_rows + Get number of rows affected by an immediate query + + + Description + + intsesam_affected_rows + stringresult_id + + + result_id is a valid result id returned by + sesam_query. + + + Returns the number of rows affected by a query associated with + result_id. + + + The sesam_affected_rows function can only + return useful values when used in combination with "immediate" + SQL statements (updating operations like + INSERT, UPDATE and + DELETE) because SESAM does not deliver any + "affected rows" information for "select type" queries. The + number returned is the number of affected rows. + + + + <function>sesam_affected_rows</function> example + ]]> - - - - - See also sesam_query and - sesam_execimm. - - - + + + + + See also sesam_query and + sesam_execimm. + + + + - - - sesam_commit - - Commit pending updates to the SESAM database - - - - Description - - boolsesam_commit - - - - Returns: &true; on success, - &false; on errors - - - sesam_commit commits any pending updates to - the database. - - - Note that there is no "auto-commit" feature as in other - databases, as it could lead to accidental data loss. Uncommitted - data at the end of the current script (or when calling - sesam_disconnect) will be discarded by an - implied sesam_rollback call. - - - - - See also: sesam_rollback. - - Committing an update to the SESAM database - + + + sesam_commit + Commit pending updates to the SESAM database + + + Description + + boolsesam_commit + + + + Returns: &true; on success, + &false; on errors + + + sesam_commit commits any pending updates to + the database. + + + Note that there is no "auto-commit" feature as in other + databases, as it could lead to accidental data loss. Uncommitted + data at the end of the current script (or when calling + sesam_disconnect) will be discarded by an + implied sesam_rollback call. + + + + + See also: sesam_rollback. + + Committing an update to the SESAM database + ]]> - - - - - + + + + + + - - - sesam_connect - Open SESAM database connection - - - Description - - boolsesam_connect - stringcatalog - stringschema - stringuser - - - Returns &true; if a connection to the SESAM - database was made, or &false; on error. - - - sesam_connect establishes a connection to an - SESAM database handler task. The connection is always - "persistent" in the sense that only the very first invocation - will actually load the driver from the configured SESAM OML PLAM - library. Subsequent calls will reuse the driver and will - immediately use the given catalog, schema, and user. - - - When creating a database, the "catalog" - name is specified in the SESAM configuration directive - //ADD-SQL-DATABASE-CATALOG-LIST ENTRY-1 = - *CATALOG(CATALOG-NAME = catalogname,...) - - - The "schema" references the desired - database schema (see SESAM handbook). - - - The "user" argument references one of the - users which are allowed to access this - "catalog" / - "schema" combination. Note that - "user" is completely independent from both - the system's user id's and from HTTP user/password protection. It - appears in the SESAM configuration only. - - - See also sesam_disconnect. - - Connect to a SESAM database - + + + sesam_connect + Open SESAM database connection + + + Description + + boolsesam_connect + stringcatalog + stringschema + stringuser + + + Returns &true; if a connection to the SESAM + database was made, or &false; on error. + + + sesam_connect establishes a connection to an + SESAM database handler task. The connection is always + "persistent" in the sense that only the very first invocation + will actually load the driver from the configured SESAM OML PLAM + library. Subsequent calls will reuse the driver and will + immediately use the given catalog, schema, and user. + + + When creating a database, the "catalog" + name is specified in the SESAM configuration directive + //ADD-SQL-DATABASE-CATALOG-LIST ENTRY-1 = + *CATALOG(CATALOG-NAME = catalogname,...) + + + The "schema" references the desired + database schema (see SESAM handbook). + + + The "user" argument references one of the + users which are allowed to access this + "catalog" / + "schema" combination. Note that + "user" is completely independent from both + the system's user id's and from HTTP user/password protection. It + appears in the SESAM configuration only. + + + See also sesam_disconnect. + + Connect to a SESAM database + ]]> - - - - - + + + + + + - - - sesam_diagnostic - - Return status information for last SESAM call - - - - Description - - arraysesam_diagnostic - - - - Returns an associative array of status and return codes for the - last SQL query/statement/command. Elements of the array are: - - - Status information returned by <function>sesam_diagnostic</function> - - - - - Element - Contents - - - - - $array["sqlstate"] - - 5 digit SQL return code (see the SESAM manual for the - description of the possible values of SQLSTATE) - - - - $array["rowcount"] - - number of affected rows in last update/insert/delete (set - after "immediate" statements only) - - - - $array["errmsg"] - - "human readable" error message string (set after errors - only) - - - - $array["errcol"] - - error column number of previous error (0-based; or -1 if - undefined. Set after errors only) - - - - $array["errlin"] - - error line number of previous error (0-based; or -1 if - undefined. Set after errors only) - - - - -
- - - In the following example, a syntax error (E SEW42AE ILLEGAL - CHARACTER) is displayed by including the offending SQL statement - and pointing to the error location: - - Displaying SESAM error messages with error position - + + + sesam_diagnostic + Return status information for last SESAM call + + + Description + + arraysesam_diagnostic + + + + Returns an associative array of status and return codes for the + last SQL query/statement/command. Elements of the array are: + + + Status information returned by <function>sesam_diagnostic</function> + + + + + Element + Contents + + + + + $array["sqlstate"] + + 5 digit SQL return code (see the SESAM manual for the + description of the possible values of SQLSTATE) + + + + $array["rowcount"] + + number of affected rows in last update/insert/delete (set + after "immediate" statements only) + + + + $array["errmsg"] + + "human readable" error message string (set after errors + only) + + + + $array["errcol"] + + error column number of previous error (0-based; or -1 if + undefined. Set after errors only) + + + + $array["errlin"] + + error line number of previous error (0-based; or -1 if + undefined. Set after errors only) + + + + +
+ + + In the following example, a syntax error (E SEW42AE ILLEGAL + CHARACTER) is displayed by including the offending SQL statement + and pointing to the error location: + + Displaying SESAM error messages with error position + ]]> - - - - - See also: sesam_errormsg for simple access - to the error string only - - - + + + + + See also: sesam_errormsg for simple access + to the error string only + + + + - - - sesam_disconnect - Detach from SESAM connection - - - Description - - boolsesam_disconnect - - - - Returns: always &true;. - - - sesam_disconnect closes the logical link to - a SESAM database (without actually disconnecting and unloading - the driver). - - - Note that this isn't usually necessary, as the open connection is - automatically closed at the end of the script's execution. - Uncommitted data will be discarded, because an implicit - sesam_rollback is executed. - - - sesam_disconnect will not close the - persistent link, it will only invalidate the currently defined - "catalog", "schema" - and "user" triple, so that any sesam - function called after sesam_disconnect will - fail. - - - - Closing a SESAM connection - + + + sesam_disconnect + Detach from SESAM connection + + + Description + + boolsesam_disconnect + + + + Returns: always &true;. + + + sesam_disconnect closes the logical link to + a SESAM database (without actually disconnecting and unloading + the driver). + + + Note that this isn't usually necessary, as the open connection is + automatically closed at the end of the script's execution. + Uncommitted data will be discarded, because an implicit + sesam_rollback is executed. + + + sesam_disconnect will not close the + persistent link, it will only invalidate the currently defined + "catalog", "schema" + and "user" triple, so that any sesam + function called after sesam_disconnect will + fail. + + + + Closing a SESAM connection + ]]> - - - - - See also sesam_connect. - - - + + + + + See also sesam_connect. + + + + - - - sesam_errormsg - Returns error message of last SESAM call - - - Description - - stringsesam_errormsg - - - - Returns the SESAM error message associated with the most recent - SESAM error. - - - - <function>sesam_errormsg</function> example - + + + sesam_errormsg + Returns error message of last SESAM call + + + Description + + stringsesam_errormsg + + + + Returns the SESAM error message associated with the most recent + SESAM error. + + + + <function>sesam_errormsg</function> example + ]]> - - - - - See also sesam_diagnostic for the full set - of SESAM SQL status information. - - - + + + + + See also sesam_diagnostic for the full set + of SESAM SQL status information. + + + + - - - sesam_execimm - Execute an "immediate" SQL-statement - - - Description - - stringsesam_execimm - stringquery - - - Returns: A SESAM "result identifier" on success, or - &false; on error. - - - sesam_execimm executes an "immediate" - statement (i.e., a statement like UPDATE, INSERT or DELETE which - returns no result, and has no INPUT or OUTPUT variables). - "select type" queries can not be used with - sesam_execimm. Sets the - affected_rows value for retrieval by the - sesam_affected_rows function. - - - Note that sesam_query can handle both - "immediate" and "select-type" queries. Use - sesam_execimm only if you know beforehand - what type of statement will be executed. An attempt to use - SELECT type queries with sesam_execimm will - return $err["sqlstate"] == "42SBW". - - - The returned "result identifier" can not be used for retrieving - anything but the sesam_affected_rows; it is - only returned for symmetry with the - sesam_query function. - - - - + + + sesam_execimm + Execute an "immediate" SQL-statement + + + Description + + stringsesam_execimm + stringquery + + + Returns: A SESAM "result identifier" on success, or + &false; on error. + + + sesam_execimm executes an "immediate" + statement (i.e., a statement like UPDATE, INSERT or DELETE which + returns no result, and has no INPUT or OUTPUT variables). + "select type" queries can not be used with + sesam_execimm. Sets the + affected_rows value for retrieval by the + sesam_affected_rows function. + + + Note that sesam_query can handle both + "immediate" and "select-type" queries. Use + sesam_execimm only if you know beforehand + what type of statement will be executed. An attempt to use + SELECT type queries with sesam_execimm will + return $err["sqlstate"] == "42SBW". + + + The returned "result identifier" can not be used for retrieving + anything but the sesam_affected_rows; it is + only returned for symmetry with the + sesam_query function. + + + + ]]> - - - - - See also sesam_query and - sesam_affected_rows. - - - + + + + + See also sesam_query and + sesam_affected_rows. + + + + - - - sesam_fetch_array - Fetch one row as an associative array - - - Description - - arraysesam_fetch_array - stringresult_id - intwhence - intoffset - - - Returns an array that corresponds to the fetched row, or - &false; if there are no more rows. - - - sesam_fetch_array is an alternative version - of sesam_fetch_row. Instead of storing the - data in the numeric indices of the result array, it stores the - data in associative indices, using the field names as keys. - - - result_id is a valid result id returned by - sesam_query (select type queries only!). - - - For the valid values of the optional - whenceand - offset parameters, - see the sesam_fetch_row function for - details. - - - sesam_fetch_array fetches one row of data - from the result associated with the specified result identifier. - The row is returned as an associative array. Each result column - is stored with an associative index equal to its column - (aka. field) name. The column names are converted to lower case. - - - Columns without a field name (e.g., results of arithmetic - operations) and empty fields are not stored in the array. Also, - if two or more columns of the result have the same column names, - the later column will take precedence. In this situation, either - call sesam_fetch_row or make an alias for - the column. - - + + + sesam_fetch_array + Fetch one row as an associative array + + + Description + + arraysesam_fetch_array + stringresult_id + intwhence + intoffset + + + Returns an array that corresponds to the fetched row, or + &false; if there are no more rows. + + + sesam_fetch_array is an alternative version + of sesam_fetch_row. Instead of storing the + data in the numeric indices of the result array, it stores the + data in associative indices, using the field names as keys. + + + result_id is a valid result id returned by + sesam_query (select type queries only!). + + + For the valid values of the optional + whenceand + offset parameters, + see the sesam_fetch_row function for + details. + + + sesam_fetch_array fetches one row of data + from the result associated with the specified result identifier. + The row is returned as an associative array. Each result column + is stored with an associative index equal to its column + (aka. field) name. The column names are converted to lower case. + + + Columns without a field name (e.g., results of arithmetic + operations) and empty fields are not stored in the array. Also, + if two or more columns of the result have the same column names, + the later column will take precedence. In this situation, either + call sesam_fetch_row or make an alias for + the column. + + - - - - - A special handling allows fetching "multiple field" columns - (which would otherwise all have the same column names). For each - column of a "multiple field", the index name is constructed by - appending the string "(n)" where n is the sub-index of the - multiple field column, ranging from 1 to its declared repetition - factor. The indices are NOT zero based, in order to match the - nomenclature used in the respective query syntax. For a column - declared as: - - + + + + + A special handling allows fetching "multiple field" columns + (which would otherwise all have the same column names). For each + column of a "multiple field", the index name is constructed by + appending the string "(n)" where n is the sub-index of the + multiple field column, ranging from 1 to its declared repetition + factor. The indices are NOT zero based, in order to match the + nomenclature used in the respective query syntax. For a column + declared as: + + - - - the associative indices used for the individual "multiple field" - columns would be "multi(1)", - "multi(2)", and "multi(3)" - respectively. - - - Subsequent calls to sesam_fetch_array would - return the next (or prior, or n'th next/prior, depending on the - scroll attributes) row in the result set, or - &false; if there are no more rows. - - - SESAM fetch array - + + + the associative indices used for the individual "multiple field" + columns would be "multi(1)", + "multi(2)", and "multi(3)" + respectively. + + + Subsequent calls to sesam_fetch_array would + return the next (or prior, or n'th next/prior, depending on the + scroll attributes) row in the result set, or + &false; if there are no more rows. + + + SESAM fetch array + \n"; sesam_free_result($result); ?> ]]> - - - - See also: sesam_fetch_row which returns an - indexed array. - - - + + + + See also: sesam_fetch_row which returns an + indexed array. + + + + - - - sesam_fetch_result - Return all or part of a query result - - - Description - - mixedsesam_fetch_result - stringresult_id - intmax_rows - - - Returns a mixed array with the query result entries, optionally - limited to a maximum of max_rows rows. - Note that both row and column indexes are zero-based. - - - Mixed result set returned by <function>sesam_fetch_result</function> - - - - - Array Element - Contents - - - - - int $arr["count"] - - number of columns in result set (or zero if this was an - "immediate" query) - - - - int $arr["rows"] - - number of rows in result set (between zero and - max_rows) - - - - bool $arr["truncated"] - - &true; if the number of rows was at least - max_rows, &false; - otherwise. Note that even when this is - &true;, the next - sesam_fetch_result call may return zero - rows because there are no more result entries. - - - - mixed $arr[col][row] - - result data for all the fields at - row(row) and - column(col), (where the integer index - row is between 0 and - $arr["rows"]-1, and - col is between 0 and - $arr["count"]-1). Fields may be empty, so - you must check for the existence of a field by using the php - isset function. The type of the - returned fields depend on the respective SQL type declared - for its column (see SESAM - overview for the conversions applied). SESAM - "multiple fields" are "inlined" and treated like a sequence - of columns. - - - - -
- Note that the amount of memory used up by a large query may be - gigantic. Use the max_rows parameter to - limit the maximum number of rows returned, unless you are - absolutely sure that your result will not use up all available - memory. - - - See also: sesam_fetch_row, and - sesam_field_array to check for "multiple - fields". See the description of the - sesam_query function for a complete example - using sesam_fetch_result. - - - + + + sesam_fetch_result + Return all or part of a query result + + + Description + + mixedsesam_fetch_result + stringresult_id + intmax_rows + + + Returns a mixed array with the query result entries, optionally + limited to a maximum of max_rows rows. + Note that both row and column indexes are zero-based. + + + Mixed result set returned by <function>sesam_fetch_result</function> + + + + + Array Element + Contents + + + + + int $arr["count"] + + number of columns in result set (or zero if this was an + "immediate" query) + + + + int $arr["rows"] + + number of rows in result set (between zero and + max_rows) + + + + bool $arr["truncated"] + + &true; if the number of rows was at least + max_rows, &false; + otherwise. Note that even when this is + &true;, the next + sesam_fetch_result call may return zero + rows because there are no more result entries. + + + + mixed $arr[col][row] + + result data for all the fields at + row(row) and + column(col), (where the integer index + row is between 0 and + $arr["rows"]-1, and + col is between 0 and + $arr["count"]-1). Fields may be empty, so + you must check for the existence of a field by using the php + isset function. The type of the + returned fields depend on the respective SQL type declared + for its column (see SESAM + overview for the conversions applied). SESAM + "multiple fields" are "inlined" and treated like a sequence + of columns. + + + + +
+ Note that the amount of memory used up by a large query may be + gigantic. Use the max_rows parameter to + limit the maximum number of rows returned, unless you are + absolutely sure that your result will not use up all available + memory. + + + See also: sesam_fetch_row, and + sesam_field_array to check for "multiple + fields". See the description of the + sesam_query function for a complete example + using sesam_fetch_result. + + + + - - - sesam_fetch_row - Fetch one row as an array - - - Description - - arraysesam_fetch_row - stringresult_id - intwhence - intoffset - - - Returns an array that corresponds to the fetched row, or - &false; if there are no more rows. - - - The number of columns in the result set is returned in an - associative array element $array["count"]. Because some of the - result columns may be empty, the count - function can not be used on the result row returned by - sesam_fetch_row. - - - result_id is a valid result id returned by - sesam_query (select type queries only!). - - - whence is an optional - parameter for a fetch operation on "scrollable" cursors, which - can be set to the following predefined constants: - - Valid values for <parameter>"whence"</parameter> parameter - - - - Value - Constant - Meaning - - - - - 0 - SESAM_SEEK_NEXT - - read sequentially (after fetch, the internal default is set - to SESAM_SEEK_NEXT) - - - - 1 - SESAM_SEEK_PRIOR - - read sequentially backwards (after fetch, the internal - default is set to SESAM_SEEK_PRIOR) - - - - 2 - SESAM_SEEK_FIRST - - rewind to first row (after fetch, the default is set to - SESAM_SEEK_NEXT) - - - - 3 - SESAM_SEEK_LAST - - seek to last row (after fetch, the default is set to - SESAM_SEEK_PRIOR) - - - - 4 - SESAM_SEEK_ABSOLUTE - - seek to absolute row number given as - offset (Zero-based. After fetch, the - internal default is set to - SESAM_SEEK_ABSOLUTE, and the internal - offset value is auto-incremented) - - - - 5 - SESAM_SEEK_RELATIVE - - seek relative to current scroll position, where - offset can be a positive or negative - offset value. - - - - -
- This parameter is only valid for "scrollable" cursors. - - - When using "scrollable" cursors, the cursor can be freely - positioned on the result set. If the - whence parameter is - omitted, the global default values for the scrolling type - (initialized to: SESAM_SEEK_NEXT, and settable - by sesam_seek_row) are used. If - whence is supplied, - its value replaces the global default. - - - offset is an optional - parameter which is only evaluated (and required) if - whence is either - SESAM_SEEK_RELATIVE or - SESAM_SEEK_ABSOLUTE. This parameter is only - valid for "scrollable" cursors. - - - sesam_fetch_row fetches one row of data from - the result associated with the specified result identifier. The - row is returned as an array (indexed by values between - 0 and $array["count"]-1). - Fields may be empty, so you must check for the existence of a - field by using the isset function. The - type of the returned fields depend on the respective SQL type - declared for its column (see SESAM - overview for the conversions applied). SESAM "multiple - fields" are "inlined" and treated like a sequence of columns. - - - Subsequent calls to sesam_fetch_row would - return the next (or prior, or n'th next/prior, depending on the - scroll attributes) row in the result set, or - &false; if there are no more rows. - - - SESAM fetch rows - + + + sesam_fetch_row + Fetch one row as an array + + + Description + + arraysesam_fetch_row + stringresult_id + intwhence + intoffset + + + Returns an array that corresponds to the fetched row, or + &false; if there are no more rows. + + + The number of columns in the result set is returned in an + associative array element $array["count"]. Because some of the + result columns may be empty, the count + function can not be used on the result row returned by + sesam_fetch_row. + + + result_id is a valid result id returned by + sesam_query (select type queries only!). + + + whence is an optional + parameter for a fetch operation on "scrollable" cursors, which + can be set to the following predefined constants: + + Valid values for <parameter>"whence"</parameter> parameter + + + + Value + Constant + Meaning + + + + + 0 + SESAM_SEEK_NEXT + + read sequentially (after fetch, the internal default is set + to SESAM_SEEK_NEXT) + + + + 1 + SESAM_SEEK_PRIOR + + read sequentially backwards (after fetch, the internal + default is set to SESAM_SEEK_PRIOR) + + + + 2 + SESAM_SEEK_FIRST + + rewind to first row (after fetch, the default is set to + SESAM_SEEK_NEXT) + + + + 3 + SESAM_SEEK_LAST + + seek to last row (after fetch, the default is set to + SESAM_SEEK_PRIOR) + + + + 4 + SESAM_SEEK_ABSOLUTE + + seek to absolute row number given as + offset (Zero-based. After fetch, the + internal default is set to + SESAM_SEEK_ABSOLUTE, and the internal + offset value is auto-incremented) + + + + 5 + SESAM_SEEK_RELATIVE + + seek relative to current scroll position, where + offset can be a positive or negative + offset value. + + + + +
+ This parameter is only valid for "scrollable" cursors. + + + When using "scrollable" cursors, the cursor can be freely + positioned on the result set. If the + whence parameter is + omitted, the global default values for the scrolling type + (initialized to: SESAM_SEEK_NEXT, and settable + by sesam_seek_row) are used. If + whence is supplied, + its value replaces the global default. + + + offset is an optional + parameter which is only evaluated (and required) if + whence is either + SESAM_SEEK_RELATIVE or + SESAM_SEEK_ABSOLUTE. This parameter is only + valid for "scrollable" cursors. + + + sesam_fetch_row fetches one row of data from + the result associated with the specified result identifier. The + row is returned as an array (indexed by values between + 0 and $array["count"]-1). + Fields may be empty, so you must check for the existence of a + field by using the isset function. The + type of the returned fields depend on the respective SQL type + declared for its column (see SESAM + overview for the conversions applied). SESAM "multiple + fields" are "inlined" and treated like a sequence of columns. + + + Subsequent calls to sesam_fetch_row would + return the next (or prior, or n'th next/prior, depending on the + scroll attributes) row in the result set, or + &false; if there are no more rows. + + + SESAM fetch rows + \n"; sesam_free_result($result); ?> ]]> - - - - See also: sesam_fetch_array which returns an - associative array, and sesam_fetch_result - which returns many rows per invocation. - - - + + + + See also: sesam_fetch_array which returns an + associative array, and sesam_fetch_result + which returns many rows per invocation. + + + + - - - sesam_field_array - - Return meta information about individual columns in a result - - - - Description - - arraysesam_field_array - stringresult_id - - - result_id is a valid result id returned by - sesam_query. - - - Returns a mixed associative/indexed array with meta information - (column name, type, precision, ...) about individual columns of - the result after the query associated with - result_id. - - - - - Mixed result set returned by <function>sesam_field_array</function> - - - - - Array Element - Contents - - - - - int $arr["count"] - - Total number of columns in result set (or zero if this was - an "immediate" query). SESAM "multiple fields" are - "inlined" and treated like the respective number of columns. - - - - string $arr[col]["name"] - - column name for column(col), where - col is between 0 and - $arr["count"]-1. The returned value can - be the empty string (for dynamically computed - columns). SESAM "multiple fields" are "inlined" and treated - like the respective number of columns, each with the same - column name. - - - - string $arr[col]["count"] - - The "count" attribute describes the repetition factor when - the column has been declared as a "multiple field". Usually, - the "count" attribute is 1. The first column of a "multiple - field" column however contains the number of repetitions - (the second and following column of the "multiple field" - contain a "count" attribute of 1). This can be used to - detect "multiple fields" in the result set. See the example - shown in the sesam_query description - for a sample use of the "count" attribute. - - - - string $arr[col]["type"] - - PHP variable type of the data for - column(col), where col - is between 0 and $arr["count"]-1. The - returned value can be one of - - - integer - - - float - - - string - - - depending on the SQL type of the result. SESAM "multiple - fields" are "inlined" and treated like the respective number - of columns, each with the same PHP type. - - - - string $arr[col]["sqltype"] - - SQL variable type of the column data for - column(col), where col - is between 0 and $arr["count"]-1. The - returned value can be one of - - - "CHARACTER" - - - "VARCHAR" - - - "NUMERIC" - - - "DECIMAL" - - - "INTEGER" - - - "SMALLINT" - - - "FLOAT" - - - "REAL" - - - "DOUBLE" - - - "DATE" - - - "TIME" - - - "TIMESTAMP" - - - describing the SQL type of the result. SESAM "multiple - fields" are "inlined" and treated like the respective number - of columns, each with the same SQL type. - - - - string $arr[col]["length"] - - The SQL "length" attribute of the SQL variable in - column(col), where col - is between 0 and $arr["count"]-1. The - "length" attribute is used with "CHARACTER" and "VARCHAR" - SQL types to specify the (maximum) length of the string - variable. SESAM "multiple fields" are "inlined" and treated - like the respective number of columns, each with the same - length attribute. - - - - string $arr[col]["precision"] - - The "precision" attribute of the SQL variable in - column(col), where col - is between 0 and $arr["count"]-1. The - "precision" attribute is used with numeric and time data - types. SESAM "multiple fields" are "inlined" and treated - like the respective number of columns, each with the same - precision attribute. - - - - string $arr[col]["scale"] - - The "scale" attribute of the SQL variable in - column(col), where col - is between 0 and $arr["count"]-1. The - "scale" attribute is used with numeric data types. SESAM - "multiple fields" are "inlined" and treated like the - respective number of columns, each with the same scale - attribute. - - - - -
- - - See also sesam_query for an example - of the sesam_field_array use. - - - + + + sesam_field_array + Return meta information about individual columns in a result + + + Description + + arraysesam_field_array + stringresult_id + + + result_id is a valid result id returned by + sesam_query. + + + Returns a mixed associative/indexed array with meta information + (column name, type, precision, ...) about individual columns of + the result after the query associated with + result_id. + + + + + Mixed result set returned by <function>sesam_field_array</function> + + + + + Array Element + Contents + + + + + int $arr["count"] + + Total number of columns in result set (or zero if this was + an "immediate" query). SESAM "multiple fields" are + "inlined" and treated like the respective number of columns. + + + + string $arr[col]["name"] + + column name for column(col), where + col is between 0 and + $arr["count"]-1. The returned value can + be the empty string (for dynamically computed + columns). SESAM "multiple fields" are "inlined" and treated + like the respective number of columns, each with the same + column name. + + + + string $arr[col]["count"] + + The "count" attribute describes the repetition factor when + the column has been declared as a "multiple field". Usually, + the "count" attribute is 1. The first column of a "multiple + field" column however contains the number of repetitions + (the second and following column of the "multiple field" + contain a "count" attribute of 1). This can be used to + detect "multiple fields" in the result set. See the example + shown in the sesam_query description + for a sample use of the "count" attribute. + + + + string $arr[col]["type"] + + PHP variable type of the data for + column(col), where col + is between 0 and $arr["count"]-1. The + returned value can be one of + + + integer + + + float + + + string + + + depending on the SQL type of the result. SESAM "multiple + fields" are "inlined" and treated like the respective number + of columns, each with the same PHP type. + + + + string $arr[col]["sqltype"] + + SQL variable type of the column data for + column(col), where col + is between 0 and $arr["count"]-1. The + returned value can be one of + + + "CHARACTER" + + + "VARCHAR" + + + "NUMERIC" + + + "DECIMAL" + + + "INTEGER" + + + "SMALLINT" + + + "FLOAT" + + + "REAL" + + + "DOUBLE" + + + "DATE" + + + "TIME" + + + "TIMESTAMP" + + + describing the SQL type of the result. SESAM "multiple + fields" are "inlined" and treated like the respective number + of columns, each with the same SQL type. + + + + string $arr[col]["length"] + + The SQL "length" attribute of the SQL variable in + column(col), where col + is between 0 and $arr["count"]-1. The + "length" attribute is used with "CHARACTER" and "VARCHAR" + SQL types to specify the (maximum) length of the string + variable. SESAM "multiple fields" are "inlined" and treated + like the respective number of columns, each with the same + length attribute. + + + + string $arr[col]["precision"] + + The "precision" attribute of the SQL variable in + column(col), where col + is between 0 and $arr["count"]-1. The + "precision" attribute is used with numeric and time data + types. SESAM "multiple fields" are "inlined" and treated + like the respective number of columns, each with the same + precision attribute. + + + + string $arr[col]["scale"] + + The "scale" attribute of the SQL variable in + column(col), where col + is between 0 and $arr["count"]-1. The + "scale" attribute is used with numeric data types. SESAM + "multiple fields" are "inlined" and treated like the + respective number of columns, each with the same scale + attribute. + + + + +
+ + + See also sesam_query for an example + of the sesam_field_array use. + + + + - - - sesam_field_name - - Return one column name of the result set - - - - Description - - intsesam_field_name - stringresult_id - intindex - - - Returns the name of a field (i.e., the column name) in the result - set, or &false; on error. - - - For "immediate" queries, or for dynamic columns, an empty string - is returned. - - - - The column index is zero-based, not one-based as in SESAM. - - - - See also: sesam_field_array. It provides an - easier interface to access the column names and types, and allows - for detection of "multiple fields". - - - + + + sesam_field_name + Return one column name of the result set + + + Description + + intsesam_field_name + stringresult_id + intindex + + + Returns the name of a field (i.e., the column name) in the result + set, or &false; on error. + + + For "immediate" queries, or for dynamic columns, an empty string + is returned. + + + + The column index is zero-based, not one-based as in SESAM. + + + + See also: sesam_field_array. It provides an + easier interface to access the column names and types, and allows + for detection of "multiple fields". + + + + - - - sesam_free_result - Releases resources for the query - - - Description - - intsesam_free_result - stringresult_id - - - Releases resources for the query associated with - result_id. Returns - &false; on error. - - - + + + sesam_free_result + Releases resources for the query + + + Description + + intsesam_free_result + stringresult_id + + + Releases resources for the query associated with + result_id. Returns + &false; on error. + + + + - - - sesam_num_fields - - Return the number of fields/columns in a result set - - - - Description - - intsesam_num_fields - stringresult_id - - - After calling sesam_query with a "select - type" query, this function gives you the number of columns in the - result. Returns an integer describing the total number of - columns (aka. fields) in the current - result_id result set or - &false; on error. - - - For "immediate" statements, the value zero is returned. The SESAM - "multiple field" columns count as their respective dimension, - i.e., a three-column "multiple field" counts as three columns. - - - See also: sesam_query and - sesam_field_array for a way to distinguish - between "multiple field" columns and regular columns. - - - + + + sesam_num_fields + Return the number of fields/columns in a result set + + + Description + + intsesam_num_fields + stringresult_id + + + After calling sesam_query with a "select + type" query, this function gives you the number of columns in the + result. Returns an integer describing the total number of + columns (aka. fields) in the current + result_id result set or + &false; on error. + + + For "immediate" statements, the value zero is returned. The SESAM + "multiple field" columns count as their respective dimension, + i.e., a three-column "multiple field" counts as three columns. + + + See also: sesam_query and + sesam_field_array for a way to distinguish + between "multiple field" columns and regular columns. + + + + - - - sesam_query - Perform a SESAM SQL query and prepare the result - - - Description - - stringsesam_query - stringquery - boolscrollable - - - Returns: A SESAM "result identifier" on success, or - &false; on error. - - - A "result_id" resource is used by other functions to retrieve the - query results. - - - sesam_query sends a query to the currently - active database on the server. It can execute both "immediate" - SQL statements and "select type" queries. If an "immediate" - statement is executed, then no cursor is allocated, and any - subsequent sesam_fetch_row or - sesam_fetch_result call will return an empty - result (zero columns, indicating end-of-result). For "select - type" statements, a result descriptor and a (scrollable or - sequential, depending on the optional boolean - scrollable parameter) cursor will be - allocated. If scrollable is omitted, the - cursor will be sequential. - - - When using "scrollable" cursors, the cursor can be freely - positioned on the result set. For each "scrollable" query, there - are global default values for the scrolling type (initialized to: - SESAM_SEEK_NEXT) and the scrolling offset - which can either be set once by - sesam_seek_row or each time when fetching a - row using sesam_fetch_row. - - - For "immediate" statements, the number of affected rows is saved - for retrieval by the sesam_affected_rows - function. - - - See also: sesam_fetch_row and - sesam_fetch_result. - - - Show all rows of the "phone" table as a HTML table - - + + + sesam_query + Perform a SESAM SQL query and prepare the result + + + Description + + stringsesam_query + stringquery + boolscrollable + + + Returns: A SESAM "result identifier" on success, or + &false; on error. + + + A "result_id" resource is used by other functions to retrieve the + query results. + + + sesam_query sends a query to the currently + active database on the server. It can execute both "immediate" + SQL statements and "select type" queries. If an "immediate" + statement is executed, then no cursor is allocated, and any + subsequent sesam_fetch_row or + sesam_fetch_result call will return an empty + result (zero columns, indicating end-of-result). For "select + type" statements, a result descriptor and a (scrollable or + sequential, depending on the optional boolean + scrollable parameter) cursor will be + allocated. If scrollable is omitted, the + cursor will be sequential. + + + When using "scrollable" cursors, the cursor can be freely + positioned on the result set. For each "scrollable" query, there + are global default values for the scrolling type (initialized to: + SESAM_SEEK_NEXT) and the scrolling offset + which can either be set once by + sesam_seek_row or each time when fetching a + row using sesam_fetch_row. + + + For "immediate" statements, the number of affected rows is saved + for retrieval by the sesam_affected_rows + function. + + + See also: sesam_fetch_row and + sesam_fetch_result. + + + Show all rows of the "phone" table as a HTML table + + \n"; sesam_free_result($result); ?> ]]> - - - - - + + + + + + - - - sesam_rollback - - Discard any pending updates to the SESAM database - - - - Description - - boolsesam_rollback - - - - Returns: &true; on success, - &false; on errors - - - sesam_rollback discards any pending updates - to the database. Also affected are result cursors and result - descriptors. - - - At the end of each script, and as part of the - sesam_disconnect function, an implied - sesam_rollback is executed, discarding any - pending changes to the database. - - - See also: sesam_commit. - - Discarding an update to the SESAM database - + + + sesam_rollback + Discard any pending updates to the SESAM database + + + Description + + boolsesam_rollback + + + + Returns: &true; on success, + &false; on errors + + + sesam_rollback discards any pending updates + to the database. Also affected are result cursors and result + descriptors. + + + At the end of each script, and as part of the + sesam_disconnect function, an implied + sesam_rollback is executed, discarding any + pending changes to the database. + + + See also: sesam_commit. + + Discarding an update to the SESAM database + ]]> - - - - - + + + + + + - - - sesam_seek_row - - Set scrollable cursor mode for subsequent fetches - - - - Description - - boolsesam_seek_row - stringresult_id - intwhence - intoffset - - - result_id is a valid result id (select - type queries only, and only if a "scrollable" cursor was - requested when calling sesam_query). - - - whence sets the global default value for - the scrolling type, it specifies the scroll type to use in - subsequent fetch operations on "scrollable" cursors, which can be - set to the following predefined constants: - - Valid values for <parameter>"whence"</parameter> parameter - - - - Value - Constant - Meaning - - - - - 0 - SESAM_SEEK_NEXT - read sequentially - - - - 1 - SESAM_SEEK_PRIOR - read sequentially backwards - - - - 2 - SESAM_SEEK_FIRST - - fetch first row (after fetch, the default is set to - SESAM_SEEK_NEXT) - - - - 3 - SESAM_SEEK_LAST - - fetch last row (after fetch, the default is set to - SESAM_SEEK_PRIOR) - - - - 4 - SESAM_SEEK_ABSOLUTE - - fetch absolute row number given as - offset (Zero-based. After fetch, the - default is set to SESAM_SEEK_ABSOLUTE, - and the offset value is auto-incremented) - - - - 5 - SESAM_SEEK_RELATIVE - - fetch relative to current scroll position, where - offset can be a positive or negative - offset value (this also sets the default "offset" value for - subsequent fetches). - - - - -
- - - offset is an optional - parameter which is only evaluated (and required) if - whence is either - SESAM_SEEK_RELATIVE or - SESAM_SEEK_ABSOLUTE. - - - + + + sesam_seek_row + Set scrollable cursor mode for subsequent fetches + + + Description + + boolsesam_seek_row + stringresult_id + intwhence + intoffset + + + result_id is a valid result id (select + type queries only, and only if a "scrollable" cursor was + requested when calling sesam_query). + + + whence sets the global default value for + the scrolling type, it specifies the scroll type to use in + subsequent fetch operations on "scrollable" cursors, which can be + set to the following predefined constants: + + Valid values for <parameter>"whence"</parameter> parameter + + + + Value + Constant + Meaning + + + + + 0 + SESAM_SEEK_NEXT + read sequentially + + + + 1 + SESAM_SEEK_PRIOR + read sequentially backwards + + + + 2 + SESAM_SEEK_FIRST + + fetch first row (after fetch, the default is set to + SESAM_SEEK_NEXT) + + + + 3 + SESAM_SEEK_LAST + + fetch last row (after fetch, the default is set to + SESAM_SEEK_PRIOR) + + + + 4 + SESAM_SEEK_ABSOLUTE + + fetch absolute row number given as + offset (Zero-based. After fetch, the + default is set to SESAM_SEEK_ABSOLUTE, + and the offset value is auto-incremented) + + + + 5 + SESAM_SEEK_RELATIVE + + fetch relative to current scroll position, where + offset can be a positive or negative + offset value (this also sets the default "offset" value for + subsequent fetches). + + + + +
+ + + offset is an optional + parameter which is only evaluated (and required) if + whence is either + SESAM_SEEK_RELATIVE or + SESAM_SEEK_ABSOLUTE. + + + + - - - sesam_settransaction - Set SESAM transaction parameters - - - Description - - boolsesam_settransaction - intisolation_level - intread_only - - - Returns: &true; if the values are valid, and the - settransaction operation was successful, - &false; otherwise. - - - sesam_settransaction overrides the default - values for the "isolation level" and "read-only" transaction - parameters (which are set in the SESAM configuration file), in - order to optimize subsequent queries and guarantee database - consistency. The overridden values are used for the next - transaction only. - - - sesam_settransaction can only be called - before starting a transaction, not after the transaction has been - started already. - - - To simplify the use in PHP scripts, the following constants have - been predefined in PHP (see SESAM handbook for detailed - explanation of the semantics): - - - Valid values for <parameter>"Isolation_Level"</parameter> - parameter - - - - - Value - Constant - Meaning - - - - - 1 - SESAM_TXISOL_READ_UNCOMMITTED - Read Uncommitted - - - 2 - SESAM_TXISOL_READ_COMMITTED - Read Committed - - - 3 - SESAM_TXISOL_REPEATABLE_READ - Repeatable Read - - - 4 - SESAM_TXISOL_SERIALIZABLE - Serializable - - - -
- - - Valid values for <parameter>"Read_Only"</parameter> parameter - - - - - Value - Constant - Meaning - - - - - 0 - SESAM_TXREAD_READWRITE - Read/Write - - - 1 - SESAM_TXREAD_READONLY - Read-Only - - - -
- - - The values set by sesam_settransaction will - override the default setting specified in the SESAM configuration file. - - - - Setting SESAM transaction parameters - + + + sesam_settransaction + Set SESAM transaction parameters + + + Description + + boolsesam_settransaction + intisolation_level + intread_only + + + Returns: &true; if the values are valid, and the + settransaction operation was successful, + &false; otherwise. + + + sesam_settransaction overrides the default + values for the "isolation level" and "read-only" transaction + parameters (which are set in the SESAM configuration file), in + order to optimize subsequent queries and guarantee database + consistency. The overridden values are used for the next + transaction only. + + + sesam_settransaction can only be called + before starting a transaction, not after the transaction has been + started already. + + + To simplify the use in PHP scripts, the following constants have + been predefined in PHP (see SESAM handbook for detailed + explanation of the semantics): + + + Valid values for <parameter>"Isolation_Level"</parameter> + parameter + + + + + Value + Constant + Meaning + + + + + 1 + SESAM_TXISOL_READ_UNCOMMITTED + Read Uncommitted + + + 2 + SESAM_TXISOL_READ_COMMITTED + Read Committed + + + 3 + SESAM_TXISOL_REPEATABLE_READ + Repeatable Read + + + 4 + SESAM_TXISOL_SERIALIZABLE + Serializable + + + +
+ + + Valid values for <parameter>"Read_Only"</parameter> parameter + + + + + Value + Constant + Meaning + + + + + 0 + SESAM_TXREAD_READWRITE + Read/Write + + + 1 + SESAM_TXREAD_READONLY + Read-Only + + + +
+ + + The values set by sesam_settransaction will + override the default setting specified in the SESAM configuration file. + + + + Setting SESAM transaction parameters + ]]> - - - - - + + + + +