Administrative API Reference

sqlefrce - Force Application

Forces local or remote users or applications off the system to allow for maintenance on a server.

Attention: If an operation that cannot be interrupted (RESTORE DATABASE, for example) is forced, the operation must be successfully re-executed before the database becomes available.

Scope

This API affects all nodes that are listed in the $HOME/sqllib/db2nodes.cfg file.

In a partitioned database environment, this API does not have to be issued from the coordinator node of the application being forced. This API can be issued from any node (database partition server) in the partitioned database environment.

Authorization

One of the following:

Required Connection

Instance. To force users off a remote server, it is necessary to first attach to that server. If no attachment exists, this API is executed locally.

Version

sqlenv.h

C API Syntax 



/* File: sqlenv.h */
/* API: Force Application */
/* ... */
SQL_API_RC SQL_API_FN
  sqlefrce (
    long NumAgentIds,
    sqluint32 * pAgentIds,
    unsigned short ForceMode,
    struct sqlca * pSqlca);
/* ... */

Generic API Syntax 



/* File: sqlenv.h */
/* API: Force Application */
/* ... */
SQL_API_RC SQL_API_FN
  sqlgfrce (
    struct sqlca * pSqlca,
    unsigned short ForceMode,
    sqluint32 * pAgentIds,
    long NumAgentIds);
/* ... */

API Parameters

pSqlca
Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

ForceMode
Input. An integer specifying the operating mode of the FORCE APPLICATION API. Only the asynchronous mode is supported. This means that FORCE APPLICATION does not wait until all specified users are terminated before returning. It returns as soon as the API has been issued successfully, or an error occurs. As a result, there may be a short interval between the time the FORCE APPLICATION call completes and the specified users have been terminated.

This parameter must be set to SQL_ASYNCH (defined in sqlenv).

pAgentIds
Input. Pointer to an array of unsigned long integers. Each entry describes the agent ID of the corresponding database user. To list the agent IDs of the active applications, use db2GetSnapshot - Get Snapshot.

NumAgentIds
Input. An integer representing the total number of users to be terminated. This number should be the same as the number of elements in the array of agent IDs.

If this parameter is set to SQL_ALL_USERS (defined in sqlenv), all users are forced. If it is set to zero, an error is returned.

REXX API Syntax 



FORCE APPLICATION {ALL | :agentidarray} [MODE ASYNC]

REXX API Parameters

ALL
All applications will be disconnected from their database connection.

agentidarray
A compound REXX host variable containing the list of agent IDs to be terminated. In the following, XXX is the name of the host variable:

XXX.0
Number of agents to be terminated

XXX.1
First agent ID

XXX.2
Second agent ID

XXX.3
and so on.

ASYNC
The only mode currently supported means that FORCE APPLICATION does not wait until all specified applications are terminated before returning.

Sample Programs

C
\sqllib\samples\c\dbstop.sqc

COBOL
\sqllib\samples\cobol\dbstop.sqb

REXX
\sqllib\samples\rexx\dbstop.cmd

Usage Notes

db2stop cannot be executed during a force. The database manager remains active so that subsequent database manager operations can be handled without the need for db2start.

To preserve database integrity, only users who are idling or executing interruptible database operations can be terminated.

After a FORCE has been issued, the database will still accept requests to connect. Additional forces may be required to completely force all users off.

The database system monitor functions are used to gather the agent IDs of the users to be forced. For more information, see the System Monitor Guide and Reference.

When the force mode is set to SQL_ASYNCH (the only value permitted), the API immediately returns to the calling application.

Minimal validation is performed on the array of agent IDs to be forced. The user must ensure that the pointer points to an array containing the total number of elements specified. If NumAgentIds is set to SQL_ALL_USERS, the array is ignored.

When a user is terminated, a ROLLBACK is performed to ensure database consistency.

All users that can be forced will be forced. If one or more specified agent IDs cannot be found, sqlcode in the sqlca structure is set to 1230. An agent ID may not be found, for instance, if the user signs off between the time an agent ID is collected and sqlefrce is called. The user that calls this API is never forced off.

Agent IDs are recycled, and are used to force applications some time after being gathered by the database system monitor. When a user signs off, therefore, another user may sign on and acquire the same agent ID through this recycling process, with the result that the wrong user may be forced.

See Also

sqleatin - Attach

sqledtin - Detach

sqlepstp - Stop Database Manager

db2GetSnapshot - Get Snapshot.

[ Top of Page | Previous Page | Next Page ]