INFORMIX-ESQL/C Programmer's Manual Working with the Database Server

The timeout program demonstrates how to set up a time-out interval. This program uses the sqlbreakcallback() function to perform the following actions:

• To specify a time-out interval of 200 milliseconds for execution of an SQL request
• To register the on_timeout() callback function to be called when an SQL request begins and ends as well as when the time-out interval elapses

If execution of an SQL request exceeds the time-out interval, the callback function uses the sqldone() function to ensure that the database server is still busy, prompts the user for confirmation of the interrupt, and then uses the sqlbreak() function to send an interrupt request to the database server.

Use the following command to compile the timeout program:

esql -o timeout timeout.ec

The -o timeout option causes the executable program to be named timeout. Without the -o option, the name of the executable program defaults to a.out. See Using the esql Command for more information on the esql command.

/*

* timeout.ec *

*/

#include <stdio.h>

#include <string.h>

#include <ctype.h>

#include <decimal.h>

#include <errno.h>

EXEC SQL include sqltypes;

#define LCASE(c) (isupper(c) ? tolower(c) : (c))

/* Defines for callback mechanism */

#define DB_TIMEOUT 200 /* number of milliseconds in time-out */

#define SQL_INTERRUPT -213 /* SQLCODE value for interrupted stmt */

/* These constants are used for the canceltst table, created by

* this program.

*/

#define MAX_ROWS 10000 /* number of rows added to table */

EXEC SQL define CHARFLDSIZE 20; /* size of character columns in table */

/* Define for sqldone() return values */

#define SERVER_BUSY -439

/* These constants used by the exp_chk2() function to determine

* whether to display warnings.

*/

#define WARNNOTIFY 1

#define NOWARNNOTIFY 0

int4 dspquery();

extern int4 exp_chk2();

void on_timeout();

main()

