File 0399-odbc-Add-missing-API-specs.patch of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0399-odbc-Add-missing-API-specs.patch of Package erlang (Revision 8f70100112790b2ecaef2042dd03930d)

Currently displaying revision 8f70100112790b2ecaef2042dd03930d , Show latest

From 1fe33fda0d9c11cd4efd3944cda2d47c313707b5 Mon Sep 17 00:00:00 2001
From: Ingela Anderton Andin <ingela@erlang.org>
Date: Wed, 10 Jan 2024 11:17:52 +0100
Subject: [PATCH] odbc: Add missing API specs

---
 lib/odbc/doc/specs/.gitignore |   1 +
 lib/odbc/doc/src/Makefile     |   4 +
 lib/odbc/doc/src/odbc.xml     | 369 ++++++++++++++--------------------
 lib/odbc/doc/src/specs.xml    |   4 +
 lib/odbc/src/odbc.erl         | 288 +++++++++++++++++++-------
 5 files changed, 379 insertions(+), 287 deletions(-)
 create mode 100644 lib/odbc/doc/specs/.gitignore
 create mode 100644 lib/odbc/doc/src/specs.xml

diff --git a/lib/odbc/doc/specs/.gitignore b/lib/odbc/doc/specs/.gitignore
new file mode 100644
index 0000000000..322eebcb06
--- /dev/null
+++ b/lib/odbc/doc/specs/.gitignore
@@ -0,0 +1 @@
+specs_*.xml
diff --git a/lib/odbc/doc/src/Makefile b/lib/odbc/doc/src/Makefile
index 4fbe4acdb0..7b9b226dbd 100644
--- a/lib/odbc/doc/src/Makefile
+++ b/lib/odbc/doc/src/Makefile
@@ -52,6 +52,10 @@ BOOK_FILES = book.xml
 XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF3_FILES) \
 $(XML_PART_FILES) $(XML_CHAPTER_FILES)
 
+SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml)
+
+TOP_SPECS_FILE = specs.xml
+
 IMAGE_FILES = \
 	odbc_app_arc.gif
 
diff --git a/lib/odbc/doc/src/odbc.xml b/lib/odbc/doc/src/odbc.xml
index 28d4334fdf..141fc44829 100644
--- a/lib/odbc/doc/src/odbc.xml
+++ b/lib/odbc/doc/src/odbc.xml
@@ -55,73 +55,92 @@
 </note>
 </description>
 
- <section>
- <title>COMMON DATA TYPES </title>
- Here follows type definitions that are used by more than one
- function in the ODBC API. 
- <note>
- The type <c>TimeOut</c> has the default value
- <c>infinity</c>, so for instance: 
+ 
 
- commit(Ref, CommitMode) is the same as
- commit(Ref, CommitMode, infinity). If the
- timeout expires the client will exit with the reason
- timeout. 
- </note>
- <code type="none">
- connection_reference() - as returned by connect/2 </code>
- <code type="none">
- time_out() = milliseconds() | infinity </code>
- <code type="none">
- milliseconds() = integer() >= 0 </code>
- <code type="none">
- common_reason() = connection_closed | extended_error() | term() - some kind of
- explanation of what went wrong </code>
- <code type="none">
- extended_error() = {string(), integer(), Reason} - extended error type with ODBC
- and native database error codes, as well as the base reason that would have been
- returned had extended_errors not been enabled. </code>
- <code type="none">
- string() = list of ASCII characters </code>
- <code type="none">
- col_name() = string() - Name of column in the result set </code>
- <code type="none">
- col_names() - [col_name()] - e.g. a list of the names of the
- selected columns in the result set. </code>
- <code type="none">
- row() = {value()} - Tuple of column values e.g. one row of the
- result set. </code>
- <code type="none">
- value() = null | term() - A column value. </code>
- <code type="none">
- rows() = [row()] - A list of rows from the result set. </code>
- <code type="none">
- result_tuple() =
- {updated, n_rows()} | {selected, col_names(), rows()} </code>
- <code type="none">
- n_rows() = integer() - The number of affected rows for UPDATE,
- INSERT, or DELETE queries. For other query types the value
- is driver defined, and hence should be ignored. </code>
- <code type="none">
- odbc_data_type() = sql_integer | sql_smallint | sql_tinyint |
- {sql_decimal, precision(), scale()} |
- {sql_numeric, precision(), scale()} |
- {sql_char, size()} |
- {sql_wchar, size()} |
- {sql_varchar, size()} |
- {sql_wvarchar, size()}|
- {sql_float, precision()} |
- {sql_wlongvarchar, size()} |
- {sql_float, precision()} |
- sql_real | sql_double | sql_bit | atom()
- </code>
- <code type="none">
- precision() = integer() </code>
- <code type="none">
- scale() = integer() </code>
- <code type="none">
- size() = integer() </code>
- </section>
+ <datatypes>
+ <datatype_title>Types used in ODBC application</datatype_title>
+
+ <datatype> 
+ <name name="connection_reference"/>
+ <desc>
+	Opaque reference to an ODBC connection as returnded by connect/2.
+ </desc>
+ </datatype>
+
+ <datatype>
+ <name name="col_name"/>
+ <desc>
+	 Name of column in the result set.
+ </desc>
+ </datatype>
+
+ <datatype>
+	 <name name="row"/>
+	 <desc>
+	 A tuple, with the number of elements selected form columns in a database row, containg the values of the columns
+	 such as <c>{value(), value() ... value()} </c>.
+	 
+	 </desc>
+	</datatype>
+
+	<datatype>
+ <name name="value"/>
+ <desc>
+ Erlang data type that corresponds to the ODBC data type being handled.
+ </desc>
+ </datatype>
+	
+	<datatype>
+	 <name name="selected"/>
+	 <desc>
+	 Return value for queries that select data from database tabels.
+	 </desc>
+	</datatype>
+	
+	 <datatype>
+	 <name name="updated"/>
+	 <desc>
+		Return value for queries that update database tables.
+	 </desc>
+	 </datatype>
+
+	 <datatype>
+	 <name name="n_rows"/>
+	 <desc>
+		 The number of affected rows for UPDATE,
+		 INSERT, or DELETE queries. For other query types the value
+		 is driver defined, and hence should be ignored. 
+		</desc>
+	 </datatype>
+
+	 <datatype>
+	 <name name="odbc_data_type"/>
+	 <desc>
+		 Data type used by ODBC, to learn which Erlang data type
+		corresponds to an ODBC data type see the Erlang to ODBC
+		data type <seeguide marker="databases#type">mapping</seeguide> in the User's Guide.
+	 </desc>
+	 </datatype>
+
+	 <datatype>
+	 <name name="common_reason"/>
+	 <desc>
+		 An explanation of what went wrong. For common errors there will be atom decriptions.
+	 </desc>
+	 </datatype>
+
+	 <datatype>
+	 <name name="extended_error"/>
+	 <desc>
+		extended error type with ODBC and native database error codes, as well as the base reason that would have been
+		returned had extended_errors not been enabled.
+	 </desc>
+	 </datatype>
+ </datatypes>
 
 <section>
 <title>ERROR HANDLING </title>
