GET DIAGNOSTICS statement

id="getdiag2">GET DIAGNOSTICS statement

The GET DIAGNOSTICS statement obtains information about the previous SQL statement that was executed. The syntax of GET DIAGNOSTICS in an SQL function, SQL procedure, or SQL trigger is a subset of what is supported as a GET DIAGNOSTICS statement in other contexts. See GET DIAGNOSTICS for details.

Syntax
                    .-CURRENT-.
>>-+--------+--GET--+---------+--DIAGNOSTICS--+-statement-information-+-><
   '-label:-'       '-STACKED-'               +-condition-information-+
                                              '-combined-information--'
 
statement-information:  
   .-,---------------------------------------------------------.
   V                                                           |
|----+-SQL-variable-name-1--+-- = --statement-information-item-+--|
     '-SQL-parameter-name-1-'
 
condition-information:  
|--CONDITION--+-+-SQL-variable-name-2--+-+---------------------->
              | '-SQL-parameter-name-2-' |
              '-integer------------------'
 
   .-,--------------------------------------------------------------.
   V                                                                |
>----+-SQL-variable-name-3--+-- = --+-connection-information-item-+-+--|
     '-SQL-parameter-name-3-'       '-condition-information-item--'
 
combined-information:  
|--+-SQL-variable-name-4--+-- = -------------------------------->
   '-SQL-parameter-name-4-'
 
                                                                 (1)
>--ALL--+------------------------------------------------------+-------|
        | .-,------------------------------------------------. |
        | V                                                  | |
        '---+-STATEMENT------------------------------------+-+-'
            '-+-CONDITION--+--+--------------------------+-'
              '-CONNECTION-'  +-+-SQL-variable-name-5--+-+
                              | '-SQL-parameter-name-5-' |
                              '-integer------------------'
 
Notes:

STATEMENT can only be specified once. If SQL-variable-name-5, SQL-parameter-name-5, or integer is not specified, CONDITION and CONNECTION can only be specified once.
statement-information-item:  
|--+-COMMAND_FUNCTION_CODE-----------+--------------------------|
   +-DB2_DIAGNOSTIC_CONVERSION_ERROR-+
   +-DB2_LAST_ROW--------------------+
   +-DB2_NUMBER_CONNECTIONS----------+
   +-DB2_NUMBER_PARAMETER_MARKERS----+
   +-DB2_NUMBER_RESULT_SETS----------+
   +-DB2_NUMBER_ROWS-----------------+
   +-DB2_NUMBER_SUCCESSFUL_SUBSTMTS--+
   +-DB2_RELATIVE_COST_ESTIMATE------+
   +-DB2_RETURN_STATUS---------------+
   +-DB2_ROW_COUNT_SECONDARY---------+
   +-DB2_ROW_LENGTH------------------+
   +-DB2_SQL_ATTR_CONCURRENCY--------+
   +-DB2_SQL_ATTR_CURSOR_CAPABILITY--+
   +-DB2_SQL_ATTR_CURSOR_HOLD--------+
   +-DB2_SQL_ATTR_CURSOR_ROWSET------+
   +-DB2_SQL_ATTR_CURSOR_SCROLLABLE--+
   +-DB2_SQL_ATTR_CURSOR_SENSITIVITY-+
   +-DB2_SQL_ATTR_CURSOR_TYPE--------+
   +-DYNAMIC_FUNCTION----------------+
   +-DYNAMIC_FUNCTION_CODE-----------+
   +-MORE----------------------------+
   +-NUMBER--------------------------+
   +-ROW_COUNT-----------------------+
   +-TRANSACTION_ACTIVE--------------+
   +-TRANSACTIONS_COMMITTED----------+
   '-TRANSACTIONS_ROLLED_BACK--------'
 
connection-information-item:  
|--+-CONNECTION_NAME-----------+--------------------------------|
   +-DB2_AUTHENTICATION_TYPE---+
   +-DB2_AUTHID_TRUNCATION-----+
   +-DB2_AUTHORIZATION_ID------+
   +-DB2_CONNECTION_METHOD-----+
   +-DB2_CONNECTION_NUMBER-----+
   +-DB2_CONNECTION_STATE------+
   +-DB2_CONNECTION_STATUS-----+
   +-DB2_CONNECTION_TYPE-------+
   +-DB2_DDM_SERVER_CLASS_NAME-+
   +-DB2_DYN_QUERY_MGMT--------+
   +-DB2_ENCRYPTION_TYPE-------+
   +-DB2_EXPANSION_FACTOR_FROM-+
   +-DB2_EXPANSION_FACTOR_TO---+
   +-DB2_PRODUCT_ID------------+
   +-DB2_SERVER_CLASS_NAME-----+
   +-DB2_SERVER_NAME-----------+
   '-DB2_USER_ID---------------'
 