{

char ques[80], prompt_ans();

int4 ret;

mint create_tbl(), drop_tbl();

printf("TIMEOUT Sample ESQL Program running.\n\n");

/*

* Establish an explicit connection to the stores7 database

* on the default database server.

*/

EXEC SQL connect to 'stores7';

Lines 4 to 8 include the UNIX header files from the /usr/include directory. The ESQL/C sqltypes.h header file (line 9) defines names for integer values that identify SQL and C data types.

Line 10 defines LCASE, a macro that converts an uppercase character to a lowercase character. The DB_TIMEOUT (line 12) constant defines the number of milliseconds in the time-out interval. The SQL_INTERRUPT constant (line 13) defines the SQLCODE value that the database server returns when it interrupts an SQL statement.

Lines 17 and 18 define constants that the create_tbl() function uses to create the canceltst table. This table holds the test data needed for the large query (lines 125 to 132). MAX_ROWS is the number of rows that create_tbl() inserts into canceltst. You can change this number if you find that the query does not run long enough for you to interrupt it. CHARFLDSIZE is the number of characters in the character fields (char_fld1 and char_fld2) of canceltst.

Line 20 defines the SERVER_BUSY constant to hold the sqldone() return value that indicates that the database server is busy processing an SQL request. Use of this constant makes code more readable and removes the explicit return value from the code.

The exp_chk2() exception-handling function uses the WARNNOTIFY and NOWARNNOTIFY constants (lines 24 and 25). Calls to exp_chk2() specify one of these as the second argument to indicate whether the function displays SQLSTATE and SQLCODE information for warnings (WARNNOTIFY) or does not display this information for warnings (NOWARNNOTIFY). For more information on the exp_chk2() function, see Lines 348 to 355.

The main() program block begins on line 29. Lines 31 to 33 declare variables local to the main() program block.

if (exp_chk2("CONNECT to stores7", NOWARNNOTIFY) < 0)

exit(1);

printf("Connected to 'stores7' on default server\n");

/*

* Create the canceltst table to hold MAX_ROWS (10,000) rows.

*/

if (!create_tbl())

{

printf("\nTIMEOUT Sample Program over.\n\n");

exit(1);

}

while(1)

{

/*

* Establish on_timeout() as callback function. The callback

* function is called with an argument value of 2 when the

* database server has executed a single SQL request for number

* of milliseconds specified by the DB_TIMEOUT constant

* (0.00333333 minutes by default). Call to sqlbreakcallback()

* must come after server connection is established and before

* the first SQL statement that can be interrupted.

*/

if (sqlbreakcallback(DB_TIMEOUT, on_timeout))

{

printf("\nUnable to establish callback function.\n");

printf("TIMEOUT Sample Program over.\n\n");

exit(1);

}

/*

* Notify end user of time-out interval.

*/

printf("Time-out interval for SQL requests is: ");

printf("%0.8f minutes\n", DB_TIMEOUT/60000.00);

stcopy("Are you ready to begin execution of the query?",

ques);

if (prompt_ans(ques) == 'n')

{

/*

* Unregister callback function so table cleanup will not

* be interrupted.

*/

sqlbreakcallback(-1L, (void *)NULL);

break;

}

The create_tbl() function creates the canceltst table in the stores7 database. It inserts MAX_ROWS number of rows into this table. If create_tbl() encounters some error while it creates canceltst, execution of the timeout program cannot continue. The program exits with a status value of 1 (line 49).

This while loop (which ends on line 97), controls the execution of the query on the canceltst table. It allows the user to run this query multiple times to test various interrupt scenarios.

The first task of the while loop is to use sqlbreakcallback() to specify a time-out interval of DB_TIMEOUT (200) milliseconds and to register on_timeout() as the callback function. If this call to sqlbreakcallback() fails, the program exits with a status value of 1. To test different time-out intervals, you can change the DB_TIMEOUT constant value and recompile the timeout.ec source file.

These printf() functions notify the user of the time-out interval. Notice that the message displays this interval in minutes, not milliseconds. It divides the DB_TIMEOUT value by 60,000 (number of milliseconds in a minute).

The prompt_ans() function asks the user to indicate when to begin execution of the canceltst query. If the user enters n (no), the program calls the sqlbreakcallback() function to unregister the callback function. This call prevents the SQL statements in the drop_tbl() function (lines 322 to 329) from initiating the callback function. For a description of the prompt_ans() function, see Lines 337 to 347.

/*

* Start display of query output

*/

printf("\nBeginning execution of query...\n\n");

if ((ret = dspquery()) == 0)

{

if (prompt_ans("Try another run?") == 'y')

continue;

else

break;

}

else /* dspquery() encountered an error */

exit(1);

} /* end while */

/*

* Drop the table created for this program

*/

drop_tbl();

EXEC SQL disconnect current;

if (exp_chk2("DISCONNECT for stores7", WARNNOTIFY) != 0)

exit(1);

printf("\nDisconnected stores7 connection\n");

printf("\nTIMEOUT Sample Program over.\n\n");

}

/* This function performs the query on the canceltst table. */

int4 dspquery()

