Branch: Tag:

2009-02-15

2009-02-15 21:53:40 by Stephen R. van den Berg <srb@cuci.nl>

Additional doc tuning.

Rev: lib/modules/Sql.pmod/pgsql.pike:1.57
Rev: lib/modules/Sql.pmod/pgsql_util.pmod:1.16

149:   //! PostgreSQL backend. Since PostgreSQL requires a database to be   //! selected, it will try to connect to the default database. The   //! connection may fail however, for a variety of reasons; in this case - //! the most likely reason is because you don't have enough privileges + //! the most likely reason is because you don't have sufficient privileges   //! to connect to that database. So use of this particular syntax is   //! discouraged.   //!
168:   //! @param options   //! Currently supports at least the following:   //! @mapping - //! @member int "use_ssl" + //! @member int use_ssl   //! If the database supports and allows SSL connections, the session   //! will be SSL encrypted, if not, the connection will fallback   //! to plain unencrypted - //! @member int "force_ssl" + //! @member int force_ssl   //! If the database supports and allows SSL connections, the session   //! will be SSL encrypted, if not, the connection will abort - //! @member int "cache_autoprepared_statements" + //! @member int cache_autoprepared_statements   //! If set to zero, it disables the automatic statement prepare and   //! cache logic; caching prepared statements can be problematic   //! when stored procedures and tables are redefined which leave stale   //! references in the already cached prepared statements - //! @member string "client_encoding" + //! @member string client_encoding   //! Character encoding for the client side, it defaults to using   //! the default encoding specified by the database, e.g.: "SQL_ASCII" - //! @member string "standard_conforming_strings" + //! @member string standard_conforming_strings   //! When on, backslashes in strings must not be escaped any longer,   //! @[quote()] automatically adjusts quoting strategy accordingly - //! @member string "escape_string_warning" + //! @member string escape_string_warning   //! When on, a warning is issued if a backslash (\) appears in an   //! ordinary string literal and @[standard_conforming_strings] is off,   //! defaults to on
346:   //! during session creation, and then processed and returned by the server.   //! Common values are:   //! @mapping - //! @member string "client_encoding" + //! @member string client_encoding   //! Character encoding for the client side, e.g.: "SQL_ASCII" - //! @member string "server_encoding" + //! @member string server_encoding   //! Character encoding for the server side as determined when the   //! database was created, e.g.: "SQL_ASCII" - //! @member string "DateStyle" + //! @member string DateStyle   //! Date parsing/display, e.g.: "ISO, DMY" - //! @member string "TimeZone" + //! @member string TimeZone   //! Default timezone used by the database, e.g.: "localtime" - //! @member string "standard_conforming_strings" + //! @member string standard_conforming_strings   //! When on, backslashes in strings must not be escaped any longer - //! @member string "session_authorization" + //! @member string session_authorization   //! Displays the authorisationrole which the current session runs under - //! @member string "is_superuser" + //! @member string is_superuser   //! Indicates if the current authorisationrole has database-superuser   //! privileges - //! @member string "integer_datetimes" + //! @member string integer_datetimes   //! Reports wether the database supports 64-bit-integer dates and times - //! @member string "server_version" + //! @member string server_version   //! Shows the server version, e.g.: "8.3.3"   //! @endmapping   //!
385:   //! @returns   //! A set of statistics for the current session:   //! @mapping - //! @member int "warnings_dropped" + //! @member int warnings_dropped   //! Number of warnings/notices generated by the database but not - //! collected by the application by using @[error] after the statements + //! collected by the application by using @[error()] after the statements   //! that generated them. - //! @member int "skipped_describe_count" + //! @member int skipped_describe_count   //! Number of times the driver skipped asking the database to   //! describe the statement parameters because it was already cached. - //! @member int "used_prepared_statements" + //! @member int used_prepared_statements   //! Numer of times prepared statements were used from cache instead of   //! reparsing in the current session. - //! @member int "current_prepared_statements" + //! @member int current_prepared_statements   //! Cache size of currently prepared statements. - //! @member int "current_prepared_statement_hits" + //! @member int current_prepared_statement_hits   //! Sum of the number hits on statements in the current statement cache. - //! @member int "prepared_portal_count" + //! @member int prepared_portal_count   //! Total number of prepared portals generated. - //! @member int "prepared_statement_count" + //! @member int prepared_statement_count   //! Total number of prepared statements generated. - //! @member int "portals_opened_count" + //! @member int portals_opened_count   //! Total number of portals opened, i.e. number of statements issued   //! to the database. - //! @member int "blocked_count" + //! @member int blocked_count   //! Number of times the driver had to (briefly) wait for the database to   //! send additional data. - //! @member int "bytes_received" + //! @member int bytes_received   //! Total number of bytes received from the database so far. - //! @member int "messages_received" + //! @member int messages_received   //! Total number of messages received from the database (one SQL-statement   //! requires multiple messages to be exchanged). - //! @member int "bytes_sent" + //! @member int bytes_sent   //! Total number of bytes sent to the database so far. - //! @member int "packets_sent" + //! @member int packets_sent   //! Total number of packets sent to the database (one packet usually   //! contains multiple messages). - //! @member int "reconnect_count" + //! @member int reconnect_count   //! Number of times the connection to the database has been lost. - //! @member int "portals_in_flight" + //! @member int portals_in_flight   //! Currently still open portals, i.e. running statements.   //! @endmapping   //!
481:    return oldtimeout;   }    - //! Returns the old portalbuffersize, sets the new portalbuffersize - //! for buffering partially concurrent queries. + //! @param newportalbuffersize + //! Sets the new portalbuffersize for buffering partially concurrent queries.   //! -  + //! @returns + //! The previous portalbuffersize. + //!   //! @note   //! This function is PostgreSQL-specific, and thus it is not available   //! through the generic SQL-interface.
494:    return oldportalbuffersize;   }    - //! Returns the old fetchlimit, sets the new fetchlimit to interleave - //! queries. + //! @param newfetchlimit + //! Sets the new fetchlimit to interleave queries.   //! -  + //! @returns + //! The previous fetchlimit. + //!   //! @note   //! This function is PostgreSQL-specific, and thus it is not available   //! through the generic SQL-interface.
1128:   //!   //! @note   //! This function @b{can@} raise exceptions if something goes wrong - //! (backend process not running, not enough permissions..) + //! (backend process not running, insufficient privileges...)   //!   //! @seealso   //! @[create()]
1146:   //! to. A special case is the empty string, which matches all events,   //! and can be used as fallback function which is called only when the   //! specific condition is not handled. Another special case is - //! @[_reconnect] which gets called whenever the connection unexpectedly + //! @ref{_reconnect@} which gets called whenever the connection unexpectedly   //! drops and reconnects to the database.   //!   //! @param notify_cb   //! Function to be called on receiving a notification-event of - //! condition @[condition]. + //! condition @ref{condition@}.   //! The callback function is invoked with   //! @expr{void notify_cb(pid,condition,extrainfo, .. args);@} - //! @[pid] is the process id of the database session that originated - //! the event. @[condition] contains the current condition. - //! @[extrainfo] contains optional extra information specified by + //! @ref{pid@} is the process id of the database session that originated + //! the event. @ref{condition@} contains the current condition. + //! @ref{extrainfo@} contains optional extra information specified by   //! the database. - //! The rest of the arguments to @[notify_cb] are passed - //! verbatim from @[args]. + //! The rest of the arguments to @ref{notify_cb@} are passed + //! verbatim from @ref{args@}.   //! The callback function must return no value.   //!   //! @param selfnotify   //! Normally notify events generated by your own session are ignored. - //! If you want to receive those as well, set @[selfnotify] to one. + //! If you want to receive those as well, set @ref{selfnotify@} to one.   //!   //! @param args - //! Extra arguments to pass to @[notify_cb]. + //! Extra arguments to pass to @ref{notify_cb@}.   //!   //! @note   //! This function is PostgreSQL-specific, and thus it is not available
1215:      //! @returns   //! The given string, but escapes/quotes all contained magic characters - //! according to the quoting rules of the current session for binary (bytea) - //! arguments in textual SQL-queries. + //! for binary (bytea) arguments in textual SQL-queries.   //!   //! @note   //! Quoting must not be done for parameters passed in bindings.
1232:   }      //! This function creates a new database (assuming we - //! have enough privileges to do this). + //! have sufficient privileges to do this).   //!   //! @param db   //! Name of the new database.
1244:   }      //! This function destroys a database and all the data it contains (assuming - //! we have enough privileges to do so). It is not possible to delete + //! we have sufficient privileges to do so). It is not possible to delete   //! the database you're currently connected to. You can connect to database   //! @ref{template1@} to avoid connecting to any live database.   //!
1315:   //! The currently defined fields are:   //!   //! @mapping - //! @member int "is_shared" - //! @member string "owner" + //! @member int is_shared + //! @member string owner   //! Tableowner - //! @member string "length" + //! @member string length   //! Size of the columndatatype - //! @member string "text" + //! @member string text   //! A textual description of the internal (to the server) type-name - //! @member mixed "default" + //! @member mixed default   //! Default value for the column - //! @member mixed "schema" + //! @member mixed schema   //! Schema the table belongs to - //! @member mixed "table" + //! @member mixed table   //! Name of the table - //! @member mixed "kind" + //! @member mixed kind   //! Type of table - //! @member mixed "has_index" + //! @member mixed has_index   //! If the table has any indices - //! @member mixed "has_primarykey" + //! @member mixed has_primarykey   //! If the table has a primary key - //! @member mixed "rowcount" + //! @member mixed rowcount   //! Estimated rowcount of the table - //! @member mixed "pagecount" + //! @member mixed pagecount   //! Estimated pagecount of the table   //! @endmapping   //!
1491:   //! @returns   //! The current commitstatus of the connection. Returns either one of:   //! @string - //! @value "idle" - //! @value "intransaction" - //! @value "infailedtransaction" + //! @value idle + //! @value intransaction + //! @value infailedtransaction   //! @endstring   //!   //! @note
1518:   //! @decl Sql.pgsql_util.pgsql_result big_query(string query, mapping bindings)   //!   //! This is the only provided interface which allows you to query the - //! database. If you wish to use the simpler "query" function, you need to - //! use the @[Sql.Sql] generic SQL-object. + //! database. If you wish to use the simpler @[Sql.Sql()->query()] function, + //! you need to use the @[Sql.Sql] generic SQL-object.   //! - //! Bindings are supported natively straight through the network. + //! Bindings are supported natively straight across the network.   //! Special bindings supported are:   //! @mapping   //! @member int ":_cache" - //! Forces caching or no caching for the query at hand. + //! Forces caching on or off for the query at hand.   //! @endmapping   //!   //! @returns   //! A @[Sql.pgsql_util.pgsql_result] object (which conforms to the - //! @[Sql.sql_result] standard interface for accessing data). I - //! recommend using @[query()] for simpler queries (because it is - //! easier to handle, but stores all the result in memory), and - //! @[big_query()] for queries you expect to return huge amounts of + //! @[Sql.sql_result] standard interface for accessing data). It is + //! recommended to use @[Sql.Sql()->query()] for simpler queries (because + //! it is easier to handle, but stores all the result in memory), and + //! @[Sql.Sql()->big_query()] for queries you expect to return huge amounts of   //! data (it's harder to handle, but fetches results on demand).   //!   //! @note
1547:   //! @note   //! This function does not support multiple queries in one querystring.   //! I.e. it allows for but does not require a trailing semicolon, but it - //! simply ignores any commands after the first semicolon. This can be - //! viewed as a limited protection against SQL-injection attacks. + //! simply ignores any commands after the first unquoted semicolon. This can + //! be viewed as a limited protection against SQL-injection attacks.   //!   //! @seealso - //! @[Sql.Sql], @[Sql.sql_result], @[Sql.pgsql_util.pgsql_result] + //! @[big_typed_query()], @[Sql.Sql], @[Sql.sql_result], + //! @[Sql.Sql()->query()], @[Sql.pgsql_util.pgsql_result]   object big_query(string q,void|mapping(string|int:mixed) bindings,    void|int _alltyped) {    string preparedname="";
1825:   //! streaming of multiple simultaneous queries through the same connection.   //!   //! @seealso - //! @[big_query()], @[Sql.Sql], @[Sql.sql_result] + //! @[big_query()], @[big_typed_query()], @[Sql.Sql], @[Sql.sql_result]   object streaming_query(string q,void|mapping(string|int:mixed) bindings) {    return big_query(q,bindings);   }