@@ -130,34 +149,17 @@
 </section>
 <funcs>
 <func>
- <name since="">commit(Ref, CommitMode) -></name>
- <name since="">commit(Ref, CommitMode, TimeOut) -> ok | {error, Reason} </name>
+ <name since="" name="commit" arity="2"></name>
+ <name since="" name="commit" arity="3"></name>
 <fsummary>Commits or rollbacks a transaction. </fsummary>
- <type>
- <v>Ref = connection_reference() </v>
- <v>CommitMode = commit | rollback</v>
- <v>TimeOut = time_out()</v>
- <v>Reason = not_an_explicit_commit_connection | process_not_owner_of_odbc_connection | common_reason()</v>
- </type>
 <desc>
 Commits or rollbacks a transaction. Needed on connections
 where automatic commit is turned off.
 </desc>
 </func>
 <func>
- <name since="">connect(ConnectStr, Options) -> {ok, Ref} | {error, Reason} </name>
+ <name since="" name="connect" arity="2"></name>
 <fsummary>Opens a connection to the database. </fsummary>
- <type>
- <v>ConnectStr = string()</v>
- <d>An example of a connection string: <c>"DSN=sql-server;UID=aladdin;PWD=sesame"</c> where DSN is your ODBC Data Source Name, UID is a database user id and PWD is the password for that user. These are usually the attributes required in the connection string, but some drivers have other driver specific attributes, for example <c>"DSN=Oracle8;DBQ=gandalf;UID=aladdin;PWD=sesame"</c> where DBQ is your TNSNAMES.ORA entry name e.g. some Oracle specific configuration attribute.</d>
- <v>Options = [] | [option()]</v>
- <d>All options has default values. </d>
- <v>option() = {auto_commit, on | off} | {timeout, milliseconds()}
-	| {binary_strings, on | off} | {tuple_row, on | off} | {scrollable_cursors, on | off} |
-	{trace_driver, on | off} | {extended_errors, on | off} </v>
- <v>Ref = connection_reference() - should be used to access the connection. </v>
- <v>Reason = port_program_executable_not_found | common_reason()</v>
- </type>
 <desc>
 Opens a connection to the database. The connection is
 associated with the process that created it and can only be
@@ -175,7 +177,7 @@
 
 	 The default timeout is infinity 
 	 
-	 >If the option binary_strings is turned on all strings
+	 If the option binary_strings is turned on all strings
 	 will be returned as binaries and strings inputted to
 	 param_query will be expected to be binaries. The user needs
 	 to ensure that the binary is in an encoding that the
@@ -208,20 +210,23 @@
 description of the function SQLDriverConnect in [1].
 </note>
 
-		 The <c>extended_errors</c> option enables extended ODBC error
-			 information when an operation fails. Rather than returning <c>{error, Reason}</c>,
-			 the failing function will return <c>{error, {ODBCErrorCode, NativeErrorCode, Reason}}</c>.
-			 Note that this information is probably of little use when writing database-independent code,
-			 but can be of assistance in providing more sophisticated error handling when dealing with
-			 a known underlying database.
-	 
-			 <list type="bulleted">
-				 <item><c>ODBCErrorCode</c> is the ODBC error string returned by the ODBC driver.</item>
-				 <item><c>NativeErrorCode</c> is the numeric error code returned by the underlying database. The possible values
-					 and their meanings are dependent on the database being used.</item>
-				 <item><c>Reason</c> is as per the <c>Reason</c> field when extended errors are not enabled.</item>
-		 </list>
-
+	The <c>extended_errors</c> option enables extended ODBC
+	error information when an operation fails. Rather than
+	returning <c>{error, Reason}</c>, the failing function will
+	return <c>{error, {ODBCErrorCode, NativeErrorCode,
+	Reason}}</c>. Note that this information is probably of
+	little use when writing database-independent code, but can be
+	of assistance in providing more sophisticated error handling
+	when dealing with a known underlying database.
+	
+	<list type="bulleted">
+	 <item><c>ODBCErrorCode</c> is the ODBC error string returned
+	 by the ODBC driver.</item>
+	 <item><c>NativeErrorCode</c> is the numeric error code returned by the underlying database. The possible values
+	 and their meanings are dependent on the database being used.</item>
+	 <item><c>Reason</c> is as per the <c>Reason</c> field when extended errors are not enabled.</item>
+	</list>
+	
 <note>
 The current implementation spawns a port program
 written in C that utilizes the actual ODBC driver. There