{

mint cnt = 0;

int4 ret = 0;

int4 sqlcode = 0;

int4 sqlerr_code, sqlstate_err();

void disp_exception(), disp_error(), disp_warning();

EXEC SQL BEGIN DECLARE SECTION;

char fld1_val[ CHARFLDSIZE + 1 ];

char fld2_val[ CHARFLDSIZE + 1 ];

int4 int_val;

EXEC SQL END DECLARE SECTION;

/* This query contains an artifically complex WHERE clause to

* keep the database server busy long enough for an interrupt

* to occur.

*/

EXEC SQL declare cancel_curs cursor for

select sum(int_fld), char_fld1, char_fld2

from canceltst

where char_fld1 matches "*f*"

or char_fld1 matches "*h*"

or char_fld2 matches "*w*"

or char_fld2 matches "*l*"

group by char_fld1, char_fld2;

If the user chooses to continue the query, the program calls the dspquery() function (line 88) to run the canceltst query. The prompt_ans() function displays a prompt so the user can decide whether to run the program again.

The drop_tbl() function drops the canceltst table from the stores7 database to clean up after the program.

The dspquery() function runs a query of the canceltst table and displays the results. It returns zero (success) or the negative value of SQLCODE (failure) to indicate the result of the canceltst query.

Line 125 declares the cancel_curs cursor for the query. The actual SELECT (lines 126 to 132) obtains the sum of the int_fld column and the values of the two character columns (char_fld1 and char_fld2). The WHERE clause uses the MATCHES operator to specify matching rows, as follows:

• All char_fld1 columns that contain an f or an h with the criteria:
char_fld1 matches "*f*"
or char_fld1 matches "*h*"

These criteria match rows with a char_fld1 value of Informix or "4100 Bohannon Dr."

• All char_fld2 columns that contain a w or an l with the criteria:
char_fl2 matches "*w*"
or char_fld2 matches "*l*"

These criteria match rows with a char_fld2 value of Software or "Menlo Park, CA".

This SELECT is artificially complex to ensure that the query takes a long time to execute. Without a reasonably complex query, the database server finishes execution before the user has a chance to interrupt it. In a production application, only use the sqlbreakcallback() feature with queries that take a long time to execute.

EXEC SQL open cancel_curs;

sqlcode = SQLCODE;

sqlerr_code = sqlstate_err(); /* check SQLSTATE for exception */

if (sqlerr_code != 0) /* if exception found */

{

if (sqlerr_code == -1) /* runtime error encountered */

{

if (sqlcode == SQL_INTERRUPT) /* user interrupt */

{

/* This is where you would clean up resources */

printf("\n TIMEOUT INTERRUPT PROCESSED\n\n");

sqlcode = 0;

}

else /* serious runtime error */

disp_error("OPEN cancel_curs");

EXEC SQL close cancel_curs;

EXEC SQL free cancel_curs;

return(sqlcode);

}

else if (sqlerr_code == 1) /* warning encountered */

disp_warning("OPEN cancel_curs");

}

This OPEN statement causes the database server to execute the SELECT that is associated with the cancel_curs cursor. Because the database server executes the canceltst query at this point, this OPEN is the statement that the user would be most likely to interrupt. When the FETCH executes, the database server just sends matching rows to the application, an operation that is not usually time intensive.

This block of code checks the success of the OPEN. Since the OPEN can be interrupted, this exception checking must include an explicit check for the interrupt value of -213. The database server sets SQLCODE to -213 when it has interrupted an SQL request. On line 140, the program uses the SQL_INTERRUPT defined constant (which line 13 defines), for this SQLCODE value.

The sqlstate_err() function (line 135) uses the GET DIAGNOSTICS statement to analyze the value of the SQLSTATE variable. If this function returns a non-zero value, SQLSTATE indicates a warning, a runtime error, or the NOT FOUND condition. Before the call to sqlstate_err(), line 134 saves the SQLCODE value so that execution of any other SQL statements (such as GET DIAGNOSTICS in sqlstate_err()) does not overwrite it. The function returns the value of SQLCODE if the OPEN encounters a runtime error (line 150).

The first if statement (line 136) checks if the OPEN encounters any type of exception (sqlstate_err() returns a nonzero value). The second if (line 138) checks if the OPEN has generated a runtime error (return value of -1). However, if the database server has interrupted the OPEN, sqlstate_err() also returns -1. Since ESQL/C does not handle an interrupted SQL statement as a runtime error, the third if checks explicitly for the SQL_INTERRUPT value (line 140). If the OPEN was interrupted, line 143 notifies the user that the interrupt request was successful and then the function resets the saved SQLCODE value (in sqlcode) to zero to indicate that the OPEN did not generate a runtime error.

Lines 146 and 147 execute only if the OPEN generates a runtime error other than SQL_INTERRUPT (-213). The disp_error() function displays the exception information in the diagnostics area and the SQLCODE value. Lines 148 to 150 clean up after the OPEN. They close and free the cancel_curs cursor and then return the SQLCODE value. The dspquery() function does not continue with the FETCH (line 158) if the OPEN was interrupted.

If sqlstate_err() returns one (1), the OPEN has generated a warning. Lines 152 and 153 call the disp_warning() function to display warning information from the diagnostics area. For more information on the disp_error() and disp_warning() functions, see Lines 341 to 348 on page 12-67.

printf("Displaying data...\n");

while(1)

{

EXEC SQL fetch cancel_curs into :int_val, :fld1_val, :fld2_val;

if ((ret = exp_chk2("FETCH from cancel_curs", NOWARNNOTIFY)) == 0)

{

printf(" sum(int_fld) = %d\n", int_val);

printf(" char_fld1 = %s\n", fld1_val);

printf(" char_fld2 = %s\n\n", fld2_val);

}

/*

* Will display warning messages (WARNNOTIFY) but continue

* execution when they occur (exp_chk2() == 1)

*/

else

{

if (ret==100) /* NOT FOUND condition */

{

printf("\nNumber of rows found: %d\n\n", cnt);

break;

}

if (ret < 0) /* Runtime error */

{

EXEC SQL close cancel_curs;

EXEC SQL free cancel_curs;

return(ret);

}

}

cnt++;

} /* end while */

EXEC SQL close cancel_curs;

EXEC SQL free cancel_curs;

return(0);

}

