2.4 Sedna Terminal

se_term is an interactive terminal to Sedna. It is a C application that uses Sedna C API (see “Sedna Programmer’s Guide”) to work with Sedna. It enables you to open a session to one of the Sedna database, type in queries interactively, issue them to the database and see the query results. Alternatively, input can be from a file, or a single query can be passed for execution as a command line parameter. In addition, it provides a number of meta-commands.

The usage of the se_term is as follows:

-help or --help provides the exhaustive information about the se_term.

-version option allows getting the version of the se_term.

-file option specifies the name of the file that contains any number of queries and meta-commands. se_term uses this file as the source of queries and meta-commands instead of reading them interactively. se_term executes the queries and meta-commands from file consequently and exit. XQuery and XUpdate statements must be delimited with ampersand symbol at the end.

For example, the following script turns off autocommit mode, then executes a number of XQuery statements and finally commits transaction explicitly:

-output option specifies a filename of a file to redirect all se_term output to.

-query option specifies the query to execute.

-echo option specifies if se_term output needs to be displayed or not. If the echo is on, the output is displayed, if the echo is off, the output is not displayed. By default, the echo option is set to on when using se_term in an interactive mode, and the echo option is set to off when using se_term in a batch mode (running queries/commands from file).

-show-time option allows getting the time of the latest query execution. If used with the -query option provides the time of the specified query execution; if used with the -file option provides the time of the execution of the last query in file.

-debug option specifies session debug mode. If -debug option is on, statements of this session are executed in a debug mode. If -debug option is off, statement of this session are executed in normal (not debug) mode. For details see ”Debug Facilities” section of the Sedna Programmer’s Guide.

-host option specifies the name of the machine with Sedna DBMS running. If not used, default value localhost is used.

-port option specifies the TCP port on which Sedna server is listening to client applications. If omitted, port number 5050 is used by default.

-name and -password options specify the user name and the password. If omitted, connects as a predefined user SYSTEM with password MANAGER.

dbname is a required argument. It specifies the name of the database to connect to.

When se_term is used in the interactive mode it takes in query/update statements and meta-commands from stdin. To execute a query/update statement type in a statement and use ampersand and line feed to terminate it (&’\n’ terminates the query). An end of line does not terminate the query, thus queries can be spread over several lines for clarity. Alternatively, se_term can be used in a batch mode, then query/update statements and meta-commands are taken from the input file specified by the -file option. By default, se_term session is run in the autocommit mode, that is, each statement is run in a separate transaction. To switch to a manual-commit mode use unset meta-command (se_term meta-commands are described below in this section). If the statement executed successfully, the results are displayed on the screen.

se_term returns 0 to the shell if it finished normally, 1 if a fatal error of its own (out of memory, file not found) occurs, 2 if the connection to the Sedna server went bad and the session is not interactive, and 3 if a statement or a command failed and the variable ON_ERROR_STOP was set (se_term internal variables are described below in this section).

Meta-commands are commands for se_term that processed by the se_term itself. A meta-command begins with a backslash and that differs it from the query/update statements. Thus, the format of se_term meta-command is the backslash, followed immediately by a command, with no ampersand at the end. se_term takes in the following meta-commands:

set and unset meta-commands are used for managing se_term internal variables. Notice, that there are aliases for some commands. So you can write \ac instead of \set AUTOCOMMIT. There are following se_term internal variables:

AUTOCOMMIT (\ac for set, \nac for unset) - when set, autocommit mode is on. When unset manual-commit mode is on. AUTOCOMMIT is set by default.

ON_ERROR_STOP - when set, se_term returns with the code 3 when statement or meta-command fails. When unset se_term processing continues, unless it is the connection failure.

DEBUG - when set, session debug mode is on. When unset, session debug mode is off. See ”Debug Facilities” section of the Sedna Programmer’s Guide for details.

TRANSACTION_READ_ONLY (\ro for set, \upd for unset) - transactions are run as READ-ONLY when set. When unset, transactions are run as UPDATE-transactions. By default transactions are run as UPDATE - transactions.

LOG_LESS_MODE (\ll for set, \fl for unset) - when set, every following bulkload will be less logged and checkpoint will be made on every commit. When unset, every following bulkload will be fully logged. By default transactions are run in full log mode. This option should be used with care (see details about SEDNA_LOG_AMOUNT connection attribute in “Sedna Programmer’s guide”).

QUERY_TIMEOUT=<time in seconds> - when set, every query execution will be dropped on server if it lasts longer than timeout set. By default there is no any timeout set (query is executed as long as needed).

set? - provides help on se_term internal variables.