All the routines described here can be called from any host language
program that calls an SQL module or from any SQL precompiled
program. These routines cannot be called from an SQL module.
NOTE
SQL defines all routines in uppercase on OpenVMS.
Application programs must adhere to the rules about case-
sensitivity of the language compiler to ensure that the
programs call the routines correctly.
1 – sql_close_cursors
1.1 – Format
sql_close_cursors ()
1.2 – Returns
No value returned.
1.3 – Arguments
None.
1.4 – Description
The sql_close_cursors routine closes all open cursors.
1.5 – Related Routines
None.
2 – sql_deregister_error_handler
Deregisters an application's error handling routine
2.1 – Format
sql_deregister_error_handler ()
2.2 – Returns
No value returned.
2.3 – Arguments
None.
2.4 – Description
The sql_deregister_error_handler routine deregisters the
application's currently registered error handling routine.
When you deregister a routine, SQL discontinues using the
application's currently registered error handling routine. The
standard error handling mechanisms are always in effect.
2.5 – Related Routines
o sql_get_error_handler
o sql_register_error_handler
3 – sql_get_error_handler
Gets the address of the application's currently registered error
handling routine and the address of the user-specified data
3.1 – Format
sql_get_error_handler (user-error-routine, user-data)
3.2 – Returns
No value returned.
3.3 – Arguments
3.3.1 – user-error-routine
The address of an application's error handling routine
Value: Address of an application's error handling routine
Data type: Longword
Passing By reference
mechanism:
3.3.2 – user-data
The address of the user-specified data
Value: Address of the user-specified data
Data type: Longword
Passing By reference
mechanism:
3.4 – Description
The sql_get_error_handler routine gets the address of the
application's currently registered error handling routine and
the address of the user-specified data.
An application can use the sql_get_error_handler routine to
get the address of the currently registered routine and user-
specified data. The application can store the values in variables
for use later in the program.
3.5 – Related Routines
o sql_register_error_handler
o sql_deregister_error_handler
4 – sql$get_error_text
Passes error text with formatted ASCII output to programs for
processing
4.1 – Format
sql$get_error_text (buf [,errmsglen])
4.2 – Returns
The status code that results from the copy operation of the
vector's text to the user's buffer.
4.3 – Arguments
4.3.1 – buf
The buffer declared to receive the text
Value: Address of the buffer declared to receive the text
Data type: Character string
Passing By descriptor
mechanism:
4.3.2 – errmsglen
The number of characters allotted for the error messages to be
returned. This parameter is optional.
Value: Number of characters allotted for the error
messages
Data type: Word
Passing By reference
mechanism:
4.4 – Description
Use the sql$get_error_text routine when you want to pass error
text with formatted ASCII output (FAO) substitutions to your
program for processing.
To use the sql$get_error_text routine, you must include a buffer
(field) in your program declarations to receive the text SQL will
pass to it. Declare this field as a text string with a length
sufficient to accommodate the number of characters you expect
for the message associated with the RDB$LU_STATUS value and for
all follow-on messages. As an option, you can declare the buffer
length as a separate field (defined as a signed word).
4.5 – Related Routines
o sql_get_error_text
5 – sql_get_error_text
Passes error text with formatted ASCII output to programs for
processing.
5.1 – Format
sql_get_error_text (buf, len, errmsglen)
5.2 – Returns
The status code that results from the copy operation of the
vector's text to the user's buffer.
5.3 – Arguments
5.3.1 – buf
The buffer declared to receive the text.
Value: Address of the buffer declared to receive the text
Data type: Character string
Passing By reference
mechanism:
5.3.2 – len
The length of the buffer declared to receive the text.
Value: The length of the character string pointed to by
the first parameter
Data type: Longword
Passing By value
mechanism:
5.3.3 – errmsglen
The number of characters allotted for the error messages to be
returned.
Value: Number of characters allotted for the error
messages
Data type: Longword
Passing By reference
mechanism:
5.4 – Description
Use the sql_get_error_text routine when you want to pass error
text with formatted ASCII output (FAO) substitutions to your
program for processing.
To use the sql_get_error_text routine, you must include a buffer
(field) in your program declarations to receive the text SQL will
pass to it. Declare this field as a text string with a length
sufficient to accommodate the number of characters you expect for
the message associated with the RDB$LU_STATUS value and for all
follow-on messages.
5.5 – Related Routines
o sql$get_error_text
6 – sql_get_message_vector
Retrieves information from the message vector about the status of
the last SQL statement.
6.1 – Format
sql_get_message_vector (addr, index)
6.2 – Returns
No value returned.
6.3 – Arguments
6.3.1 – addr
Address of a variable into which the requested vector element
will be written.
Value: Address of the variable declared to receive the
vector element
Data type: longword (32 bit)
Passing By reference
mechanism:
6.3.2 – index
The index value of the vector element to return.
Value: A value greater than or equal to 1 and less than
or equal to 20
Data type: Unsigned longword
Passing By value
mechanism:
The following table shows the index values and how they map to
vector elements and the information contained in each vector
element.
Index
Value Information Returned
1 Number of arguments in the vector
2 Primary status code of the last SQL statement
3 Number of FAO arguments to primary message
4-20 Return status for follow-on messages, if any
6.4 – Description
Use the sql_get_message_vector routine to retrieve information
from the RDB$MESSAGE_VECTOR array. The array provides information
about the execution status of SQL statements. Index 2 of the sql_
get_message_vector routine returns the primary status code of
the last SQL statement. This index is comparable to the SQLCODE
status parameter.
The ANSI/ISO SQL standard does not include the sql_get_message_
vector routine or the RDB$MESSAGE_VECTOR array. For application
programs that comply with the standard, use the SQLCODE or
SQLSTATE status parameters. Furthermore, the status values
returned for a particular condition may change in future versions
of Oracle Rdb.
The status values that are stored in the message vector are
intended to be supplementary information to the status parameters
SQLCODE and SQLSTATE. Use the sql_get_message_vector routine if
the information provided by SQLCODE or SQLSTATE is ambiguous and
your application needs a more specific error code to handle the
error condition.
Relationship Between sql_message_vector and RDB$MESSAGE_VECTOR
shows the relationship between the indexes returned by sql_
message_vector and the fields in RDB$MESSAGE_VECTOR.
Table 1-1 Relationship Between sql_message_vector and
RDB$MESSAGE_VECTOR
sql_message_vector
Indexes RDB$MESSAGE_VECTOR Fields
Index 1 RDB$LU_NUM_ARGUMENTS
Index 2 RDB$LU_STATUS
Index 3 RDB$LU_ARGUMENTS
Index 4-20 Return status for follow-on messages,
if any
6.5 – Related Routines
None.
7 – sql_register_error_handler
Registers an application's error handling routines with the SQL
precompiler.
7.1 – Format
sql_register_error_handler (user-error-routine, user-data)
7.2 – Returns
No value returned.
7.3 – Arguments
7.3.1 – user-error-routine
The address of an application's error handling routine
Value: Address of an application's error handling routine
Data type: Address
Passing By value
mechanism:
7.3.2 – user-data
The address of the user-specified data
Value: Address of the user-specified data
Data type: Address
Passing By value
mechanism:
7.4 – Description
The sql_register_error_handler routine registers the
application's error handling routine with SQL. When SQL
determines that it will return a negative value for SQLCODE, SQL
calls the error handling routine that is currently registered.
The standard error handling routines are always in effect,
whether special error handling routines have been registered or
not. After the error handling routine executes, control returns
to SQL.
An application can contain and call more than one error handling
routine. However, only one routine can be active at a time.
An application can use the sql_get_error_handler routine to store
the address of a registered routine for use later in the program.
To deregister a routine, use the sql_deregister_error_handler
routine.
For information about declaring the error handling routines in
the supported programming languages, see the Oracle Rdb Guide to
SQL Programming.
7.5 – Related Routines
o sql_deregister_error_handler
o sql_get_error_handler
8 – sql_signal
8.1 – Format
sql_signal ()
8.2 – Returns
No value returned.
8.3 – Arguments
None.
8.4 – Description
The sql_signal routine signals to your program condition handler
an error that occurs on the execution of an SQL statement. If
your program does not contain a condition handler, the sql_
routine prints an error message and exits the program when an
error occurs.
If the host language compiler does not provide a signaling
mechanism, you must provide your own condition handler.
8.5 – Related Routines
None.