/*

* The on_timeout() function is the callback function. If the user

* confirms the cancellation, this function uses sqlbreak() to

* send an interrupt request to the database server.

*/

void on_timeout(when_called)

mint when_called;

{

mint ret;

static intr_sent;

This while loop executes for each row that the cancel_curs cursor contains. The FETCH statement (line 158) retrieves one row from the cancel_curs cursor. If the FETCH generates an error, the function releases the cursor resources and returns the SQLCODE error value (lines 176 to 181). Otherwise, the function displays the retrieved data to the user. On the last row (ret = 100), the function displays the number of rows that it retrieved (line 173).

After the FETCH has retrieved the last row from the cursor, the function releases resources allocated to the cancel_curs cursor and returns a success value of zero.

The on_timeout() function is the callback function for the timeout program. The sqlbreakcallback() call on line 62 registers this callback function and establishes a time-out interval of 200 milliseconds. This function is called every time the database server begins and ends an SQL request. For long-running requests, the application also calls on_timeout() each time the time-out interval elapses.

/* Determine when callback function has been called. */

switch(when_called)

{

case 0: /* Request to server completed */

printf("+------SQL Request ends");

printf("-------------------------------+\n\n");

/*

* Unregister callback function so no further SQL statements

* can be interrupted.

*/

if (intr_sent)

sqlbreakcallback(-1L, (void *)NULL);

break;

case 1: /* Request to server begins */

printf("+------SQL Request begins");

printf("-----------------------------+\n");

printf("| ");

printf(" |\n");

intr_sent = 0;

break;

case 2: /* Time-out interval has expired */

/*

* Is the database server still processing the request?

*/

if (sqldone() == SERVER_BUSY)

if (!intr_sent) /* has interrupt already been sent? */

{

printf("| An interrupt has been received ");

printf("by the application.|\n");

printf("| ");

printf(" |\n");

/*

* Ask user to confirm interrupt

*/

if (cancel_request())

{

printf("| TIMEOUT INTERRUPT ");

printf("REQUESTED |\n");

/*

* Call sqlbreak() to issue an interrupt request for

* current SQL request to be cancelled.

*/

sqlbreak();

}

intr_sent = 1;

}

break;

This switch statement uses the callback function argument, when_called, to determine the actions of the callback function, as follows:

• Lines 202 to 211: If when_called is 0, the callback function was called after the database server ends an SQL request. The function displays the bottom of the message-request box to indicate the end of the SQL request, as follows:
+------SQL Request ends-------------------------------+
• Lines 212 to 218: If when_called is 1, the callback function was called when the database server begins an SQL request. The display of the top of the message-request box indicates this condition:
+------SQL Request begins-----------------------------+
| |

For more information on these message-request boxes, see Lines 21 to 30. The function also initializes the intr_sent flag to 0 because the user has not yet sent an interrupt for this SQL request.

• Lines 219 to 245: If when_called is 2, the callback function was called because the time-out interval has elapsed.

To handle the elapsed time-out interval, the callback function first calls the ESQL/C sqldone() function (line 223) to determine whether the database server is still busy processing the SQL request. If the database server is idle, the application does not need to send an interrupt. If sqldone() returns SERVER_BUSY (-439), the database server is still busy.

Line 224 checks if the user has already attempted to interrupt the SQL request that is currently executing. If an interrupt was sent, intr_sent is 1, and the program does not need to send another request. If an interrupt request has not yet been sent, the callback function notifies the user that the time-out interval has elapsed (lines 226 to 229). It then uses the cancel_request() function (line 233) to allow the user to confirm the interrupt. For more information on cancel_request(), see Lines 251 to 261.

default:

printf("Invalid status value in callback: %d\n", when_called);

break;

}

}

