X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref.sgml;h=89113a8c0e4f86e9d33cb8b483c74e99d868c163;hb=fff83fbba112503ad015db50038c5628c88d4c99;hp=71d6da3a3afb6af0053ac3b702df619b4c6e4226;hpb=8213ff48f5362c3d4792444c929f50bd128bd044;p=clsql.git diff --git a/doc/ref.sgml b/doc/ref.sgml index 71d6da3..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,7 @@ 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. @@ -1562,6 +1582,65 @@ 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. + + + See Also + + + connect + closed-database + + + + + Notes + 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 @@ -1780,7 +1859,7 @@ Syntax - query query-expression &key database => result + query query-expression &key database types => result Arguments and Values @@ -1803,6 +1882,48 @@ of *default-database*. + + types + + A + field type + specififier. The default is &nil;. + + + The purpose of this argument is cause &clsql; to + import SQL numeric fields into numeric Lisp objects + rather than strings. This reduces the cost of + allocating a temporary string and the &clsql; users' + inconvenience of converting number strings into number + objects. + + + A value of :auto causes &clsql; + to automatically convert SQL fields into a + numeric format where applicable. The default value of + &nil; causes all fields to be returned as strings + regardless of the SQL type. Otherwise a list is expected + which has a element for each field that specifies the + conversion. If the list is shorter than the number + of fields, the a value of t is + assumed for the field. If the list is longer than + the number of fields, the extra elements are + ignored. + + :int Field is imported as a + signed integer, from 8-bits to 64-bits depending + upon the field type. + + :double Field is imported as a + double-float number. + + t Field is imported as a + string. + + + + + result @@ -1821,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. @@ -1864,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 @@ -1889,7 +2010,7 @@ Syntax - map-query output-type-spec function query-expression &key database => result + map-query output-type-spec function query-expression &key database types => result Arguments and Values @@ -1929,6 +2050,17 @@ of *default-database*. + + types + + + A field type specififier. + The default is &nil;. See query + for the semantics of this argument. + + + result @@ -1985,8 +2117,9 @@ (map-query '(vector double-float) #'(lambda (salary name) (declare (ignorable name)) - (coerce (read-from-string salary) 'double-float)) - "select salary,name from simple where salary > 8000") + (let ((*read-default-float-format* 'double-float)) + (coerce (read-from-string salary) 'double-float)) + "select salary,name from simple where salary > 8000")) => #(10000.0d0 8000.5d0) (type-of *) => (SIMPLE-ARRAY DOUBLE-FLOAT (2)) @@ -2013,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 @@ -2048,7 +2181,7 @@ Syntax - do-query ((&rest args) query-expression &key database) &body body => nil + do-query ((&rest args) query-expression &key database types) &body body => nil Arguments and Values @@ -2078,6 +2211,17 @@ *default-database*. + + types + + + A field type specififier. + The default is &nil;. See query + for the semantics of this argument. + + + body @@ -2136,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 @@ -2163,6 +2307,10 @@ query via a loop clause Loop Clause + + Compatibility + loop-for-as-tuples only works with &cmucl;. + Syntax var [type-spec] being {each | the} {record | records | tuple | tuples} {in | of} query [from database] @@ -2269,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. @@ -2289,6 +2437,7 @@ + <symbol>CLSQL-SYS</symbol> @@ -2297,11 +2446,6 @@ exported from CLSQL. These symbols are part of the interface for database back-ends, but not part of the normal user-interface of &clsql;. - - This part has only one demonstration entry, since the - rest still has to be written. In the meantime, use the - source to understand the database back-end interface. - @@ -2351,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. @@ -2370,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.