@@ -236,83 +241,50 @@
 </desc>
 </func>
 <func>
- <name since="">disconnect(Ref) -> ok | {error, Reason} </name>
+ <name since="" name="disconnect" arity="1"></name>
 <fsummary>Closes a connection to a database. </fsummary>
- <type>
- <v>Ref = connection_reference()</v>
- <v>Reason = process_not_owner_of_odbc_connection | extended_error()</v>
- </type>
 <desc>
- Closes a connection to a database. This will also
- terminate all processes that may have been spawned 
- when the connection was opened. This call will always succeed.
- If the connection cannot be disconnected gracefully it will
- be brutally killed. However you may receive an error message
- as result if you try to disconnect a connection started by another
- process.
- <marker id="describe_table"></marker>
-
+ Closes a connection to a database. This will also terminate
+ all processes that may have been spawned when the connection
+ was opened. This call will always succeed. If the connection
+ cannot be disconnected gracefully it will be brutally
+ killed. However you may receive an error message as result if
+ you try to disconnect a connection started by another process.
+ <marker id="describe_table"></marker>
+	
 </desc>
 </func>
 <func>
- <name since="">describe_table(Ref, Table) -> </name>
- <name since="">describe_table(Ref, Table, Timeout) -> {ok, Description} | {error, Reason} </name>
+ <name since="" name="describe_table" arity="2"></name>
+ <name since="" name="describe_table" arity="3"></name>
 <fsummary>Queries the database to find out the data types of the columns of the table <c>Table</c>. </fsummary>
- <type>
- <v>Ref = connection_reference()</v>
- <v>Table = string() - Name of database table.</v>
- <v>TimeOut = time_out()</v>
- <v>Description = [{col_name(), odbc_data_type()}]</v>
- <v>Reason = common_reason()</v>
- </type>
 <desc>
 Queries the database to find out the ODBC data types of the
 columns of the table <c>Table</c>. 
 </desc>
 </func>
 <func>
- <name since="">first(Ref) -></name>
- <name since="">first(Ref, Timeout) -> {selected, ColNames, Rows} | {error, Reason} </name>
+ <name since="" name="first" arity="1"></name>
+ <name since="" name="first" arity="2"></name>
 <fsummary>Returns the first row of the result set and positions a cursor at this row.</fsummary>
- <type>
- <v>Ref = connection_reference()</v>
- <v>TimeOut = time_out()</v>
- <v>ColNames = col_names() </v>
- <v>Rows = rows()</v>
- <v>Reason = result_set_does_not_exist | driver_does_not_support_function | scrollable_cursors_disabled | process_not_owner_of_odbc_connection | common_reason() </v>
- </type>
 <desc>
 Returns the first row of the result set and positions a
 cursor at this row.
 </desc>
 </func>
 <func>
- <name since="">last(Ref) -></name>
- <name since="">last(Ref, TimeOut) -> {selected, ColNames, Rows} | {error, Reason} </name>
+ <name since="" name="last" arity="1"></name>
+ <name since="" name="last" arity="2"></name>
 <fsummary>Returns the last row of the result set and positions a cursor at this row. </fsummary>
- <type>
- <v>Ref = connection_reference()</v>
- <v>TimeOut = time_out()</v>
- <v>ColNames = col_names() </v>
- <v>Rows = rows()</v>
- <v>Reason = result_set_does_not_exist | driver_does_not_support_function | scrollable_cursors_disabled | process_not_owner_of_odbc_connection | common_reason() </v>
- </type>
 <desc>
 Returns the last row of the result set and positions a
 cursor at this row.
 </desc>
 </func>
 <func>
- <name since="">next(Ref) -> </name>
- <name since="">next(Ref, TimeOut) -> {selected, ColNames, Rows} | {error, Reason} </name>
+ <name since="" name="next" arity="1"></name>
+ <name since="" name="next" arity="2"></name>
 <fsummary>Returns the next row of the result set relative the current cursor position and positions the cursor at this row. </fsummary>
- <type>
- <v>Ref = connection_reference()</v>
- <v>TimeOut = time_out()</v>
- <v>ColNames = col_names() </v>
- <v>Rows = rows()</v>
- <v>Reason = result_set_does_not_exist | process_not_owner_of_odbc_connection | common_reason() </v>
- </type>
 <desc>
 Returns the next row of the result set relative the
 current cursor position and positions the cursor at this
@@ -321,22 +293,13 @@
 will be <c>{selected, ColNames,[]}</c> e.i. the list of row
 values is empty indicating that there is no more data to fetch.
 <marker id="param_query"></marker>
-
+	
 </desc>
 </func>
 <func>
- <name since="">param_query(Ref, SQLQuery, Params) -> </name>
- <name since="">param_query(Ref, SQLQuery, Params, TimeOut) -> ResultTuple | {error, Reason} </name>
+ <name since="" name="param_query" arity="3"></name>
+ <name since="" name="param_query" arity="4"></name>
 <fsummary>Executes a parameterized SQL query.</fsummary>