/* This function prompts the user to confirm the sending of an

* interrupt request for the current SQL request.

*/

mint cancel_request()

{

char prompt_ans();

if (prompt_ans("Do you want to confirm this interrupt?") == 'n')

return(0); /* don't interrupt SQL request */

else

return(1); /* interrupt SQL request */

}

/* This function creates a new table in the current database. It

* populates this table with MAX_ROWS rows of data. */

mint create_tbl()

{

char st_msg[15];

int ret = 1;

EXEC SQL BEGIN DECLARE SECTION;

mint cnt;

mint pa;

mint i;

char fld1[ CHARFLDSIZE + 1 ], fld2[ CHARFLDSIZE + 1 ];

EXEC SQL END DECLARE SECTION;

/*

* Create canceltst table in current database

*/

EXEC SQL create table canceltst (char_fld1 char(20),

char_fld2 char(20), int_fld integer);

if (exp_chk2("CREATE TABLE", WARNNOTIFY) < 0)

return(0);

printf("Created table 'canceltst'\n");

/*

* Insert MAX_ROWS of data into canceltst

*/

printf("Inserting rows into 'canceltst'...\n");

for (i = 0; i < MAX_ROWS; i++)

{

If the user confirms the interrupt, the callback function calls the sqlbreak() function to send the interrupt request to the database server. The callback function does not wait for the database server to respond to the interrupt request. Execution continues to line 243 and sets the intr_sent flag to 1, to indicate that the interrupt request was sent. If the callback function was called with an invalid argument value (a value other than 0, 1, or 2), the function displays an error message (line 247).

The cancel_request() function asks the user to confirm the interrupt request. It displays the prompt:

Do you want to confirm this interrupt?

If the user answers y (yes), cancel_request() returns 0. If the user answers n (no), cancel_request() returns 1.

The create_tbl() function creates the canceltst table and inserts the test data into this table. The CREATE TABLE statement (lines 277 and 278) creates the canceltst table with three columns: int_fld, char_fld1, and char_fld2. If the CREATE TABLE encounters an error, the exp_chk2() function (line 279) displays the diagnostics-area information and create_tbl() returns zero (0) to indicate that an error has occurred.

This for loop controls the insertion of the canceltst rows. The MAX_ROWS constant determines the number of iterations for the loop, and hence the number of rows that the function inserts into the table. If you cannot interrupt the canceltst query (lines 126 to 132) because it executes too quickly, increase the value of MAX_ROWS and recompile the timeout.ec file.

if (i%2 == 1) /* odd-numbered rows */

{

stcopy("4100 Bohannan Dr", fld1);

stcopy("Menlo Park, CA", fld2);

}

else /* even-numbered rows */

{

stcopy("Informix", fld1);

stcopy("Software", fld2);

}

EXEC SQL insert into canceltst

values (:fld1, :fld2, :i);

if ( (i+1)%1000 == 0 ) /* every 1000 rows */

printf(" Inserted %d rows\n", i+1);

sprintf(st_msg, "INSERT #%d", i);

if (exp_chk2(st_msg, WARNNOTIFY) < 0)

{

ret = 0;

break;

}

}

printf("Inserted %d rows into 'canceltst'.\n", MAX_ROWS);

/*

* Verify that MAX_ROWS rows have added to canceltst

*/

printf("Counting number of rows in 'canceltst' table...\n");

EXEC SQL select count(*) into :cnt from canceltst;

if (exp_chk2("SELECT count(*)", WARNNOTIFY) < 0)

return(0);

printf("Number of rows = %d\n\n", cnt);

return (ret);

}

