X-Git-Url: http://git.kpe.io/?p=clsql.git;a=blobdiff_plain;f=doc%2Fref.sgml;h=89113a8c0e4f86e9d33cb8b483c74e99d868c163;hp=a24ae22b0d337952b4fba2c2af9f476c0c715c1d;hb=f8478421f5a0440246f70aa4234ff25f416be7e3;hpb=3228710cd1c7c67628085f4d079d7deab3da47bc diff --git a/doc/ref.sgml b/doc/ref.sgml index a24ae22..89113a8 100644 --- a/doc/ref.sgml +++ b/doc/ref.sgml @@ -10,7 +10,7 @@ &clsql;. - + CLSQL-CONDITION the super-type of all @@ -22,7 +22,7 @@ Class Precedence List - maisql-condition + clsql-condition condition t @@ -37,7 +37,7 @@ initialization arguments nor any accessors. - + CLSQL-ERROR the super-type of all @@ -49,10 +49,10 @@ Class Precedence List - maisql-error + clsql-error error serious-condition - maisql-condition + clsql-condition condition t @@ -68,7 +68,7 @@ initialization arguments nor any accessors. - + CLSQL-SIMPLE-ERROR Unspecific simple @@ -79,12 +79,12 @@ Class Precedence List - maisql-simple-error + clsql-simple-error simple-condition - maisql-error + clsql-error error serious-condition - maisql-condition + clsql-condition condition t @@ -99,7 +99,7 @@ simple-condition. - + CLSQL-WARNING the super-type of all @@ -111,9 +111,9 @@ Class Precedence List - maisql-warning + clsql-warning warning - maisql-condition + clsql-condition condition t @@ -129,7 +129,7 @@ initialization arguments nor any accessors. - + CLSQL-SIMPLE-WARNING Unspecific simple @@ -140,11 +140,11 @@ Class Precedence List - maisql-simple-warning + clsql-simple-warning simple-condition - maisql-warning + clsql-warning warning - maisql-condition + clsql-condition condition t @@ -161,7 +161,7 @@ - + CLSQL-INVALID-SPEC-ERROR condition representing errors because of invalid @@ -172,11 +172,11 @@ Class Precedence List - maisql-invalid-spec-error - maisql-error + clsql-invalid-spec-error + clsql-error error serious-condition - maisql-condition + clsql-condition condition t @@ -195,24 +195,24 @@ Description :connection-spec - maisql-invalid-spec-error-connection-spec + clsql-invalid-spec-error-connection-spec The invalid connection specification used. :database-type - maisql-invalid-spec-error-database-type + clsql-invalid-spec-error-database-type The Database type used in the attempt. :template - maisql-invalid-spec-error-template + clsql-invalid-spec-error-template An argument describing the template that a valid connection specification must match for this database type. - + CLSQL-CONNECT-ERROR condition representing errors during @@ -223,11 +223,11 @@ Class Precedence List - maisql-connect-error - maisql-error + clsql-connect-error + clsql-error error serious-condition - maisql-condition + clsql-condition condition t @@ -244,32 +244,32 @@ Description :database-type - maisql-connect-error-database-type + clsql-connect-error-database-type Database type for the connection attempt :connection-spec - maisql-connect-error-connection-spec + clsql-connect-error-connection-spec The connection specification used in the connection attempt. :errno - maisql-connect-error-errno + clsql-connect-error-errno The numeric or symbolic error specification returned by the database back-end. The values and semantics of this are interface specific. :error - maisql-connect-error-error + clsql-connect-error-error A string describing the problem that occurred, possibly one returned by the database back-end. - + CLSQL-SQL-ERROR condition representing errors during query or @@ -280,11 +280,11 @@ Class Precedence List - maisql-sql-error - maisql-error + clsql-sql-error + clsql-error error serious-condition - maisql-condition + clsql-condition condition t @@ -303,32 +303,32 @@ Description :database - maisql-sql-error-database + clsql-sql-error-database The database object that was involved in the incident. :expression - maisql-sql-error-expression + clsql-sql-error-expression The SQL expression whose execution caused the error. :errno - maisql-sql-error-errno + clsql-sql-error-errno The numeric or symbolic error specification returned by the database back-end. The values and semantics of this are interface specific. :error - maisql-sql-error-error + clsql-sql-error-error A string describing the problem that occurred, possibly one returned by the database back-end. - + CLSQL-EXISTS-CONDITION condition indicating situations arising because of @@ -339,8 +339,8 @@ Class Precedence List - maisql-exists-condition - maisql-condition + clsql-exists-condition + clsql-condition condition t @@ -356,13 +356,13 @@ connect, either a warning, an error or no condition at all is signalled. If a warning or error is signalled, either - maisql-exists-warning or - maisql-exists-error is signalled, + clsql-exists-warning or + clsql-exists-error is signalled, which are subtypes of - maisql-exists-condition and - maisql-warning or - maisql-error. - maisql-exists-condition is never + clsql-exists-condition and + clsql-warning or + clsql-error. + clsql-exists-condition is never signalled itself. The following initialization arguments and accessors exist: @@ -372,13 +372,13 @@ Description :old-db - maisql-exists-condition-old-db + clsql-exists-condition-old-db The database object that represents the existing connection. This slot is always filled. :new-db - maisql-exists-condition-new-db + clsql-exists-condition-new-db The database object that will be used and returned by this call to connect, if execution continues normally. This can be either nil, indicating that @@ -392,7 +392,7 @@ - + CLSQL-EXISTS-WARNING condition representing warnings arising because of @@ -403,11 +403,11 @@ Class Precedence List - maisql-exists-warning - maisql-exists-condition - maisql-warning + clsql-exists-warning + clsql-exists-condition + clsql-warning warning - maisql-condition + clsql-condition condition t @@ -416,7 +416,7 @@ Description This condition is a subtype of - maisql-exists-condition, and is + clsql-exists-condition, and is signalled during calls to connect when there is an existing connection, and if-exists is either @@ -426,10 +426,10 @@ the existing old database object. The initialization arguments and accessors are the same as - for maisql-exists-condition. + for clsql-exists-condition. - + CLSQL-EXISTS-ERROR condition representing errors arising because of @@ -440,12 +440,12 @@ Class Precedence List - maisql-exists-error - maisql-exists-condition - maisql-error + clsql-exists-error + clsql-exists-condition + clsql-error error serious-condition - maisql-condition + clsql-condition condition t @@ -454,7 +454,7 @@ Description This condition is a subtype of - maisql-exists-condition, and is + clsql-exists-condition, and is signalled during calls to connect when there is an existing connection, and if-exists is :error. @@ -464,10 +464,10 @@ action in continuing from this correctable error. The initialization arguments and accessors are the same as - for maisql-exists-condition. + for clsql-exists-condition. - + CLSQL-CLOSED-ERROR condition representing errors because the database @@ -478,11 +478,11 @@ Class Precedence List - maisql-closed-error - maisql-error + clsql-closed-error + clsql-error error serious-condition - maisql-condition + clsql-condition condition t @@ -507,7 +507,7 @@ Description :database - maisql-closed-error-database + clsql-closed-error-database The database object that was involved in the incident. @@ -674,7 +674,7 @@ already present. If initialization fails, the function returns nil, and/or signals an error of type - maisql-error. The kind of action + clsql-error. The kind of action taken depends on the back-end and the cause of the problem. @@ -724,7 +724,7 @@ Exceptional Situations If an error is encountered during the initialization attempt, the back-end may signal errors of kind - maisql-error. + clsql-error. See Also @@ -1036,7 +1036,7 @@ disconnect. All functions and generic functions that take database objects as arguments will signal errors of type - maisql-closed-error when they are + clsql-closed-error when they are called on instances of closed-database, with the exception of database-name, which will continue to work as for instances of @@ -1208,7 +1208,7 @@ database. If it succeeds, it returns the first database found. If it fails to find a matching database, it will signal - an error of type maisql-error if + an error of type clsql-error if errorp is true. If errorp is nil, it will return nil instead. @@ -1258,7 +1258,7 @@ Exceptional Situations Will signal an error of type - maisql-error if no matching database + clsql-error if no matching database can be found, and errorp is true. Will signal an error if the value of database is neither an object of type @@ -1280,6 +1280,7 @@ None. + CONNECT @@ -1288,7 +1289,7 @@ Syntax - connect connection-spec &key if-exists database-type => database + connect connection-spec &key if-exists database-type pool => database Arguments and Values @@ -1316,6 +1317,14 @@ *default-database-type* + + pool + + A boolean flag. If &t;, acquire connection from a + pool of open connections. If the pool is empty, a new + connection is created. The default is &nil;. + + database @@ -1350,7 +1359,7 @@ This is just like :new, but also signals a warning of type - maisql-exists-warning, + clsql-exists-warning, indicating the old and newly created databases. @@ -1360,7 +1369,7 @@ This will cause connect to signal a correctable error of type - maisql-exists-error. The + clsql-exists-error. The user may choose to proceed, either by indicating that a new connection shall be created, via the restart create-new, or by @@ -1381,7 +1390,7 @@ This is just like :old, but also signals a warning of type - maisql-exists-warning, + clsql-exists-warning, indicating the old database used, via the slots old-db and new-db @@ -1448,11 +1457,11 @@ Exceptional Situations If the connection specification is not syntactically or semantically correct for the given database type, an error - of type maisql-invalid-spec-error is + of type clsql-invalid-spec-error is signalled. If during the connection attempt an error is detected (e.g. because of permission problems, network trouble or any other cause), an error of type - maisql-connect-error is + clsql-connect-error is signalled. If a connection to the database specified by connection-spec exists already, @@ -1474,6 +1483,7 @@ None. + DISCONNECT @@ -1482,11 +1492,21 @@ Syntax - disconnect &key database => t + disconnect &key database pool => t Arguments and Values + + pool + + A boolean flag indicating whether to put the database into a +pool of opened databases. If &t;, rather than terminating the database connection, the +connection is left open and the connection is placed into a pool of connections. Subsequent +calls to connect can then reuse this connection. +The default is &nil;. + + database @@ -1508,7 +1528,7 @@ with the exception of database-name. If the user does pass a closed database object to any other &clsql; function, an error of type - maisql-closed-error is + clsql-closed-error is signalled. @@ -1545,7 +1565,65 @@ Exceptional Situations If during the disconnection attempt an error is detected (e.g. because of network trouble or any other - cause), an error of type maisql-error + cause), an error of type clsql-error + might be signalled. + + + See Also + + + connect + closed-database + + + + + Notes + None. + + + + + + DISCONNECT-POOLED + closes all pooled database connections + Function + + + Syntax + disconnect-pool => t + + + Description + This function disconnects all database connections + that have been placed into the pool. Connections are placed + in the pool by calling + disconnection. + + + Examples + +(disconnect-pool) +=> T + + + + Side Effects + Database connections will be closed and entries in the pool are removed. + + + Affected by + + + disconnect + + + + + Exceptional Situations + If during the disconnection attempt an error is + detected (e.g. because of network trouble or any other + cause), an error of type clsql-error might be signalled. @@ -1562,6 +1640,7 @@ None. + DATABASE-NAME-FROM-SPEC @@ -1654,7 +1733,7 @@ If the value of connection-spec is not a valid connection specification for the given database type, an error of type - maisql-invalid-spec-error might be + clsql-invalid-spec-error might be signalled. @@ -1710,7 +1789,7 @@ sql-expression in the database specified. If the execution succeeds it will return t, otherwise an - error of type maisql-sql-error will + error of type clsql-sql-error will be signalled. @@ -1756,7 +1835,7 @@ Exceptional Situations If the execution of the SQL statement leads to any errors, an error of type - maisql-sql-error is signalled. + clsql-sql-error is signalled. See Also @@ -1863,7 +1942,7 @@ database specified. If the execution succeeds it will return the result set returned by the database, otherwise an error of type - maisql-sql-error will + clsql-sql-error will be signalled. @@ -1906,7 +1985,7 @@ Exceptional Situations If the execution of the SQL query leads to any errors, an error of type - maisql-sql-error is signalled. + clsql-sql-error is signalled. See Also @@ -2067,7 +2146,7 @@ Exceptional Situations If the execution of the SQL query leads to any errors, an error of type - maisql-sql-error is signalled. + clsql-sql-error is signalled. An error of type type-error must be signaled if the output-type-spec is not a recognizable subtype of list, not a @@ -2201,7 +2280,7 @@ Exceptional Situations If the execution of the SQL query leads to any errors, an error of type - maisql-sql-error is signalled. + clsql-sql-error is signalled. If the number of variable names in args and the number of attributes in the tuples in the result set don't match up, an error is @@ -2338,7 +2417,7 @@ Exceptional Situations If the execution of the SQL query leads to any errors, an error of type - maisql-sql-error is signalled. + clsql-sql-error is signalled. Otherwise, any of the exceptional situations of loop applies. @@ -2416,7 +2495,7 @@ initialization by returning t from their method, and nil otherwise. Methods for this generic function are allowed to signal errors of type - maisql-error or subtypes thereof. + clsql-error or subtypes thereof. They may also signal other types of conditions, if appropriate, but have to document this. @@ -2435,7 +2514,7 @@ Exceptional Situations - Conditions of type maisql-error + Conditions of type clsql-error or other conditions may be signalled, depending on the database back-end.