condition-information-item:  
|--+-CATALOG_NAME------------------+----------------------------|
   +-CLASS_ORIGIN------------------+
   +-COLUMN_NAME-------------------+
   +-CONDITION_IDENTIFIER----------+
   +-CONDITION_NUMBER--------------+
   +-CONSTRAINT_CATALOG------------+
   +-CONSTRAINT_NAME---------------+
   +-CONSTRAINT_SCHEMA-------------+
   +-CURSOR_NAME-------------------+
   +-DB2_ERROR_CODE1---------------+
   +-DB2_ERROR_CODE2---------------+
   +-DB2_ERROR_CODE3---------------+
   +-DB2_ERROR_CODE4---------------+
   +-DB2_INTERNAL_ERROR_POINTER----+
   +-DB2_LINE_NUMBER---------------+
   +-DB2_MESSAGE_ID----------------+
   +-DB2_MESSAGE_ID1---------------+
   +-DB2_MESSAGE_ID2---------------+
   +-DB2_MESSAGE_KEY---------------+
   +-DB2_MODULE_DETECTING_ERROR----+
   +-DB2_NUMBER_FAILING_STATEMENTS-+
   +-DB2_OFFSET--------------------+
   +-DB2_ORDINAL_TOKEN_n-----------+
   +-DB2_PARTITION_NUMBER----------+
   +-DB2_REASON_CODE---------------+
   +-DB2_RETURNED_SQLCODE----------+
   +-DB2_ROW_NUMBER----------------+
   +-DB2_SQLERRD_SET---------------+
   +-DB2_SQLERRD1------------------+
   +-DB2_SQLERRD2------------------+
   +-DB2_SQLERRD3------------------+
   +-DB2_SQLERRD4------------------+
   +-DB2_SQLERRD5------------------+
   +-DB2_SQLERRD6------------------+
   +-DB2_TOKEN_COUNT---------------+
   +-DB2_TOKEN_STRING--------------+
   +-MESSAGE_LENGTH----------------+
   +-MESSAGE_OCTET_LENGTH----------+
   +-MESSAGE_TEXT------------------+
   +-PARAMETER_MODE----------------+
   +-PARAMETER_NAME----------------+
   +-PARAMETER_ORDINAL_POSITION----+
   +-RETURNED_SQLSTATE-------------+
   +-ROUTINE_CATALOG---------------+
   +-ROUTINE_NAME------------------+
   +-ROUTINE_SCHEMA----------------+
   +-SCHEMA_NAME-------------------+
   +-SERVER_NAME-------------------+
   +-SPECIFIC_NAME-----------------+
   +-SUBCLASS_ORIGIN---------------+
   +-TABLE_NAME--------------------+
   +-TRIGGER_CATALOG---------------+
   +-TRIGGER_NAME------------------+
   '-TRIGGER_SCHEMA----------------'
 
Description
CURRENT or STACKED

Specifies which diagnostics area to access.

CURRENT

Specifies to access the first diagnostics area. It corresponds to the previous SQL statement that was executed and that was not a GET DIAGNOSTICS statement. This is the default.

STACKED

Specifies to access the second diagnostics area. The second diagnostics area is only available within a handler. It corresponds to the previous SQL statement that was executed before the handler was entered and that was not a GET DIAGNOSTICS statement. If the GET DIAGNOSTICS statement is the first statement within a handler, then the first diagnostics area and the second diagnostics area contain the same diagnostics information.

statement-information

Returns information about the last SQL statement executed.

SQL-variable-name-1 or SQL-parameter-name-1

Identifies a variable described in the program in accordance with the rules for declaring SQL variables and SQL parameters. The data type of the SQL variable or SQL parameter must be compatible with the data type as specified in Table 58 for the specified condition information item. The SQL variable or SQL parameter is assigned the value of the specified statement information item. If the value is truncated when assigning it to the SQL variable or SQL parameter, a warning is returned (SQLSTATE 01004) and the GET_DIAGNOSTICS_DIAGNOSTICS item of the diagnostics area is updated with the details of this condition.
If a specified diagnostic item does not contain diagnostic information , then the SQL variable or SQL parameter is set to a default value, based on its data type: 0 for an exact numeric diagnostic item, an empty string for a VARCHAR diagnostic item and blanks for a CHAR diagnostic item.