/* This function drops the 'canceltst' table */

mint drop_tbl()

{

printf("\nCleaning up...\n");

EXEC SQL drop table canceltst;

if (exp_chk2("DROP TABLE", WARNNOTIFY) < 0)

return(0);

printf("Dropped table 'canceltst'\n");

return(1);

}

This if statement generates the values for the char_fld1 and char_fld2 columns of the canceltst table. Lines 290 and 291 execute for odd-numbered rows. They store the strings "4100 Bohannon Dr" and "Menlo Park, CA" in the fld1 and fld2 variables, respectively.

Lines 295 and 296 execute for even-numbered rows. They store the strings Informix and Software in the fld1 and fld2 variables, respectively.

The INSERT statement inserts a row into the canceltst table. It takes the value for the int_fld column from the :i host variable (the row number), and the values for the char_fld1 and char_fld2 columns from the :fld1 and :fld2 host variables, respectively. The function notifies the user after it inserts every 1000 rows (lines 300 and 301). If the INSERT encounters an error, the exp_chk2() function (line 303) displays the diagnostics-area information and create_tbl() returns zero to indicate that an error has occurred.

These lines verify that the program has added the rows to the canceltst table and that it can access them. The program does a SELECT on the newly created canceltst table and returns the number of rows found. The program checks whether this number matches the number that the function has added, which line 309 displays. If the SELECT encounters an error, the exp_chk2() function (line 315) displays the diagnostics-area information, and create_tbl() returns 0 to indicate that an error has occurred.

The drop_tbl() function drops the canceltst table from the current database. If the DROP TABLE statement (line 324) encounters an error, the exp_chk2() function displays the diagnostics-area information and drop_tbl() returns 0 to indicate that an error has occurred.

/*

* The inpfuncs.c file contains the following functions used in this

* program:

* getans(ans, len) - accepts user input, up to 'len' number of

* characters and puts it in 'ans'

*/

#include "inpfuncs.c"

char prompt_ans(question)

char * question;

{

char ans = ` `;

while(ans != 'y' && ans != 'n')

{

printf("\n*** %s (y/n): ", question);

getans(&ans,1);

}

return ans;

}

/*

* The exp_chk() file contains the exception handling functions to

* check the SQLSTATE status variable to see if an error has occurred

* following an SQL statement. If a warning or an error has

* occurred, exp_chk2() executes the GET DIAGNOSTICS statement and

* displays the detail for each exception that is returned.

*/

EXEC SQL include exp_chk.ec;

Several of the ESQL/C demonstration programs also call the getans() function. Therefore, this function is broken out into a separate C source file and included in the appropriate demonstration program. Because this function does not contain ESQL/C, the program can use the C #include preprocessor statement to include the file. For a description of this function, see Guide to the inpfuncs.c File.

The prompt_ans() function displays the string in the question argument and waits for the user to enter y (yes) or n (no) as a response. It returns the single-character response.

The timeout program uses the exp_chk2(), sqlstate_err(), disp_error(), and disp_warning() functions to perform its exception handling. Because several demonstration programs use these functions, the exp_chk2() function and its supporting functions have been placed in a separate exp_chk.ec source file. The timeout program must include this file with the ESQL/C include directive because the exception-handling functions use ESQL/C statements. For a description of the exp_chk.ec file, see Guide to the exp_chk.ec File.

Tip: In a production environment, you would put functions such as getans(), exp_chk2(), sqlstate_err(), disp_error(), and disp_warning() into a library and include this library on the command line of the ESQL/C-program compilation.

Example Output

This section includes a sample output of the timeout demonstration program. This program performs two runs of the canceltst query, as follows:

• Lines 20 to 43: The first run confirms the interrupt request as soon as the confirmation prompt appears. (The user enters y.)
• Lines 44 to 75: The second run does not confirm the interrupt request. (The user enters n.)

The numbers that appear in the following output are for explanation only. They do not appear in the actual program output.

TIMEOUT Sample ESQL Program running.

Connected to 'stores7' on default server

Created table 'canceltst'

Inserting rows into 'canceltst'...

Inserted 1000 rows

Inserted 2000 rows

