Eloquence B.07.00 - Database

The dbctl utility

The dbctl utility allows access to a running eloqdb6 process. It is used to control server operation or retrieve database server status information.
An alternative to request status information is to use the HTTP status of the eloqdb6 server process. After enabling the HTTP status a web browser can be used to monitor the current status of the database server.

Usage:

dbctl [-h hostname] [-s service] [-u login] [-p password] command [args]

Options:

-h host

Name or IP address of the system running the eloqdb6 server. The default is the local system (localhost). The -h option also accepts a host:service argument to specify a host name and service.

-s service

Service name or port number the eloqdb6 process is listening on. The default is eloqdb.

-u login

The login name to access the database. dbctl by default uses the user id "public". The default user name and password can be configured with the EQ_DBUSER and EQ_DBPASSWORD environment variables.

-p pswd

The password for the given database login.

Commands:

help [command]

Ask the server to provide a list of supported commands. If the optional command argument is specified, syntax of the specified command is displayed.

For example:

 dbctl help shutdown

shutdown [#seconds|cancel]

Shutdown the eloqdb6 server. dba authorization is required. In addition, a shutdown delay (in seconds) can be specified to schedule the shutdown of the eloqdb6 server process at a later time. The shutdown cancel operation can be used to cancel a previously scheduled shutdown.

backup {start|stop}

Enter or leave on-line backup mode. dba authorization is required. When eloqdb6 enters on-line backup mode all changes to the data volume(s) are redirected to the log volume(s) and the data volume(s) are guaranteed to be consistent and not to change. The data volume(s) can then be backed up by a backup tool (e.g. fbackup or tar).
When the on-line backup mode is stopped, all pending data is written to the data volume(s).

NOTE: The eloqdb6 performance is reduced in on-line backup mode and the log volume must provide space for all committed transactions during the on-line backup period.

In case the eloqdb6 server is shut down during on-line backup mode (or a failure occurs) the data volume(s) will be updated automatically when the server is restarted.

list {session|db|lock|thread} [notitle]

The list command returns status information from the eloqdb6 server process (similar to using the HTTP status interface). However the dbctl is easier to use from a script file. The list command is allowed with any valid server login.

If the notitle option is specified, any header lines are omitted.

list session

Provide a list of all active database sessions. The following information is displayed:

Session	Internal session id
TID	eloqdb6 thread id associated with this session
Host	Host name or IP address the client is running on
IP ADDR	IP address and port number of the client
Platform	Client platform
User	User login on the client system and database login of the session

Example output:

 Session    TID Host / IP ADDR       Platf User / Login
 ---------- --- -------------------- ----- --------------------
 403f9c70     8 127.0.0.1            HPUX  mike
        	127.0.0.1:61774            public

list db

Provide a list of all opened data bases. The following information is displayed:

Database	data base name
Ref	how often the database is accessed
WrShrd	how often the database is opened in mode 1
WrExcl	how often the database is opened in mode 3
RdShrd	how often the database is opened in mode 9
RdExcl	how often the database is opened in mode 8

Example output:

 Database         Ref  WrShrd WrExcl RdShrd RdExcl
 ---------------- ---- ------ ------ ------ ------
 db                  1      1      0      0      0

list lock

Provide a list of all data base locks. The following information is displayed:

Session	eloqdb6 session identifier
Database	database name
DBID	internal database instance id
Status	lock status (GRANTED/BLOCKED)
Mode	lock mode (rounded to next even mode)
Qualifier	lock qualifier (base/set/expression)

Example output:

 Session    TID Database         DBID Status  Mode Qualifier
 ---------- --- ---------------- ---- ------- ---- ---------------
 0x81db540    7 db                  1 GRANTED    6 expression
 set=1 item=@ (effective set lock)

list thread

Provide a list of all database threads. The following information is displayed:

Session	Internal session id
TID	eloqdb6 thread id associated with this session
ST	Current thread status. R - Runnable S - Suspended or Idle W - Blocked (interruptable)
WCHAN	Specifies the object the thread is waiting for. Empty if the thread is active or idle.
Blocked	Number of seconds the thread is waiting.
Sched	Number of times the thread was active
Name	Thread name. This is the IP address or host name in case the thread is associated with a user session.

Example output:

 Session    TID ST WCHAN      Blocked  Sched    Name
 ---------- --- -- ---------- -------- -------- --------------------
 internal     1 R                    0   109618 idle                
 internal     2 S               238223        1 shutdown            
 internal     3 S               238223        1 ps                  
 internal     4 S                    3    47646 syncer              
 internal     5 S               238223        1 http                
 internal     6 S                   14    57861 tio monitor         
 internal     7 S                   23     4478 checkpoint          
 403f9c70     8 S                   14        6 127.0.0.1           
 403fdfa0     9 R                    0        6 127.0.0.1           

cancelthread threadid

The cancelthread option can be used by the administrator to unblock a user session which is waiting for a lock. The session is specified with its 'tid' (thread identifier) which can be obtained with either 'dbctl list thread' or the http status display: A thread with a 'W' state (in the 'ST' column) can be signaled or killed.

cancelthread causes the blocking statement to return with status -35 (secondary status -1) in case of a blocking DBLOCK.

For example:

 dbctl cancelthread 25

killthread threadid

The killthread option can be used by the administrator to terminate a user session.

The session is specified with its 'tid' (thread identifier) which can be obtained with either 'dbctl list thread' or the http status display: A thread with a 'W' state (in the 'ST' column) can be signaled or killed.

killthread terminates the entire session by closing the server connection to the client process. The application will fail with a -700 status for the current database request or the next database operation in case it is idle.

For example:

 dbctl killthread 25

dbstore database target

The dbctl dbstore command transfers a single database to the target "device" which must be defined in the server configuration file. In order to store a database, database admin (dadmin) or server admin (dba) capabilities are required.

The target specification is either the name of a configured server device or the name of a server device and a filename separated by a slash.

For example:

 dbctl dbstore payrol backup/payrol.bkup
 dbctl dbstore payrol tape

Please refer to the database backup document for more information.

dbrestore [/info] source [new_database_name]

The dbctl dbrestore command restores a single database from a source device which must be defined in the server configuration file. The database may not already exist. Server admin (dba) capabilities are required in order to restore a database.

The source specification is either the name of a configured server device or the name of a server device and a filename separated by a slash.

If the optional /info argument is present, information on the archive is returned and the archive is not restored. The header of the specified archive is displayed.

If a new_database_name is specified, its length must not exceed 64 characters, it must not begin with '/' and must not contain any space characters.

For example:

 dbctl dbrestore backup/payrol.bkup
 dbctl dbrestore tape
 dbctl dbrestore tape info

Please refer to the database backup document for more information.

logfile log_file_name

The dbctl logfile command changes the logfile of the running eloqdb6 process. Currently only files are supported as a log target. The file name should be provided with an absolute path since the current directory of the server process is usually unknown.

For example:

 dbctl logfile /tmp/eloqdb6.log

logflags log_flags

The dbctl logflags command changes the logging options of the running eloqdb6 process.

For example:

 dbctl logflags "*1"