- <type>
- <v>Ref = connection_reference()</v>
- <v>SQLQuery = string() - a SQL query with parameter markers/place holders in form of question marks.</v>
- <v>Params = [{odbc_data_type(), [value()]}] |[{odbc_data_type(), in_or_out(), [value()]}] </v>
-	<v>in_or_out = in | out | inout</v>
-	<d>Defines IN, OUT, and IN OUT Parameter Modes for stored procedures.</d>
-	<v>TimeOut = time_out()</v>
- <v>Values = term() - Must be consistent with the Erlang data type that corresponds to the ODBC data type ODBCDataType</v>
- </type>
 <desc>
 Executes a parameterized SQL query. For an
 example see the <seeguide marker="getting_started#param_query">"Using the Erlang API"</seeguide> in the Erlang ODBC 
@@ -346,23 +309,18 @@
 ODBC data type that is expected for each column of that
 table. If a column has a data type that is described with
 capital letters, alas it is not currently supported by the
- param_query function. Too know which Erlang data type
+ param_query function. To learn which Erlang data type
 corresponds to an ODBC data type see the Erlang to ODBC
 data type <seeguide marker="databases#type">mapping</seeguide> in the User's Guide.
 </note>
 </desc>
 </func>
 <func>
- <name since="">prev(Ref) -> </name>
- <name since="">prev(ConnectionReference, TimeOut) -> {selected, ColNames, Rows} | {error, Reason} </name>
- <fsummary>Returns the previous row of the result set relative the current cursor position and positions the cursor at this row. </fsummary>
- <type>
- <v>Ref = connection_reference()</v>
- <v>TimeOut = time_out()</v>
- <v>ColNames = col_names() </v>
- <v>Rows = rows()</v>
- <v>Reason = result_set_does_not_exist | driver_does_not_support_function | scrollable_cursors_disabled | process_not_owner_of_odbc_connection | common_reason() </v>
- </type>
+ <name since="" name="prev" arity="1"></name>
+ <name since="" name="prev" arity="2"></name>
+ <fsummary>Returns the previous row of the result set relative
+ the current cursor position and positions the cursor at this
+ row. </fsummary>
 <desc>
 Returns the previous row of the result set relative the
 current cursor position and positions the
@@ -371,15 +329,9 @@
 </func>
 
 <func>
- <name since="">start() -> </name>
- <name since="">start(Type) -> ok | {error, Reason}</name>
- <fsummary>Starts the odb application. </fsummary>
- 
- <type>
-	<v>Type = permanent | transient | temporary
-	</v>
- </type>
- 
+ <name since="" name="start" arity="0"></name>
+ <name since="" name="start" arity="1"></name>
+ <fsummary>Starts the odb application. </fsummary> 
 <desc>
 	 Starts the odbc application. Default type
 	 is temporary.
@@ -389,7 +341,7 @@
 </func>
 
 <func>
- <name since="">stop() -> ok </name>
+ <name since="" name="stop" arity="0"></name>
 <fsummary> Stops the odbc application.</fsummary>
 
 <desc>
@@ -400,16 +352,14 @@
 </func>
 
 <func>
- <name since="">sql_query(Ref, SQLQuery) -> </name>
- <name since="">sql_query(Ref, SQLQuery, TimeOut) -> ResultTuple | [ResultTuple] |{error, Reason}</name>
- <fsummary>Executes a SQL query or a batch of SQL queries. If it is a SELECT query the result set is returned, on the format<c>{selected, ColNames, Rows}</c>. For other query types the tuple <c>{updated, NRows}</c>is returned, and for batched queries, if the driver supports them, this function can also return a list of result tuples.</fsummary>
- <type>
- <v>Ref = connection_reference()</v>
- <v>SQLQuery = string() - The string may be composed by several SQL-queries separated by a ";", this is called a batch. </v>
- <v>TimeOut = time_out()</v>
- <v>ResultTuple = result_tuple() </v>
- <v>Reason = process_not_owner_of_odbc_connection | common_reason() </v>
- </type>
+ <name since="" name="sql_query" arity="2"></name>
+ <name since="" name="sql_query" arity="3"></name>
+ <fsummary>Executes a SQL query or a batch of SQL queries. If it
+ is a SELECT query the result set is returned, on the
+ format<c>{selected, ColNames, Rows}</c>. For other query types
+ the tuple <c>{updated, NRows}</c>is returned, and for batched
+ queries, if the driver supports them, this function can also
+ return a list of result tuples.</fsummary>
 <desc>
 Executes a SQL query or a batch of SQL queries. If it
 is a SELECT query the result set is returned, on the format
@@ -429,17 +379,12 @@
 </desc>
 </func>
 <func>
- <name since="">select_count(Ref, SelectQuery) -> </name>
- <name since="">select_count(Ref, SelectQuery, TimeOut) -> {ok, NrRows} | {error, Reason} </name>
- <fsummary>Executes a SQL SELECT query and associates the result set with the connection. A cursor is positioned before the first row in the result set and the tuple <c>{ok, NrRows}</c>is returned. </fsummary>
- <type>
- <v>Ref = connection_reference()</v>
- <v>SelectQuery = string()</v>
- <d>SQL SELECT query.</d>
- <v>TimeOut = time_out()</v>
- <v>NrRows = n_rows()</v>
- <v>Reason = process_not_owner_of_odbc_connection | common_reason() </v>
- </type>
+ <name since="" name="select_count" arity="2"></name>
+ <name since="" name="select_count" arity="3"></name>
+ <fsummary>Executes a SQL SELECT query and associates the result
+ set with the connection. A cursor is positioned before the first
+ row in the result set and the tuple <c>{ok, NrRows}</c>is
+ returned. </fsummary>
 <desc>
 Executes a SQL SELECT query and associates the result set
 with the connection. A cursor is positioned before the first
@@ -453,19 +398,9 @@
 </desc>
 </func>
 <func>