Inserted 3000 rows

Inserted 4000 rows

Inserted 5000 rows

Inserted 6000 rows

Inserted 7000 rows

Inserted 8000 rows

Inserted 9000 rows

Inserted 10000 rows

Inserted 10000 rows into 'canceltst'.

Counting number of rows in 'canceltst' table...

Number of rows = 10000

Time-out interval for SQL requests is: 0.00333333 minutes

*** Are you ready to begin execution of the query? (y/n): y

Beginning execution of query...

+------SQL Request begins-----------------------------+

| |

+------SQL Request ends-------------------------------+

+------SQL Request begins-----------------------------+

| |

| An interrupt has been received by the application.|

| |

*** Do you want to confirm this interrupt? (y/n): y

| TIMEOUT INTERRUPT REQUESTED |

+------SQL Request ends-------------------------------+

The create_tbl() function generates these lines. They indicate that the function has successfully created the canceltst table, inserted the MAX_ROWS number of rows (1,000), and confirmed that a SELECT statement can access these rows. For a description of the create_tbl() function, see the annotation beginning with Lines 262 to 281.

Line 18 displays the time-out interval to indicate that sqlbreakcallback() has successfully registered the callback function and established the time-out interval of 200 milliseconds (0.00333333 minutes). Line 19 asks the user to indicate the beginning of the query execution. This prompt prepares the user for the confirmation prompt (lines 28 and 43), which must be answered quickly to send an interrupt while the database server is still executing the query.

This line indicates the beginning of the dspquery() function, the point at which the database server begins the canceltst query.

The program output uses a message-request box to indicate client-server communication:

+------SQL Request begins-----------------------------+
|                                                     |
+------SQL Request ends-------------------------------+

Each box represents a single message request sent between the client and the server. The callback function displays the text for a message-request box. (For a description of which parts of the function display the text, see Lines 199 to 249.) To execute the OPEN statement, the client and server exchanged two message requests, which the two message-request boxes in the output indicate. For more information on message requests, see Interruptible SQL Statements.

The first message-request box (lines 21 to 23) indicates that the first message request completes before the time-out interval elapses. The second message-request box (lines 29 to 30) indicates that execution of this message request exceeds the time-out interval and calls the callback function with a status value of 2. The callback function prompts the user to confirm the interrupt request (line 28).

Line 29 indicates that the sqlbreak() function has requested an interrupt. The message request then completes (line 30).

TIMEOUT INTERRUPT PROCESSED

*** Try another run? (y/n): y

Time-out interval for SQL requests is: 0.00333333 minutes

*** Are you ready to begin execution of the query? (y/n): y

Beginning execution of query...

+------SQL Request begins-----------------------------+

| |

+------SQL Request ends-------------------------------+

+------SQL Request begins-----------------------------+

| |

| An interrupt has been received by the application.|

| |

*** Do you want to confirm this interrupt? (y/n): n

+------SQL Request ends-------------------------------+

Displaying data...

sum(int_fld) = 25000000

char_fld1 = 4100 Bohannan Dr

char_fld2 = Menlo Park, CA

sum(int_fld) = 24995000

char_fld1 = Informix

char_fld2 = Software

Number of rows found: 2

*** Try another run? (y/n): n

Cleaning up...

Dropped table 'canceltst'

Disconnected stores7 connection

TIMEOUT Sample Program over.

When the database server actually processes the interrupt request, it sets SQLCODE to -213. Line 31 indicates that the application program has responded to this status.

This prompt indicates the end of the first run of the canceltst query. The user responds y to the prompt to run the query a second time.

The message-request box indicates that the first message request completes before the time-out interval elapses. The second message-request box (lines 39 to 44) indicates that execution of this message request again exceeds the time-out interval and calls the callback function (with when_called = 2). The callback function prompts the user to confirm the interrupt request (line 43). This time the user answers n.

Because the user has not interrupted the canceltst query, the program displays the row information that the query returns.

The drop_tbl() function generates these lines. They indicate that the function has successfully dropped the canceltst table from the database. For a description of the drop_tbl() function, see the annotation beginning with Lines 320 to 329.