.
Eloquence B.08.00 contact contact

Documentation / dbctl utility

The Eloquence dbctl utility

 
.
  The dbctl utility allows access to a running eloqdb process. It is used to control server operation or retrieve database server status information. The list of available commands and options depends on the version of the target database server.
An alternative to request status information is to use the HTTP status of the eloqdb server process. After enabling the "ServiceHttp" option in the eloqdb configuration file, a web browser can be used to monitor the current status of the database server.

Contents


Usage

dbctl [options] command [arg ...]

options:
 -help        - show usage (this list)
 -u name      - user name
 -p pswd      - password
 -h host      - host name or address
 -s service   - service name or port number
 -d flags     - debug flags

commands:
 help         - show list of available commands
 help command - show usage of specific command

Options

-h host
Name or IP address of the system running the eloqdb 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 eloqdb 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
usage: shutdown [number_of_seconds|CANCEL]


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

For example:

$ dbctl -u dba shutdown
Shutting down now.

Note that "dbctl shutdown" does NOT wait until the requested eloqdb server shutdown has completed and is thus NOT always suitable for scripting, for example. In cases where you need to be sure the server has been stopped, before continuing, you must use the "eloq8 stop" command instead.


backup {start|stop|status}
Enter or leave on-line backup mode. dba authorization is required. When eloqdb 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 eloqdb 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 eloqdb 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.

For example:

$ dbctl -u dba backup start
On-line backup mode has been started.

Please refer to the database backup document for more information.


list {session|dbopen|db|lock|thread} [/notitle|/count] [argument] [filter ...]
The list command returns status information from the eloqdb 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.

With eloqdb patch level PE80-0906080 or newer, one or more filter criteria may be specified to select a subset of the dbctl list results. If multiple filter criteria are specified, they are combined with an implicit AND operator.

Filter criteria are specified using a field name, an operator and a value. Valid operators for numeric fields are "=", "<>", as well as ">", ">=", "<" and "<=". Valid operators for text fields are "=" and "<>". For text fields, the value may include * and ? as "wildcard" characters.

For example:

 $ dbctl list session "user=root"
 $ dbctl list dbopen toydb "pname=*query3k*"
 $ dbctl list lock "db=toydb" "status=blocked"
 $ dbctl list thread "st=W" "time>=30"

If the /count option is specified, only the number of matching entries is shown.

list session
Provide a list of all active database sessions. The following information is displayed:
TID eloqdb thread id associated with this session
IP ADDR IP address and port number of the client
User / Login User login on the client system and database login of the session
Process information Information about the invoking process is output on a separate line

For example:

$ dbctl list session
TID  IP ADDR              User / Login
---- -------------------- -----------------------
   9 127.0.0.1:54345      mike / public
     uid{102}pid{17995}pname{query3k}
  10 127.0.0.1:54382      root / public
     uid{0}pid{18010}pname{query3k}
  11 127.0.0.1:54480      lars / public
     uid{233}pid{19641}pname{dbctl list session}

Valid field names for filter criteria are:
tid, ip (or ipaddr), user, login, uid, pid, pname, info.

list dbopen database
Provide a list of all users that opened a specific database. The following information is displayed:
TID eloqdb thread id associated with this session
IP ADDR IP address and port number of the client
M DBOPEN mode
User / Login User login on the client system and database login of the session
Process information Information about the invoking process is output on a separate line

For example:

$ dbctl list dbopen sample
TID  IP ADDR              M   User / Login
---- -------------------- --- -----------------------------
   9 127.0.0.1:54345      1   mike / public
     uid{102}pid{17995}pname{query3k}
  10 127.0.0.1:54382      9   root / public
     uid{0}pid{18010}pname{query3k}

NOTE: If the same database has been opened multiple times in the same session using different modes, only the first DBOPEN mode is displayed.

Valid field names for filter criteria are:
tid, ip (or ipaddr), mode, user, login, uid, pid, pname, info.

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
WrSngl how often the database is opened in mode 4

For example:

$ dbctl list db
Database         Ref  WrShrd WrExcl RdShrd RdExcl WrSngl
---------------- ---- ------ ------ ------ ------ ------
sample              2      2      0      0      0      0
Valid field names for filter criteria are:
db (or database), ref, wrshrd, wrexcl, rdshrd, rdexcl, wrsngl.

list lock
Provide a list of all data base locks. The following information is displayed:
TID eloqdb thread id associated with this session
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)

For example:

$ dbctl list lock
TID Database         DBID Status  Mode Qualifier
--- ---------------- ---- ------- ---- ---------------
  9 sample              1 GRANTED    6 expression
set=1 item=@ (effective set lock)

Valid field names for filter criteria are:
tid, db (or database), dbid, stat (or status), mode, qual (or qualifier).

list thread
Provide a list of all database threads. The following information is displayed:
TID eloqdb 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.
Time Number of seconds the thread was blocked or idle
Sched Number of times the thread was active
Blocked Number of times the thread was waiting
Name Thread name. This is the IP address and port number in case the thread is associated with a user session.

For example:

$ dbctl list thread
TID  ST WCHAN              Time     Sched    Blocked  Name
---- -- ------------------ -------- -------- -------- --------------------
   1 R                            0   790714        0 vtimer
   2 R                            0        0        0 event
   3 S                            0   262115        0 timer
   4 S                       262115        0        0 shutdown
   5 S                       262115        0        0 ps
   6 S                            0   524199       10 syncer
   7 R                            0       73        0 http
   8 S                           35     4406       10 checkpoint
   9 S                          329       28        0 127.0.0.1:50002
  10 S                           26       58        0 127.0.0.1:46116
  11 R                            0        7        0 127.0.0.1:46120
Valid field names for filter criteria are:
tid, st, wchan, time, sched, blocked, name, blocked_on.


cancelthread threadid
The cancelthread option can be used by the administrator to unblock a user session that 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 -u dba cancelthread 25
Thread 25 has been cancelled.


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 -u dba killthread 25
Thread 25 has been notified.


syncmode {on [msec]|off|status}
Enable or disable the sync mode of the running eloqdb process. dba authorization is required. If enabled, the syncer journal flush interval in milliseconds may optionally be specified.
If omitted, the interval defaults the previously active value.

For example:

$ dbctl -u dba syncmode off
Sync mode set to OFF.


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. If the dbstore target is a disk file, it will be created with permissions that restrict access to the UID used for running the database server.

For example:

$ dbctl -u dba dbstore payrol backup/payrol.bkup
Database "payrol" has been stored to "/data/backup/payrol.bkup".

$ dbctl -u dba dbstore payrol tape
Database "payrol" has been stored to "/dev/rmt/c1t0d0BEST".

Please refer to the database backup document for more information.


dbrestore [/info] [/all] [/nouser] [/force] [/nice] 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 the optional /all argument is present, the association between database permission groups and server users ("sysmember") is retained. Usage of the /all argument is safe if the database environment where the database is restored is the same or has identical server users as the environment where the database was stored. Specifying the /nouser option has the same effect as omitting the /all option.

If the optional /force argument is present, the database may even be restored while the server is in online backup mode. By default, dbrestore requests are rejected during online backup mode because of the possible negative impact on performance and log volume size.

If the optional /nice argument is specified, the server attempts to mitigate the performance impact on concurrent client sessions and the operating system buffer cache at the cost of slowing down the dbrestore progress.

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 -u dba dbrestore /all backup/payrol.bkup
Database "PAYROL" has been restored from "/data/backup/payrol.bkup".

$ dbctl -u dba dbrestore /info tape
Created: Wed Nov 17 16:09:28 2004
Archive version: 1
Volume revision: HP-UX A.06.00
Platform       : HPUX
Character set  : hp-roman8
Database name  : PAYROL

$ dbctl -u dba dbrestore tape
Database "PAYROL" has been restored from "/dev/rmt/c1t0d0BEST".

Please refer to the database backup document for more information.


forwardlog {enable|disable|restart|changelog|status}
The dbctl forwardlog command is used to control forward-logging. dba authorization is required.

If forward-logging is disabled the server stops writing to the forward-log, for example to avoid that the forward-log quickly fills up the available disk space during a dbimport or dbrestore.

The enable command is used to reenable a previously disabled forward-logging. The creation of the new forward-log is delayed until the next on-line backup because a forward-log requires a backup as a starting point.

The restart command may be used to manually begin a new forward-log. The changelog command is a synonym for the restart command.

For example:

$ dbctl -u dba forwardlog status
Forward-logging is enabled.
Forward-log is '/data/db/db-forward-22-1.log'.

Please refer to the forward-logging document for more information.


bimport [/v] [/a] [/n] [/f] database set bexp_file
The dbctl bimport command allows to efficiently import binary data set export files.

A binary import retains any chain information and detail set record numbers. The affected data set is erased before the import file is processed.

If the optional /v argument is specified, additional information is displayed. Specifying /v twice (/v /v) displays progress information.

If the optional /f argument (force) is present, the database may even be imported while the server is in online backup mode. By default, bimport requests are rejected during online backup mode because of the possible negative impact on performance and log volume size.

For example:

$ dbctl bimport /v /v sample 1 $PWD/SAMPLE.001.exb

P0: server: /data/tmp/SAMPLE.001.exb: 1355 records expected
P0: server: /data/tmp/SAMPLE.001.exb: completed, 1355 records processed

Please refer to the database migration document for more info.


logfile log_file_name
The dbctl logfile command changes the logfile of the running eloqdb process. dba authorization is required. 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. You may not specify a file that already exists.

For example:

$ dbctl -u dba logfile /tmp/eloqdb.log
Log file has been set to "/tmp/eloqdb.log".


logflags log_flags
The dbctl logflags command changes the logging options of the running eloqdb process. dba authorization is required.

For example:

$ dbctl -u dba logflags "*1E2"
Log flags have been set to "*1E2".


statfile [FileName|DISABLED]
The dbctl statfile command is used to display the current value of [server] StatFile or specify a new value.

If used without additional file name argument this returns the current value for [server] StatFile.

