CLI function return codes

You can use a CLI function to return code to detect when a function succeeds or fails. You can also use return codes in a control block to detect when data retrieval is complete.

The following table lists all possible return codes for CLI functions.

Table 1. CLI Function return codes
Return code	Explanation
SQL_SUCCESS	The function completed successfully, no additional SQLSTATE information is available.
SQL_SUCCESS_WITH_INFO	The function completed successfully with a warning or other information. Call `SQLGetDiagRec()` or `SQLGetDiagField()` to receive the SQLSTATE and any other informational messages or warnings. The SQLSTATE will have a class of '01'.
SQL_STILL_EXECUTING	The function is running asynchronously and has not yet completed. The CLI driver has returned control to the application after calling the function, but the function has not yet finished executing.
SQL_NO_DATA_FOUND	The function returned successfully, but no relevant data was found. When this is returned after the execution of an SQL statement, additional information may be available and can be obtained by calling `SQLGetDiagRec()` or `SQLGetDiagField()`.
SQL_NEED_DATA	The application tried to execute an SQL statement but CLI lacks parameter data that the application had indicated would be passed at execute time.
SQL_ERROR	The function failed. Call `SQLGetDiagRec()` or `SQLGetDiagField()` to receive the SQLSTATE and any other error information.
SQL_INVALID_HANDLE	The function failed due to an invalid input handle (environment, connection or statement handle). This is a programming error. No further information is available.

The following code segment shows how a function return code, SQL_NO_DATA_FOUND, can be used to control when data retrieval should stop:

  while (cliRC != SQL_NO_DATA_FOUND)
  {
    printf("     %-8d %-14.14s \n", deptnumb.val, location.val);
       /* fetch next row */
    cliRC = SQLFetch(hstmt);
    STMT_HANDLE_CHECK(hstmt, hdbc, cliRC);
  }