1 Routines 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. 2 sql_close_cursors 3 Format sql_close_cursors () 3 Returns No value returned. 3 Arguments None. 3 Description The sql_close_cursors routine closes all open cursors. 3 Related_Routines None. 2 sql_deregister_error_handler Deregisters an application's error handling routine 3 Format sql_deregister_error_handler () 3 Returns No value returned. 3 Arguments None. 3 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. 3 Related_Routines o sql_get_error_handler o sql_register_error_handler 2 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 Format sql_get_error_handler (user-error-routine, user-data) 3 Returns No value returned. 3 Arguments 4 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: 4 user-data The address of the user-specified data Value: Address of the user-specified data Data type: Longword Passing By reference mechanism: 3 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 Related_Routines o sql_register_error_handler o sql_deregister_error_handler 2 sql$get_error_text Passes error text with formatted ASCII output to programs for processing 3 Format sql$get_error_text (buf [,errmsglen]) 3 Returns The status code that results from the copy operation of the vector's text to the user's buffer. 3 Arguments 4 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 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: 3 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). 3 Related_Routines o sql_get_error_text 2 sql_get_error_text Passes error text with formatted ASCII output to programs for processing. 3 Format sql_get_error_text (buf, len, errmsglen) 3 Returns The status code that results from the copy operation of the vector's text to the user's buffer. 3 Arguments 4 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: 4 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: 4 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: 3 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. 3 Related_Routines o sql$get_error_text 2 sql_get_message_vector Retrieves information from the message vector about the status of the last SQL statement. 3 Format sql_get_message_vector (addr, index) 3 Returns No value returned. 3 Arguments 4 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: 4 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 3 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 3 Related_Routines None. 2 sql_register_error_handler Registers an application's error handling routines with the SQL precompiler. 3 Format sql_register_error_handler (user-error-routine, user-data) 3 Returns No value returned. 3 Arguments 4 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: 4 user-data The address of the user-specified data Value: Address of the user-specified data Data type: Address Passing By value mechanism: 3 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. 3 Related_Routines o sql_deregister_error_handler o sql_get_error_handler 2 sql_signal 3 Format sql_signal () 3 Returns No value returned. 3 Arguments None. 3 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. 3 Related_Routines None.