- <name since="">select(Ref, Position, N) -></name>
- <name since="">select(Ref, Position, N, TimeOut) -> {selected, ColNames, Rows} | {error, Reason} </name>
+ <name since="" name="select" arity="3"></name>
+ <name since="" name="select" arity="4"></name>
 <fsummary>Selects <c>N</c>consecutive rows of the result set.</fsummary>
- <type>
- <v>Ref = connection_reference()</v>
- <v>Position = next | {relative, Pos} | {absolute, Pos} </v>
- <d>Selection strategy, determines at which row in the result set to start the selection.</d>
- <v>Pos = integer() </v>
- <d>Should indicate a row number in the result set. When used together with the option <c>relative</c>it will be used as an offset from the current cursor position, when used together with the option <c>absolute</c>it will be interpreted as a row number.</d>
- <v>N = integer() </v>
- <v>TimeOut = time_out()</v>
- <v>Reason = result_set_does_not_exist | driver_does_not_support_function | scrollable_cursors_disabled | process_not_owner_of_odbc_connection | common_reason() </v>
- </type>
 <desc>
 Selects <c>N</c> consecutive rows of the result set. If
 <c>Position</c> is <c>next</c> it is semantically equivalent
diff --git a/lib/odbc/doc/src/specs.xml b/lib/odbc/doc/src/specs.xml
new file mode 100644
index 0000000000..6edc72556e
--- /dev/null
+++ b/lib/odbc/doc/src/specs.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<specs xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:include href="../specs/specs_odbc.xml"/>
+</specs>
diff --git a/lib/odbc/src/odbc.erl b/lib/odbc/src/odbc.erl
index 2431f5be1e..c597e21bd7 100644
--- a/lib/odbc/src/odbc.erl
+++ b/lib/odbc/src/odbc.erl
@@ -45,6 +45,36 @@
 -export([init/1, handle_call/3, handle_cast/2, handle_info/2, 
 	 terminate/2, code_change/3]).
 