When a file name is present, it specifies a new value for [server] StatFile. If DISABLED is specified, the [server] StatFile is unconfigured and no longer used. Otherwise an absolute file name must be specified. The file may not exist. When a file name is specified, dba capabilities are required.

For example:

$ dbctl statfile
statfile "DISABLED"

$ dbctl -u dba statfile /tmp/server.stats
statfile set to "/tmp/server.stats".

Please refer to the server statistics document for more information.


statfileflags [flags]
The dbctl statfileflags command is used to display the current value of [server] StatFileFlags or specify a new value.

If used without additional flags argument this returns the current value for [server] StatFileFlags.

When a flags argument is present, it specifies a new value for [server] StatFileFlags. An empty argument may be used to reset the flags. When a flags argument is specified, dba capabilities are required.

The following flags are supported:

s - (single line)
causes the values to be formatted into a single line. Values are separated by a space and no descriptive text is present.
a - (append)
causes additional values to be appended to the file instead of replacing the previous content.
t - (local timezone)
causes the timestamp to include the offset of the local timezone from UTC. If not present, the timestamp value denotes UTC. This flag allows to use the timestamp value with DSI (MeasureWare) on HP-UX without requiring a conversion.

For example:

$ dbctl statfileflags
statfileflags ""

$ dbctl -u dba statfileflags sat
statfileflags set to "sat"

$ dbctl -u dba statfileflags ""
statfileflags set to ""

Please refer to the server statistics document for more information.


sessionstatfile [FileName|DISABLED]
The dbctl sessionstatfile command is used to display the current value of [server] SessionStatFile or specify a new value.

If used without additional file name argument this returns the current value for [server] SessionStatFile.

When a file name is present, it specifies a new value for [server] SessionStatFile. If DISABLED is specified, the [server] SessionStatFile is unconfigured and no longer used. Otherwise an absolute file name must be specified. The file may not exist. When a file name is specified, dba capabilities are required.

For example:

$ dbctl sessionstatfile
sessionstatfile "DISABLED"

$ dbctl -u dba sessionstatfile /tmp/session.stats
sessionstatfile set to "/tmp/session.stats"

Please refer to the server statistics document for more information.


sessionstatmode [ 0 | 1 | seconds ]
The dbctl sessionstatmode command is used to display the current value of [server] SessionStatMode or specify a new value.

If used without additional mode argument this returns the current value for [server] SessionStatMode.

When a mode argument is present, it specifies a new value for [server] SessionStatMode. When a mode argument is specified dba capabilities are required.

The following values are supported:

0 - (zero)
The SessionStatFile is disabled
1 - (one)
A log entry is written to the SessionStatFile when a session ends.

Any other value is understood to specify an interval (in seconds) after which an entry is logged to the SessionStatFile in addition to the entry that is logged after the session ends. The specified value must be at least 60 seconds.

For example:
$ dbctl sessionstatmode
sessionstatmode 0

$ dbctl -u dba sessionstatmode 1
sessionstatmode set to 1

Please refer to the server statistics document for more information.


replication {STOP|STATUS}
The dbctl replication status command may be used to obtain replication status information from a master or slave server. Output includes server role, forward-log status and most recently processed checkpoint. For a slave server it also shows whether replication is active or inactive.

The dbctl replication stop command may be used on a slave server to disconnect an active replication session. dba authorization is required. This is equivalent to performing a "dbctl killthread" on the TID of the respective replication session.

For example:

$ dbctl replication status
Server is configured as MASTER
Last checkpoint is 7-1.4318 (2008-10-16 13:20:32)
Forward-logging is enabled
Forward-log is '/fwlog/fw-7-1.log'

$ dbctl -h slave_host -s slave_port replication status
Server is configured as SLAVE
Replication is active
Last checkpoint is 7-1.4318 (2008-10-16 13:20:32)
Forward-logging is enabled
Forward-log is '/slave/fwlog/fw-7-1.log'

$ dbctl -h slave_host -s slave_port -u dba replication stop
Replication thread 9 has been notified.

Please note:

  • The "Replication is active" status on the slave server replication status indicates that a dbrepl process is connected. It does not indicate if the dbrepl processes is making any progress or is blocked. A "Replication is inactive" status would indicate that no dbrepl process is connected to the slave server.

  • The slave server status displays checkpoint timestamps as received from the master server, i.e. when the respective checkpoint occured on the master, not when it was finally applied on the slave. This info may be helpful in cases where replication has been stopped or is processing backlog during "catch up" phases.

  • If the master server is idle (no database opened) the slave server checkpoint timestamp is not updated. The master server does not record its checkpoints in the fwlog file if there is no user activity. Consequently, the last replicated checkpoint timestamp on the slave server is not updated.

Please refer to the server replication document for more information.


Change History

Revision 2009-06-08

  • The "dbctl list" command was enhanced to allow the use of filter criteria as well as the "/count" option with eloqdb server patch PE80-0906080 or newer.

 
 
.
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision:  2012-05-25  
  Copyright © 2006-2009 Marxmeier Software AG