Changes:

The statfile, statfileflags, sessionstatfile and sessionstatmode options were added with patch PE71-0704110.

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

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
usage: shutdown [number_of_seconds|CANCEL]

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.

For example:

$ dbctl -u dba shutdown
Shutting down now.

Note that "dbctl shutdown" does NOT wait until the requested eloqdb6 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 "eloq6 stop" command instead.

backup {start|stop|status}

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.

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]

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:

TID	eloqdb6 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}

list dbopen database

Provide a list of all users that opened a specific database. The following information is displayed:

TID	eloqdb6 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.

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

list lock

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

TID	eloqdb6 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)

list thread

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

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.

For example:

$ dbctl list thread
TID ST WCHAN      Blocked  Sched    Name
--- -- ---------- -------- -------- --------------------
  1 R                    0   109618 idle                
  2 S                    0   355514 timer
  3 S               238223        1 shutdown            
  4 S               238223        1 ps                  
  5 S                    3    47646 syncer              
  6 S               238223        1 http                
  7 S                   14    57861 tio monitor         
  8 S                   23     4478 checkpoint          
  9 S                   14        6 127.0.0.1           
 10 S                   41       22 127.0.0.1           
 11 R                    0        6 127.0.0.1           

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 eloqdb6 process. dba authorization is required. If enabled, the syncer journal flush interval in milliseconds may optionally be specified. If omitted, the interval defaults to 500 milliseconds.

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 information.

logfile log_file_name

The dbctl logfile command changes the logfile of the running eloqdb6 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 logfile /tmp/eloqdb6.log
Log file has been set to "/tmp/eloqdb6.log".

logflags log_flags

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

For example:

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

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 [mode]

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.

Note that 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.

Please refer to the server replication document for more information.