+-opaque connection_reference() :: pid().
+-type col_name() :: string().
+-type row() :: tuple().
+-type value() :: null | term().
+-type selected() :: {selected, [col_name()], [row()]}.
+-type updated() :: {updated, n_rows()}.
+-type n_rows() :: integer().
+-type odbc_data_type() :: sql_integer | sql_smallint | sql_tinyint |
+ {sql_decimal, Precision::integer(), Scale::integer()} |
+ {sql_numeric, Precision::integer(), Scale::integer()} |
+ {sql_char, Size::integer()} |
+ {sql_wchar, Size::integer()} |
+ {sql_varchar, Size::integer()} |
+ {sql_wvarchar, Size::integer()}|
+ {sql_float, Precision::integer()} |
+ {sql_wlongvarchar, Size::integer()} |
+ {sql_float, Precision::integer()} |
+ sql_real | sql_double | sql_bit | atom().
+-type common_reason() :: connection_closed | extended_error() | term().
+-type extended_error() :: {string(), integer(), term()}.
+
+-export_type([connection_reference/0,
+ col_name/0, row/0,
+ selected/0,
+ updated/0,
+ n_rows/0,
+ odbc_data_type/0,
+ common_reason/0,
+ extended_error/0]).
+
 %%--------------------------------------------------------------------------
 %% Internal state
 -record(state, {erlang_port, % The port to the c-program
@@ -75,23 +105,26 @@
 %%% API
 %%%=========================================================================
 
+%%--------------------------------------------------------------------
+-spec start() -> ok | {error, Reason} when
+ Reason ::term().
+%%--------------------------------------------------------------------
+start() ->
+ application:start(odbc).
 
 %%--------------------------------------------------------------------
-%% Function: start([, Type]) -> ok
-%%
-%% Type = permanent | transient | temporary
+-spec start(Type) -> ok | {error, Reason} when
+ Type :: permanent | transient | temporary,
+ Reason ::term().
 %%
 %% Description: Starts the inets application. Default type
 %% is temporary. see application(3)
 %%--------------------------------------------------------------------
-start() -> 
- application:start(odbc).
-
 start(Type) -> 
 application:start(odbc, Type).
 
 %%--------------------------------------------------------------------
-%% Function: stop() -> ok
+-spec stop() -> ok.
 %%
 %% Description: Stops the odbc application.
 %%--------------------------------------------------------------------
@@ -99,8 +132,19 @@ stop() ->
 application:stop(odbc).
 
 %%-------------------------------------------------------------------------
-%% connect(ConnectionStr, Options) -> {ok, ConnectionReferense} |
-%% {error, Reason}
+-spec connect(ConnectionStr, Options) -> {ok, ConnectionReferense} |
+ {error, Reason} when
+ ConnectionStr :: string(),
+ Options :: [{auto_commit, on | off} |
+ {timeout, erlang:timeout()} |
+ {binary_strings, on | off} |
+ {tuple_row, on | off} |
+ {scrollable_cursors, on | off} |
+ {trace_driver, on | off} |
+ {extended_errors, on | off}],
+ ConnectionReferense :: connection_reference(),
+ Reason :: port_program_executable_not_found | common_reason().
+
 %% Description: Spawns an erlang control process that will open a port
 %% to a c-process that uses the ODBC API to open a connection
 %% to the database. 
@@ -119,7 +163,9 @@ connect(ConnectionStr, Options) when is_list(ConnectionStr), is_list(Options) ->
 end.
 
 %%--------------------------------------------------------------------------
-%% disconnect(ConnectionReferense) -> ok | {error, Reason}
+-spec disconnect(ConnectionReferense) -> ok | {error, Reason} when
+ ConnectionReferense :: connection_reference(),
+ Reason :: process_not_owner_of_odbc_connection | extended_error().
 %% 
 %% Description: Disconnects from the database and terminates both the erlang
 %% control process and the database handling c-process. 
@@ -144,14 +190,23 @@ disconnect(ConnectionReference) when is_pid(ConnectionReference)->
 end. 
 	 
 %%--------------------------------------------------------------------------
-%% commit(ConnectionReference, CommitMode, <TimeOut>) -> ok | {error,Reason}
-%% 
-%% Description: Commits or rollbacks a transaction. Needed on connections
-%% where automatic commit is turned off. 
+-spec commit(ConnectionReference, CommitMode) -> ok | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ CommitMode :: commit | rollback,
+ Reason :: not_an_explicit_commit_connection |
+ process_not_owner_of_odbc_connection | common_reason().
 %%--------------------------------------------------------------------------
 commit(ConnectionReference, CommitMode) ->
 commit(ConnectionReference, CommitMode, ?DEFAULT_TIMEOUT).
 
+%%--------------------------------------------------------------------------
+-spec commit(ConnectionReference, CommitMode, TimeOut) -> ok | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ CommitMode :: commit | rollback,
+ TimeOut :: erlang:timeout(),
+ Reason :: not_an_explicit_commit_connection |
+ process_not_owner_of_odbc_connection | common_reason().
+%%--------------------------------------------------------------------------
 commit(ConnectionReference, commit, infinity) 
 when is_pid(ConnectionReference) ->
 ODBCCmd = [?COMMIT_TRANSACTION, ?COMMIT],
@@ -173,16 +228,25 @@ commit(ConnectionReference, rollback, TimeOut)
 call(ConnectionReference, {commit, ODBCCmd}, TimeOut).
 
 %%--------------------------------------------------------------------------
-%% sql_query(ConnectionReference, SQLQuery, <TimeOut>) -> {updated, NRows} |
-%%			 {selected, ColNames, Rows} | {error, Reason} 
+-spec sql_query(ConnectionReference, SQLQuery) -> Result | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ SQLQuery :: string(),
+ Result :: updated() | selected(),
+ Reason :: process_not_owner_of_odbc_connection | common_reason().
 %% 
-%% Description: Executes a SQL query. If it is a SELECT query the
-%% result set is returned, otherwise the number of affected 
-%% 	rows are returned.
 %%--------------------------------------------------------------------------
 sql_query(ConnectionReference, SQLQuery) ->
 sql_query(ConnectionReference, SQLQuery, ?DEFAULT_TIMEOUT).
 
+%%--------------------------------------------------------------------------
+-spec sql_query(ConnectionReference, SQLQuery, TimeOut) -> Result | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ SQLQuery :: string(),
+ TimeOut :: erlang:timeout(),
+ Result :: updated() | selected(),
+ Reason :: process_not_owner_of_odbc_connection | common_reason().
+%%
+%%--------------------------------------------------------------------------
 sql_query(ConnectionReference, SQLQuery, infinity) when 
 is_pid(ConnectionReference), is_list(SQLQuery) -> 
 ODBCCmd = [?QUERY, SQLQuery],
@@ -194,17 +258,27 @@ sql_query(ConnectionReference, SQLQuery, TimeOut)
 call(ConnectionReference, {sql_query, ODBCCmd}, TimeOut).
 
 %%--------------------------------------------------------------------------
-%% select_count(ConnectionReference, SQLQuery, <TimeOut>) -> {ok, NrRows} |
-%%							 {error, Reason} 
+-spec select_count(ConnectionReference, SQLQuery) -> {ok, NrRows} |
+ {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ SQLQuery :: string(),
+ NrRows :: n_rows(),
+ Reason :: process_not_owner_of_odbc_connection | common_reason().
 %% 
-%% Description: Executes a SQL SELECT query and associates the result set
-%% with the connection. A cursor is positioned before
-%% 	the first row in the result set and the number of
-%%	 rows in the result set is returned.
 %%--------------------------------------------------------------------------
 select_count(ConnectionReference, SQLQuery) ->	
 select_count(ConnectionReference, SQLQuery, ?DEFAULT_TIMEOUT).
 
+%%--------------------------------------------------------------------------
+-spec select_count(ConnectionReference, SQLQuery, TimeOut) -> {ok, NrRows} |
+ {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ SQLQuery :: string(),
+ TimeOut :: erlang:timeout(),
+ NrRows :: n_rows(),
+ Reason :: process_not_owner_of_odbc_connection | common_reason().
+%%
+%%--------------------------------------------------------------------------
 select_count(ConnectionReference, SQLQuery, infinity) when 
 is_pid(ConnectionReference), is_list(SQLQuery) ->
 ODBCCmd = [?SELECT_COUNT, SQLQuery],
@@ -216,15 +290,25 @@ select_count(ConnectionReference, SQLQuery, TimeOut) when
 call(ConnectionReference, {select_count, ODBCCmd}, TimeOut).
 
 %%--------------------------------------------------------------------------
-%% first(ConnectionReference, <TimeOut>) -> {selected, ColNames, Rows} | 
-%%					 {error, Reason} 
-%% 
-%% Description: Selects the first row in the current result set. The cursor
-%% : is positioned at this row. 
+-spec first(ConnectionReference) -> Result | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ Result :: selected(),
+ Reason :: result_set_does_not_exist | driver_does_not_support_function |
+ scrollable_cursors_disabled | process_not_owner_of_odbc_connection |
+ common_reason().
 %%--------------------------------------------------------------------------
 first(ConnectionReference) ->	
 first(ConnectionReference, ?DEFAULT_TIMEOUT).	
 
+%%--------------------------------------------------------------------------
+-spec first(ConnectionReference, TimeOut) -> Result | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ TimeOut :: erlang:timeout(),
+ Result :: selected(),
+ Reason :: result_set_does_not_exist | driver_does_not_support_function |
+ scrollable_cursors_disabled | process_not_owner_of_odbc_connection |
+ common_reason().
+%%--------------------------------------------------------------------------
 first(ConnectionReference, infinity) when is_pid(ConnectionReference) ->	
 ODBCCmd = [?SELECT, ?SELECT_FIRST],
 call(ConnectionReference, {select_cmd, absolute, ODBCCmd}, infinity);
@@ -235,15 +319,25 @@ first(ConnectionReference, TimeOut)
 call(ConnectionReference, {select_cmd, absolute, ODBCCmd}, TimeOut).
 
 %%--------------------------------------------------------------------------
-%% last(ConnectionReference, <TimeOut>) -> {selected, ColNames, Rows} | 
-%%					 {error, Reason} 
-%% 
-%% Description: Selects the last row in the current result set. The cursor
-%% : is positioned at this row. 
+-spec last(ConnectionReference) -> Result | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ Result :: selected(),
+ Reason :: result_set_does_not_exist | driver_does_not_support_function |
+ scrollable_cursors_disabled | process_not_owner_of_odbc_connection |
+ common_reason().
 %%--------------------------------------------------------------------------
 last(ConnectionReference) ->	
 last(ConnectionReference, ?DEFAULT_TIMEOUT).	
 
+%%--------------------------------------------------------------------------
+-spec last(ConnectionReference, TimeOut) -> Result | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ TimeOut :: erlang:timeout(),
+ Result :: selected(),
+ Reason :: result_set_does_not_exist | driver_does_not_support_function |
+ scrollable_cursors_disabled | process_not_owner_of_odbc_connection |
+ common_reason().
+%%--------------------------------------------------------------------------
 last(ConnectionReference, infinity) when is_pid(ConnectionReference) ->	
 ODBCCmd = [?SELECT, ?SELECT_LAST],
 call(ConnectionReference, {select_cmd, absolute, ODBCCmd}, infinity);
@@ -252,17 +346,27 @@ last(ConnectionReference, TimeOut)
 when is_pid(ConnectionReference), is_integer(TimeOut), TimeOut > 0 ->	
 ODBCCmd = [?SELECT, ?SELECT_LAST],
 call(ConnectionReference, {select_cmd, absolute, ODBCCmd}, TimeOut).
+
 %%--------------------------------------------------------------------------
-%% next(ConnectionReference, <TimeOut>) -> {selected, ColNames, Rows} | 
-%%					 {error, Reason} 
-%% 
-%% Description: Selects the next row relative the current cursor position 
-%% : in the current result set. The cursor is positioned at 
-%% : this row. 
+-spec next(ConnectionReference) -> Result | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ Result :: selected(),
+ Reason :: result_set_does_not_exist | driver_does_not_support_function |
+ scrollable_cursors_disabled | process_not_owner_of_odbc_connection |
+ common_reason().
 %%--------------------------------------------------------------------------
 next(ConnectionReference) ->	
 next(ConnectionReference, ?DEFAULT_TIMEOUT).	
- 
+
+%%--------------------------------------------------------------------------
+-spec next(ConnectionReference, TimeOut) -> Result | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ TimeOut :: erlang:timeout(),
+ Result :: selected(),
+ Reason :: result_set_does_not_exist | driver_does_not_support_function |
+ scrollable_cursors_disabled | process_not_owner_of_odbc_connection |
+ common_reason().
+%%--------------------------------------------------------------------------
 next(ConnectionReference, infinity) when is_pid(ConnectionReference) ->	
 ODBCCmd = [?SELECT, ?SELECT_NEXT],
 call(ConnectionReference, {select_cmd, next, ODBCCmd}, infinity);
@@ -273,16 +377,25 @@ next(ConnectionReference, TimeOut)
 call(ConnectionReference, {select_cmd, next, ODBCCmd}, TimeOut).
 
 %%--------------------------------------------------------------------------
-%% prev(ConnectionReference, <TimeOut>) -> {selected, ColNames, Rows} | 
-%%					 {error, Reason} 
-%% 
-%% Description: Selects the previous row relative the current cursor 
-%% : position in the current result set. The cursor is
-%% : positioned at this row. 
+-spec prev(ConnectionReference) -> Result | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ Result :: selected(),
+ Reason :: result_set_does_not_exist | driver_does_not_support_function |
+ scrollable_cursors_disabled | process_not_owner_of_odbc_connection |
+ common_reason().
 %%--------------------------------------------------------------------------
 prev(ConnectionReference) ->	
 prev(ConnectionReference, ?DEFAULT_TIMEOUT).	
 
+%%--------------------------------------------------------------------------
+-spec prev(ConnectionReference, TimeOut) -> Result | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ TimeOut :: erlang:timeout(),
+ Result :: selected(),
+ Reason :: result_set_does_not_exist | driver_does_not_support_function |
+ scrollable_cursors_disabled | process_not_owner_of_odbc_connection |
+ common_reason().
+%%--------------------------------------------------------------------------
 prev(ConnectionReference, infinity) when is_pid(ConnectionReference) ->	
 ODBCCmd = [?SELECT, ?SELECT_PREV],
 call(ConnectionReference, {select_cmd, relative, ODBCCmd}, infinity);
@@ -293,21 +406,29 @@ prev(ConnectionReference, TimeOut)
 call(ConnectionReference, {select_cmd, relative, ODBCCmd}, TimeOut).
 
 %%--------------------------------------------------------------------------
-%% select(ConnectionReference, <Timeout>) -> {selected, ColNames, Rows} | 
-%%					 {error, Reason} 
-%% 
-%% Description: Selects <N> rows. If <Position> is next it is
-%% semanticly eqvivivalent of calling next/[1,2] <N>
-%% times. If <Position> is {relative, Pos} <Pos> will be
-%% used as an offset from the current cursor position to
-%% determine the first selected row. If <Position> is
-%% {absolute, Pos}, <Pos> will be the number of the first
-%% row selected. After this function has returned the
-%% cursor is positioned at the last selected row.
+-spec select(ConnectionReference, Position, N) -> Result | {error, Reason} when
+ ConnectionReference ::connection_reference(),
+ Position :: next | {relative, integer()} | {absolute, integer()},
+ N :: integer(),
+ Result :: selected(),
+ Reason :: result_set_does_not_exist | driver_does_not_support_function
+ | scrollable_cursors_disabled | process_not_owner_of_odbc_connection |
+ common_reason().
 %%--------------------------------------------------------------------------
 select(ConnectionReference, Position, N) ->
 select(ConnectionReference, Position, N, ?DEFAULT_TIMEOUT).
 
+%%--------------------------------------------------------------------------
+-spec select(ConnectionReference, Position, N, TimeOut) -> Result | {error, Reason} when
+ ConnectionReference ::connection_reference(),
+ Position :: next | {relative, integer()} | {absolute, integer()},
+ N :: integer(),
+ TimeOut :: erlang:timeout(),
+ Result :: selected(),
+ Reason :: result_set_does_not_exist | driver_does_not_support_function
+ | scrollable_cursors_disabled | process_not_owner_of_odbc_connection |
+ common_reason().
+%%--------------------------------------------------------------------------
 select(ConnectionReference, next, N, infinity) 
 when is_pid(ConnectionReference), is_integer(N), N > 0 ->
 ODBCCmd = [?SELECT, ?SELECT_N_NEXT,
@@ -355,14 +476,31 @@ select(ConnectionReference, {absolute, Pos} , N, TimeOut)
 call(ConnectionReference, {select_cmd, absolute, ODBCCmd},
 	 TimeOut).
 %%--------------------------------------------------------------------------
-%% param_query(ConnectionReference, SQLQuery, Params, <TimeOut>) -> 
-%% ok | {error, Reason} 
-%% 
-%% Description: Executes a parameterized update/delete/insert-query. 
+-spec param_query(ConnectionReference, SQLQuery, Params) ->
+ Result | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ SQLQuery :: string(),
+ Params :: [{odbc_data_type(), [value()]}] |[{odbc_data_type(), in | out| inout, [value()]}],
+ Result :: selected() | updated(),
+ Reason :: driver_does_not_support_function |
+ process_not_owner_of_odbc_connection |
+ common_reason().
 %%--------------------------------------------------------------------------
 param_query(ConnectionReference, SQLQuery, Params) ->
 param_query(ConnectionReference, SQLQuery, Params, ?DEFAULT_TIMEOUT).
 
+%%--------------------------------------------------------------------------
+-spec param_query(ConnectionReference, SQLQuery, Params, TimeOut) ->
+ Result | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ SQLQuery :: string(),
+ Params :: [{odbc_data_type(), [value()]}] |[{odbc_data_type(), in | out| inout, [value()]}],
+ TimeOut :: erlang:timeout(),
+ Result :: selected() | updated(),
+ Reason :: driver_does_not_support_function |
+ process_not_owner_of_odbc_connection |
+ common_reason().
+%%--------------------------------------------------------------------------
 param_query(ConnectionReference, SQLQuery, Params, infinity) 
 when is_pid(ConnectionReference), is_list(SQLQuery), is_list(Params) ->
 Values = param_values(Params),
@@ -383,17 +521,27 @@ param_query(ConnectionReference, SQLQuery, Params, TimeOut)
 call(ConnectionReference, {param_query, ODBCCmd}, TimeOut).
 
 %%--------------------------------------------------------------------------
-%% describe_table(ConnectionReference, Table, <TimeOut>) -> {ok, Desc} 
-%%
-%% Desc - [{ColName, Datatype}]
-%% ColName - atom()
-%% Datatype - atom() 
-%% Description: Queries the database to find out the datatypes of the
-%% table <Table>
+-spec describe_table(ConnectionReference, Table) ->
+ {ok, Description} | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ Table :: string(),
+ Description :: [{col_name(), odbc_data_type()}],
+ Reason :: process_not_owner_of_odbc_connection | common_reason().
 %%--------------------------------------------------------------------------
+
 describe_table(ConnectionReference, Table) ->
 describe_table(ConnectionReference, Table, ?DEFAULT_TIMEOUT).
 
+%%--------------------------------------------------------------------------
+-spec describe_table(ConnectionReference, Table, TimeOut) ->
+ {ok, Description} | {error, Reason} when
+ ConnectionReference :: connection_reference(),
+ Table :: string(),
+ TimeOut :: erlang:timeout(),
+ Description :: [{col_name(), odbc_data_type()}],
+ Reason :: process_not_owner_of_odbc_connection | common_reason().
+%%--------------------------------------------------------------------------
+
 describe_table(ConnectionReference, Table, infinity) when 
 is_pid(ConnectionReference), is_list(Table) -> 
 ODBCCmd = [?DESCRIBE, "SELECT * FROM " ++ Table],
-- 
2.35.3

Places

File 0399-odbc-Add-missing-API-specs.patch of Package erlang (Revision 8f70100112790b2ecaef2042dd03930d)

Places