When the database server completes the processing of an SQL request
status = 0
- It can call the sqlbreak() function to cancel the SQL request.
- It can omit the call to sqlbreak() to continue the SQL request.
- It disassociates the callback function to discontinue the calling of the callback function, as follows: sqlbreakcallback(-1L, (void *)NULL);
- It defines some other callback function or resets the time-out value to a nonzero value, as follows: sqlbreakcallback(timeout, callbackfunc_ptr);
 | Important: Small time-out values might adversely affect the performance of your application. |
You must establish a database server connection before you call the sqlbreakcallback() function. The callback function remains in effect for the duration of the connection or until the sqlbreakcallback() function redefines the callback function.
Return Codes
0 | The call to sqlbreakcallback() was successful. |
<0 | The call to sqlbreakcallback() was not successful. |
sqldetach()
The sqldetach() function detaches a process from the database server. You generally call this function when an application forks a new process to begin a new stream of execution.
Syntax
Usage
If an application spawns one or more processes after it initiates a connection to a database server, all the child processes inherit that database server connection from the parent process (the application process that spawned the child). However, the database server still assumes that this connection has only one process. If one database server connection tries to serve both the parent and child processes at the same time, problems can result. For example, if both processes send messages to do something, the database server has no way of knowing which messages belong to which process. The database server might not receive messages in an order that makes sense and might thereby generate an error (such as error -408).In this situation, call the sqldetach() function from the child process. The sqldetach() function detaches the child process from the connection that the parent process establishes (which the child inherits). This action drops all database server connections in the child process. The child process can then establish its own connection to a database server.
Use the sqldetach() function with the fork() system call. When you spawn a child process from an application process with a database server connection, sequence the function calls as follows:
1. Call fork() from the parent process to create a copy of the parent process (the child process). Now both parent and child share the same connection to the database server.
A call to the sqldetach() function does not affect the database server sessions of the parent process. Therefore, after sqldetach() executes in the child process, the parent process retains any open cursors, transactions, or databases, and the child process has neither database server sessions nor database server connections.
When you call the sqlexit() function from the parent process, the function drops the connection in the parent process but does not affect the connections in the child process. Similarly, when you call sqlexit() from the child process, the function drops only the child connections; it does not affect the parent connections. The sqlexit() function rolls back any open transactions before it closes the connection.
If you execute the DISCONNECT statement from a child process, you disconnect the process from database server connections and terminate the database server sessions that correspond to those connections. The DISCONNECT fails if any transactions are open.
If the child process application has only one implicit connection before it calls sqldetach(), execution of the next SQL statement or of the sqlstart() library function reestablishes an implicit connection to the default database server. If the application has made one or more explicit connections, you must issue a CONNECT statement before you execute any other SQL statements.
The sqldetach demonstration program illustrates how to use the sqldetach() function.
Return Codes
0 | The call to sqldetach() was successful. |
<0 | The call to sqldetach() was not successful. |
Example
The sqldetach.ec file in the demo directory contains this sample program.
Example Output
sqldone()
The sqldone() function determines whether the database server is currently processing an SQL request.
Syntax
Usage
Use sqldone() to test the status of the database server in the following situations:
- Before a call to the sqlbreak() function to determine if the database server is processing an SQL request.
- In a signal-handler function, before a call to the longjmp() system function. Only use longjmp() in a signal-handler function if sqldone() returns zero (the database server is idle).
You might want to create a defined constant for the
-439 value to make your code more readable. For example, the following code fragment creates the SERVER_BUSY constant and then uses it to test the sqldone() return status:
Return Codes
0 | The database server is not currently processing an SQL request: it is idle. |
-439 | The database server is currently processing an SQL request. |
sqlexit()
The sqlexit() function terminates all database server connections and frees resources. You can use sqlexit() to reduce database overhead in programs that refer to a database only briefly and after long intervals, or that access a database only during initialization.
Syntax
Usage
Only call the sqlexit() function when no databases are open. If an open database uses transactions, sqlexit() rolls back any open transactions before it closes the database. The behavior of this function is similar to that of the DISCONNECT ALL statement. However, the DISCONNECT ALL statement fails if any current transactions exist. Use the CLOSE DATABASE statement to close open databases before you call sqlexit().If the application has only one implicit connection before it calls sqlexit(), execution of the next SQL statement or of the sqlstart() library function re-establishes an implicit connection to the default database server. If the application makes one or more explicit connections, you must issue a CONNECT statement before you execute any other SQL statements.
Return Codes
0 | The call to sqlexit() was successful. |
<0 | The call to sqlexit() was not successful. |
sqlsignal()
The sqlsignal() function enables, disables, or reenables signal handling of the signals that the ESQL/C library handles.
Syntax
- void sqlsignal(sigvalue, sigfunc_ptr, mode)
int sigvalue;
void (*sigfunc_ptr) (void);
short mode;
Usage
The sqlsignal() function currently provides handling only for the SIGCHLD signal. In some instances, defunct child processes remain after the application ends. If the application does not clean up these processes, they can cause needless use of process IDs and increase the risk that you run out of processes. This behavior is only apparent when the application uses pipes for client-server communication (that is, the nettype field of the sqlhosts file is ipcpip). You do not need to call sqlsignal() for other communication mechanisms (for example, a nettype of tlipcp).The mode argument of sqlsignal() determines the task that sqlsignal() performs, as follows:
- When you initialize signal handling with sqlsignal(), the ESQL/C library traps the SIGCHLD signal to handle the cleanup of defunct child processes. This initial call to sqlsignal() must occur at the beginning of your application, before the first SQL statement in the program. If you omit this initial call, you cannot turn on the signal-handling capability later in your program.
- If you want to have the ESQL/C library perform signal handling for portions of the program and your own code perform signal handling for other portions, you can take the following actions:
- To disable signal handling, call sqlsignal() with mode set to
1, at the point where you want your program to handle signals:
sqlsignal(-1, (void (*)()), 1); - To re-enable signal handling, call sqlsignal() with mode set to
2, at the point where you want the INFORMIX-ESQL library to handle signals:
sqlsignal(-1, (void (*)()), 2);
sqlstart()
The sqlstart() function starts an implicit default connection. An implicit default connection can support one connection to the default database server (that the INFORMIXSERVER environment variable specifies).
Syntax
Usage
ESQL/C provides the sqlstart() function for pre-Version 6.0 applications that can only support single connections. In this context, possible uses of sqlstart() are as follows:
- You only need to verify that the default database server is available but you do not intend to open a database. If the call to sqlstart() fails, you can check the return status to verify that the default database server is not available.
- You need to speed up the execution of the DATABASE statement when the application runs over a network. When you put the call to sqlstart() in an initialization routine, the application establishes a connection before the user begins interaction with the application. The DATABASE statement can then open the specified database.
- You do not know the name of the actual database to access, or your application plans to create a database. The call to sqlstart() can establish the implicit default connection and the application can later determine the name of the database to access or create.
When you call the sqlstart() function, make sure that the application has not yet established any connections, implicit or explicit. When the application has established an explicit connection, sqlstart() returns error -1811. If an implicit connection has been established, sqlstart() returns error -1802.
You can call this function several times before you establish an explicit connection, as long as each implicit connection is disconnected before the next call to sqlstart(). For information on disconnecting, see "Terminating a Connection". For more information on explicit and implicit connections, see "Establishing a Connection".
0 | The call to sqlstart() was successful. |
<0 | The call to sqlstart() was not successful. |