condition-information
Returns information about the condition or conditions that occurred when the last SQL statement was executed.
CONDITION SQL-variable-name-2 or SQL-parameter-name-2 or integer

Identifies the diagnostic for which information is requested. Each diagnostic that occurs while executing an SQL statement is assigned an integer. The value 1 indicates the first diagnostic, 2 indicates the second diagnostic and so on. If the value is 1, then the diagnostic information retrieved corresponds to the condition indicated by the SQLSTATE value actually returned by the execution of the previous SQL statement (other than a GET DIAGNOSTICS statement). The SQL variable or SQL parameter specified must be described in the program in accordance with the rules for declaring numeric SQL variables or SQL parameters. The value specified must not be less than one or greater than the number of available diagnostics

SQL-variable-name-3 or SQL-parameter-name-3

Identifies a variable described in the program in accordance with the rules for declaring SQL variables or SQL parameters. The data type of the SQL variable or SQL parameter must be compatible with the data type as specified in Table 58 for the specified condition information item. The SQL variable or SQL parameter is assigned the value of the specified statement information item. If the value is truncated when assigning it to the SQL variable or SQL parameter, a warning is returned (SQLSTATE 01004) and the GET_DIAGNOSTICS_DIAGNOSTICS item of the diagnostics area is updated with the details of this condition.
If a specified diagnostic item does not contain diagnostic information , then the SQL variable or SQL parameter is set to a default value, based on its data type: 0 for an exact numeric diagnostic item, an empty string for a VARCHAR diagnostic item and blanks for a CHAR diagnostic item.

combined-information
Returns multiple information items combined into one string.
If the GET DIAGNOSTICS statement is specified in an SQL function, SQL procedure, or trigger, the GET DIAGNOSTICS statement must be the first statement specified in the handler that will handle the error.
If information is desired about a warning,

If a handler will get control for the warning condition, the GET DIAGNOSTICS statement must be the first statement specified in that handler.

If a handler will not get control for the warning condition, the GET DIAGNOSTICS statement must be the next statement executed after that previous statement.
SQL-variable-name-4 or SQL-parameter-name-4

Identifies a variable described in the program in accordance with the rules for declaring SQL variables or SQL parameters. The data type of the SQL variable or SQL parameter must be VARCHAR. If the length of SQL-variable-name-4 or SQL-parameter-name-4 is not sufficient to hold the full returned diagnostic string, the string is truncated, a warning is returned (SQLSTATE 01004) and the GET_DIAGNOSTICS_DIAGNOSTICS item of the diagnostics area is updated with the details of this condition.

ALL
Indicates that all diagnostic items that are set for the last SQL statement executed should be combined into one string. The format of the string is a semicolon separated list of all of the available diagnostic information in the form:
item-name=character-form-of-the-item-value;
The character form of a positive numeric value will not contain a leading plus sign (+) unless the item is RETURNED_SQLCODE. In this case, a leading plus sign (+) is added. For example:
 NUMBER=1;RETURNED_SQLSTATE=02000;DB2_RETURNED_SQLCODE=+100;
Only items that contain diagnostic information are included in the string.
STATEMENT

Indicates that all statement-information-item diagnostic items that contain diagnostic information for the last SQL statement executed should be combined into one string. The format is the same as described above for ALL.

CONDITION
Indicates that condition-information-item diagnostic items that contain diagnostic information for the last SQL statement executed should be combined into one string. If SQL-variable-name-5 or SQL-parameter-name-5 or integer is specified, then the format is the same as described above for the ALL option. If SQL-variable-name-5 or SQL-parameter-name-5 or integer is not specified, then the format includes a condition number entry at the beginning of the information for that condition in the form:
CONDITION_NUMBER=X;item-name=character-form-of-the-item-value;
where X is the number of the condition. For example:
CONDITION_NUMBER=1;RETURNED_SQLSTATE=02000;RETURNED_SQLCODE=+100;
CONDITION_NUMBER=2;RETURNED_SQLSTATE=01004;
CONNECTION
Indicates that connection-information-item diagnostic items that contain diagnostic information for the last SQL statement executed should be combined into one string. If SQL-variable-name-5 or SQL-parameter-name-5 or integer is specified, then the format is the same as described above for ALL. If SQL-variable-name-5 or SQL-parameter-name-5 or integer is not specified, then the format includes a connection number entry at the beginning of the information for that condition in the form:
CONNECTION_NUMBER=X;item-name=character-form-of-the-item-value;
where X is the number of the condition. For example:
CONNECTION_NUMBER=1;CONNECTION_NAME=SVL1;DB2_PRODUCT_ID=DSN07010;
SQL-variable-name-5 or SQL-parameter-name-5 or integer

