pike.git / lib / modules / __builtin.pmod / Sql.pmod / Connection.pike

version» Context lines:

pike.git/lib/modules/__builtin.pmod/Sql.pmod/Connection.pike:558:   }      //! Send an SQL query synchronously to the SQL-server and return   //! the results in untyped mode.   //!   //! @param q   //! Query to send to the SQL-server. This can either be a string with the   //! query, or a previously compiled query (see @[compile_query()]).   //!   //! @returns - //! The result is returned as an @[Sql.Result] object in untyped + //! An @[Sql.Result] object in untyped   //! mode. This allows for having some more info about the result as   //! well as processing the result in a streaming fashion, although the   //! result itself wasn't obtained streamingly from the server.   //!   //! @throws - //! Throws an exception if the query fails. + //! Might throw an exception if the query fails. In some cases, the + //! exception is delayed, because the database reports the error + //! a (little) while after the query has already been started.   //! - //! Called by other variants of @[big_query()] after they have processed - //! their extra arguments. - //! +    //! This prototype function is the base variant and is intended to be   //! overloaded by actual drivers.   //!   //! @note   //! Despite the name, this function is not only useful for "big"   //! queries. It typically has less overhead than @[query] also for   //! ones that return only a few rows.   //!   //! @seealso - //! @[query], @[streaming_query] + //! @[query], @[streaming_query], @[big_typed_query], @[streaming_typed_query]   variant .Result big_query(object|string q);      //! Send an SQL query synchronously to the SQL-server and return   //! the results in untyped mode.   //!   //! @param q   //! Query to send to the SQL-server. This can either be a string with the   //! query, or a previously compiled query (see @[compile_query()]).   //!   //! @param bindings
pike.git/lib/modules/__builtin.pmod/Sql.pmod/Connection.pike:603:   //! the variable is used.   //!   //! @code   //! res = query("SELECT foo FROM bar WHERE gazonk=:baz",   //! ([":baz":"value"]));   //! @endcode   //!   //! Binary values (BLOBs) may need to be placed in multisets.   //!   //! @returns - //! The result is returned as an @[Sql.Result] object in untyped + //! An @[Sql.Result] object in untyped   //! mode. This allows for having some more info about the result as   //! well as processing the result in a streaming fashion, although the   //! result itself wasn't obtained streamingly from the server.   //!   //! @throws - //! Throws an exception if the query fails. + //! Might throw an exception if the query fails. In some cases, the + //! exception is delayed, because the database reports the error + //! a (little) while after the query has already been started.   //!   //! Calls the base variant of @[big_query()] after having inserted   //! the bindings into the query (using @[emulate_bindings()]).   //!   //! Drivers that actually support bindings should overload this   //! variant in addition to the base variant.   //!   //! @note   //! Despite the name, this function is not only useful for "big"   //! queries. It typically has less overhead than @[query] also for   //! ones that return only a few rows.   //!   //! @seealso - //! @[query], @[emulate_bindings], @[streaming_query] + //! @[query], @[emulate_bindings], @[streaming_query], @[big_typed_query], + //! @[streaming_typed_query]   variant .Result big_query(object|string q,    mapping(string|int:mixed) bindings)   {    return big_query(emulate_bindings(q, bindings));   }      //! Send an SQL query synchronously to the SQL-server and return   //! the results in untyped mode.   //!   //! @param q
pike.git/lib/modules/__builtin.pmod/Sql.pmod/Connection.pike:646:   //!   //! @param extraarg   //! @param extraargs   //! Arguments as you would use in sprintf. They are automatically   //! quoted.   //!   //! @code   //! res = query("select foo from bar where gazonk=%s","value");   //! @endcode   //! - //! The result is returned as an @[Sql.Result] object in untyped - //! mode. This allows for having some more info about the result as - //! well as processing the result in a streaming fashion, although the - //! result itself wasn't obtained streamingly from the server. + //! @returns + //! An @[Sql.Result] object in untyped + //! mode. This allows for having some more info about the result as + //! well as processing the result in a streaming fashion, although the + //! result itself wasn't obtained streamingly from the server.   //!   //! The default implementation normalizes @[q] and @[extraargs] to   //! use the bindings mapping (via @[handle_extraargs()]), and calls   //! one of the other variants of @[big_query()] with the result.   //!   //! @note   //! Despite the name, this function is not only useful for "big"   //! queries. It typically has less overhead than @[query] also for   //! ones that return only a few rows.   //!
pike.git/lib/modules/__builtin.pmod/Sql.pmod/Connection.pike:706:    mixed ... extraargs)   {    return res_obj_to_array(big_query(q, @extraargs));   }      //! Send an SQL query synchronously to the SQL-server and return   //! the results in typed mode.   //!   //! For the argument, please see the @[big_query()] function.   //! - //! The result is returned as an @[Sql.Result] object in typed + //! @returns + //! An @[Sql.Result] object in typed   //! mode. This allows for having some more info about the result as   //! well as processing the result in a streaming fashion, although the   //! result itself wasn't obtained streamingly from the server.   //!   //! @note - //! Typed mode is not supported by all sql databases. If not - //! supported, an error is thrown. + //! Typed mode support varies per database and per datatype. + //! SQL datatypes which the current database cannot return as a native Pike + //! type, will be returned as (untyped) strings.   //!   //! @note   //! Despite the name, this function is not only useful for "big"   //! queries. It typically has less overhead than @[typed_query] also   //! for ones that return only a few rows.   //! - //! Called by @[big_typed_query()] after it has processed any bindings. - //! +    //! Drivers should override this prototype function.   //!   //! @seealso   //! @[query], @[typed_query], @[big_query], @[streaming_query] - variant .Result big_typed_query(object|string q); + variant .Result big_typed_query(object|string q) + { +  return big_query(q); // Fall back to untyped, if no native support + }      //! Send an SQL query synchronously to the SQL-server and return   //! the results in typed mode.   //!   //! For the arguments, please see the @[big_query()] function.   //!   //! The result is returned as an @[Sql.Result] object in typed   //! mode. This allows for having some more info about the result as   //! well as processing the result in a streaming fashion, although the   //! result itself wasn't obtained streamingly from the server.   //!   //! @note - //! Typed mode is not supported by all sql databases. If not - //! supported, an error is thrown. + //! Typed mode support varies per database and per datatype. + //! SQL datatypes which the current database cannot return as a native Pike + //! type, will be returned as (untyped) strings.   //!   //! @note   //! Despite the name, this function is not only useful for "big"   //! queries. It typically has less overhead than @[typed_query] also   //! for ones that return only a few rows.   //! - //! Called by @[big_typed_query()] after it has processed any bindings. + //! Drivers that actually support bindings should overload this + //! variant in addition to the base variant.   //!   //! @seealso   //! @[query], @[typed_query], @[big_query], @[streaming_query]   variant .Result big_typed_query(object|string q,    mapping(string|int:mixed) bindings)   {    return big_typed_query(emulate_bindings(q, bindings));   }      //! Send an SQL query synchronously to the SQL-server and return   //! the results in typed mode.   //!   //! For the arguments, please see the @[big_query()] function.   //!   //! The result is returned as an @[Sql.Result] object in typed   //! mode. This allows for having some more info about the result as   //! well as processing the result in a streaming fashion, although the   //! result itself wasn't obtained streamingly from the server.   //!   //! @note - //! Typed mode is not supported by all sql databases. If not - //! supported, an error is thrown. + //! Typed mode support varies per database and per datatype. + //! SQL datatypes which the current database cannot return as a native Pike + //! type, will be returned as (untyped) strings.   //!   //! @note   //! Despite the name, this function is not only useful for "big"   //! queries. It typically has less overhead than @[typed_query] also   //! for ones that return only a few rows.   //!   //! @seealso   //! @[query], @[typed_query], @[big_query], @[streaming_query]   variant .Result big_typed_query(object|string q,    string|multiset|int|float|object extraarg,
pike.git/lib/modules/__builtin.pmod/Sql.pmod/Connection.pike:804:   //! The result as an array of mappings indexed on the name of   //! the columns. The values have the appropriate native pike   //! types where they fit the SQL data types - see the class doc   //! for details on typed mode.   //! @type zero   //! The value @expr{0@} (zero) if the query didn't return any   //! result (eg @tt{INSERT@} or similar).   //! @endmixed   //!   //! @note - //! Typed mode is not supported by all sql databases. If not - //! supported, an error is thrown. + //! Typed mode support varies per database and per datatype. + //! SQL datatypes which the current database cannot return as a native Pike + //! type, will be returned as (untyped) strings.   //!   //! @note   //! The default implementation calls @[big_typed_query()]   //! and converts its result.   //!   //! @seealso   //! @[query], @[big_typed_query]   array(mapping(string:mixed)) typed_query(object|string q, mixed ... extraargs)   {    return res_obj_to_array(big_typed_query(q, @extraargs));   }      //! Send an SQL query synchronously to the SQL-server and return   //! the results streaming in untyped mode.   //! - //! For the arguments, please see the @[low_big_query()] function. + //! For the arguments, please see the @[big_query()] function.   //! - //! The result is returned as a streaming @[Sql.Result] object in + //! @returns + //! A streaming @[Sql.Result] object in   //! untyped mode. This allows for having results larger than the   //! available memory, and returning some more info about the result. - //! For the other arguments, they are the same as - //! for the @[query()] function. +    //! - //! Called by @[streaming_query()] after it has processed any bindings. - //! +    //! Drivers should override this prototype function.   //!   //! @note - //! Streaming operation is not supported by all sql databases. - //! The default implementation falls back to calling @[big_query()]. + //! Typed mode support varies per database and per datatype. + //! SQL datatypes which the current database cannot return as a native Pike + //! type, will be returned as (untyped) strings.   //!   //! @seealso   //! @[big_query], @[streaming_typed_query]   variant .Result streaming_query(object|string q)   {    return big_query(q);   }      //! Send an SQL query synchronously to the SQL-server and return   //! the results streaming in untyped mode.   //! - //! For the arguments, please see the @[low_big_query()] function. + //! For the arguments, please see the @[big_query()] function.   //! - //! The result is returned as a streaming @[Sql.Result] object in + //! @returns + //! A streaming @[Sql.Result] object in   //! untyped mode. This allows for having results larger than the   //! available memory, and returning some more info about the result. - //! For the other arguments, they are the same as - //! for the @[query()] function. +    //! - //! Called by @[streaming_query()] after it has processed any bindings. - //! +    //! Drivers that implement bindings should override this prototype function.   //! - //! @note - //! Streaming operation is not supported by all sql databases. - //! The default implementation falls back to calling @[big_query()]. - //! +    //! @seealso   //! @[big_query], @[streaming_typed_query]   variant .Result streaming_query(object|string q,    mapping(string:mixed) bindings)   {    return streaming_query(emulate_bindings(q, bindings));   }      //! Send an SQL query synchronously to the SQL-server and return   //! the results streaming in untyped mode.   //! - //! For the arguments, please see the @[query()] function. + //! For the arguments, please see the @[big_query()] function.   //! - //! The result is returned as a streaming @[Sql.Result] object in + //! @returns + //! A streaming @[Sql.Result] object in   //! untyped mode. This allows for having results larger than the   //! available memory, and returning some more info about the result. - //! For the other arguments, they are the same as - //! for the @[query()] function. +    //! - //! @note - //! Streaming operation is not supported by all sql databases. - //! If not supported, this function will fall back to calling - //! @[big_query()]. - //! +    //! @seealso   //! @[big_query], @[streaming_typed_query]   variant .Result streaming_query(object|string q,    string|multiset|int|float|object extraarg,    string|multiset|int|float|object ... extraargs)   {    return streaming_query(@handle_extraargs(q, ({ extraarg }) + extraargs));   }      //! Send an SQL query synchronously to the SQL-server and return   //! the results streaming in typed mode.   //! - //! For the arguments, please see the @[query()] function. + //! For the arguments, please see the @[big_query()] function.   //! - //! The result is returned as a streaming @[Sql.Result] object in + //! @returns + //! A streaming @[Sql.Result] object in   //! typed mode. This allows for having results larger than the   //! available memory, and returning some more info about the result.   //! - //! Called by @[streaming_query()] after it has processed any bindings. - //! +    //! Drivers should override this prototype function.   //! - //! @note - //! Neither streaming operation nor typed results are supported - //! by all sql databases. The default implentation falls back to - //! calling @[big_typed_query()]. - //! +    //! @seealso - //! @[streaming_query], @[big_typed_query] + //! @[big_query], @[streaming_query], @[big_typed_query]   variant .Result streaming_typed_query(object|string q)   {    return big_typed_query(q);   }      //! Send an SQL query synchronously to the SQL-server and return   //! the results streaming in typed mode.   //! - //! For the arguments, please see the @[query()] function. + //! For the arguments, please see the @[big_query()] function.   //! - //! The result is returned as a streaming @[Sql.Result] object in + //! @returns + //! A streaming @[Sql.Result] object in   //! typed mode. This allows for having results larger than the   //! available memory, and returning some more info about the result.   //! - //! - //! Called by @[streaming_query()] after it has processed any bindings. - //! +    //! Drivers should override this prototype function.   //! - //! @note - //! Neither streaming operation nor typed results are supported - //! by all sql databases. The default implentation falls back to - //! calling @[low_big_typed_query()]. - //! +    //! @seealso - //! @[streaming_query], @[big_typed_query] + //! @[big_query], @[streaming_query], @[big_typed_query]   variant .Result streaming_typed_query(object|string q,    mapping(string|int:mixed) bindings)   {    return streaming_typed_query(emulate_bindings(q, bindings));   }      //! Send an SQL query synchronously to the SQL-server and return   //! the results streaming in typed mode.   //!   //! For the arguments, please see the @[query()] function.   //! - //! The result is returned as a streaming @[Sql.Result] object in + //! @returns + //! A streaming @[Sql.Result] object in   //! typed mode. This allows for having results larger than the   //! available memory, and returning some more info about the result.   //! - //! @note - //! Neither streaming operation nor typed results are supported - //! by all sql databases. If not supported, this function will - //! fall back to calling @[big_typed_query()]. - //! +    //! @seealso - //! @[streaming_query], @[big_typed_query] + //! @[big_query], @[streaming_query], @[big_typed_query]   variant .Result streaming_typed_query(object|string q,    string|multiset|int|float|object extraarg,    string|multiset|int|float|object ... extraargs)   {    return streaming_typed_query(@handle_extraargs(q, ({ extraarg }) + extraargs));   }      //! Create a new database.   //!   //! @param db