Identifies the diagnostic for which ALL CONDITION or ALL CONNECTION information is requested. The SQL variable or SQL parameter specified must be described in the program in accordance with the rules for declaring numeric SQL variables or SQL parameters. The value specified must not be less than one or greater than the number of available diagnostics.
statement-information-item

For a description of the statement-information-items, see statement-information-item.

connection-information-item

For a description of the connection-information-items, see connection-information-item.

condition-information-item

For a description of the condition-information-items, see condition-information-item.
Notes

Effect of statement: The GET DIAGNOSTICS statement does not change the contents of the diagnostics area. If an SQLSTATE or SQLCODE special variable is declared in an SQL procedure, SQL function, or SQL trigger, these are set to the SQLSTATE or SQLCODE returned from issuing the GET DIAGNOSTICS statement.
If the SQLSTATE or SQLCODE values are needed by the handler following the GET DIAGNOSTIC statement, then either they must be saved or they can be accessed by specifying the DB2_RETURNED_SQLCODE or the RETURNED_SQLSTATE condition items on the GET DIAGNOSTIC statement.
Case of return values: Values for identifiers in returned diagnostic items are not delimited and are case sensitive. For example, a table name of "abc" would be returned, simply as abc.
Data types for items: When a diagnostic item is assigned to a SQL variable or SQL parameter, the SQL variable or SQL parameter must be compatible with the data type of the diagnostic item. For more information, see Table 58.
Keyword Synonym: The following keywords are synonyms supported for compatibility to prior releases. These keywords are non-standard and should not be used:

The keyword EXCEPTION can be used as a synonym for CONDITION.

The keyword RETURN_STATUS can be used as a synonym for DB2_RETURN_STATUS.

Example

In an SQL procedure, execute a GET DIAGNOSTICS statement to determine how many rows were updated.
   CREATE PROCEDURE sqlprocg (IN deptnbr VARCHAR(3))
     LANGUAGE SQL
     BEGIN
       DECLARE SQLSTATE CHAR(5);
       DECLARE rcount INTEGER;
       UPDATE CORPDATA.PROJECT          SET PRSTAFF = PRSTAFF + 1.5
         WHERE DEPTNO = deptnbr;
       GET DIAGNOSTICS rcount = ROW_COUNT;
       /* At this point, rcount contains the number of rows that were updated. */
     END
       
Within an SQL procedure, handle the returned status value from the invocation of a stored procedure called TRYIT. TRYIT could use the RETURN statement to explicitly return a status value or a status value could be implicitly returned by the database manager. If the procedure is successful, it returns a value of zero.
   CREATE PROCEDURE TESTIT ()
     LANGUAGE SQL
     A1: BEGIN
         DECLARE RETVAL INTEGER DEFAULT 0;
         ...
         CALL TRYIT          GET DIAGNOSTICS RETVAL = RETURN_STATUS;
         IF RETVAL <> 0 THEN
            ...
            LEAVE A1;
         ELSE
            ...
         END IF;
     END A1
       
In an SQL procedure, execute a GET DIAGNOSTICS statement to retrieve the message text for an error.
   CREATE PROCEDURE divide2 ( IN numerator INTEGER,
 	                      IN denominator INTEGER, 
	                      OUT divide_result INTEGER, 
                           OUT divide_error VARCHAR(70) )
  LANGUAGE SQL
    BEGIN
       DECLARE CONTINUE HANDLER FOR SQLEXCEPTION 
          GET DIAGNOSTICS EXCEPTION 1
            divide_error = MESSAGE_TEXT;
       SET divide_result = numerator / denominator;
    END;      
[ Top of Page | Previous Page | Next Page | Contents |
Index ]