# CHAPTER 5: Empress Variables

## 5.1 Introduction

The Empress Query Language maintains a list of character-string variables. Variables may be printed, new ones added, old ones removed, and their values changed and used.

Variables are of three types:

1. Alphanumeric variables, the names of which begin with a letter and contain letters and numbers.

2. Numeric variables, names of which range from "1" to "99".

3. System variables, a set of variables used for specific purposes by Empress.

Alphanumeric and numeric variables are described under the `SET` command in the Empress SQL: Reference.

The contents of a variable are referred to by placing a dollar sign ($) in front of the name. Where it is necessary to enter extra characters after a variable name, the variable name must be surrounded by braces, thus: `${VARIABLE}`. For example, suppose you have a file of data to go into the personnel table called `personnel_file`. If you wish to use the variable `p` to shorten typing as `personnel` when inserting data into `personnel`, and use:

       INSERT INTO $p FROM '$p_file';

you will get an error message because the variable `p_file` is not defined. Instead, you should type:

       INSERT INTO $p FROM '${p}_file';

in order to obtain the desired command: "`INSERT INTO personnel FROM personnel_file;`".

To prevent a dollar sign ($) from causing variable expansion, it must be doubled; i.e., `$$p` evaluates to the string `$p`. This applies anywhere in a string and not only for the beginning of each "word". Note that both the character used to obtain the value of a variable and the characters used as delimiters may be changed by setting the Empress system variable `MSQLVARCHARS`. To have`&` instead of `$` and square brackets instead of braces, use:

       SET MSQLVARCHARS TO &[];

Variables are set with the `SET` command and removed with the `UNSET` command. The value of variables is shown with the `SHOW` command.

## 5.2 Empress System Variables

Empress has a number of system variables which determine system defaults, such as the line continuation character, number of retrieves when trying to access locked tables, formatting of `SELECT` command output, and so on. These variables acquire values in one of two ways: they are set by Query Language commands during a work-session, or they are inherited from the operating system.

To set a system variable from the Query Language, use a command of the form:

       SET variable TO value;

where `variable` is the name of the system variable (which must all be in uppercase only), and `value` is its value. The `value` must be enclosed in quotes if it contains blanks, tabs, periods, colons, semicolons, slashes, or new lines.

### 5.2.1 Setting Variables

If a variable is set via a Query Language command, its value lasts only for the current work-session, and it must be re-set if you stop Empress. If a variable is set in the operating system, its value lasts as long as you are logged on to the operating system, and thus may last over several Empress work-sessions. Variables set in the operating system are also available to Empress 4GL and Empress Report Writer.

For UNIX:

  To set a variable from the UNIX shell use a `setenv` command in the C shell, or `export` command in the Bourne shell.

  For example, to set the variable `MSEDITOR` to "/usr/ucb/vi", the C shell command is:

         setenv MSEDITOR /usr/ucb/vi

  and the Bourne shell commands are:

         MSEDITOR=/usr/ucb/vi/
         export MSEDITOR

  If you wish to have permanent lists of Empress system variables which will be in force for every work-session, you may either:

  1. Place these in a UNIX file and set the variables from this file whenever you invoke Empress.

  2. Set the variables in your `.login` (C shell) or `.profile` (Bourne shell) files. Instructions for doing this may be obtained from the UNIX system documentation.
For Windows NT:

  To set a variable from the Windows NT environment, use the Set Environment command. For example, to set the variable `MSVALSEP` to "|", the Windows NT command is:

         set MSVALSEP=|

  You may also want to set some Empress system variables permanently. One way of doing this is to put the Empress system variables in your user environment variable list. Consult your system documentation for details.

### 5.2.2 List of Empress System Variables

A list of the system variables follows with a brief description of each.

Table 5-1: Path Specific System Variables

Variables | Description
`MSHELPPATH` | Directory for Empress help files.
`EMPRESSPATH` | Directory for Empress working files.
`MSNLSDB` | The complete name of the NLS database.

Table 5-2: General Purpose System Variables

Variables | Description
`MSDATEPIC` | Default date picture for reports and data entry.
`MSDISPLAYKATAKANA` | Specific to the Kanji (Japanese) version of Empress.
`MSDOLLAR` | Default format for dollar data types.
`MSEDITOR` | Editor used by `.zz` command and Empress 4GL.
`MSFILESOPEN` | Maximum number of files that will be opened by Empress.
`MSKEEPNONPRINTCHAR` | Flag to interpret non-printing characters.
`MSLANG` | Specifies the language in which you want Empress messages to be printed.
`MSLINECONT` | String used to continue lines.
`MSLOCKPLAN` | Provides lock usage information by Empress.
`MSNLSCODESET` | The name of the codeset appropriate to the keyboard/monitor you are using.
`MSNULLVALUE` | String to replace null values.
`MSPAGER` | System program for paging Query Language.
`MSPERMS` | Access permissions for Empress output files.
`MSPRINTER` | System program used to send output to a printer.
`MSSHELL` | System shell for shell escapes.
`MSQUERYPLAN` | Provides indices information used by Empress when evaluating any search strategy before going to the database for record retrievals.
`MSSORTBYPASS` | Flag to skip locked records during sorting.
`MSSORTSPACE` | Byte limit on space used during sorting.
`MSTMPDIR` | Directory where temporary files are created.
`MSTMPPFX` | Prefix used for temporary files.
`MSVALSEP` | String used to separate attribute values in dump files.
`MSVERSIONMESG` | Print Empress version on startup.
`MSWRAPMARGIN` | Controls line breaks and wrapping.

Table 5-3: Transaction Specific System Variables

Variables | Description
`MSTRANSCOMMENT` | Comment string for transactions.
`MSTRANSSYNC` | Flag to cause immediate write to file.
`MSTRANSTABLELOCK` | Flag to force table-level locking in transactions.
`MSTRANSUFNGFL` | Controls free record access.
`MSTRANSWARMPROTECT` | Flag to protect transactions from warm restart.

Table 5-4: Locking Specific System Variables

Variables | Description
`MSEXCLRETRY` | Number of retries for exclusive access to lock file.
`MSEXCLSLEEP` | Interval between retries for exclusive lock access.
`MSFILELOCKMAXPROCS` | Maximum number of processes which can access the Lock Manager in a lock file.
`MSFILELOCKNBUCKETS` | Number of hash buckets for a Lock Manager in a lock file.
`MSFILELOCKNLOCKS` | Maximum number of locks for a Lock Manager in a lock file.
`MSIAEXCLRETRY` | Number of exclusive access retries for Interactive Interface.
`MSIAEXCLSLEEP` | Exclusive access retry interval for Interactive Interface.
`MSIALOCKRETRY` | Number of lock retries for Interactive Interface.
`MSIALOCKSLEEP` | Lock retry interval for Interactive Interface.
`MSINDEXRETRY` | Number of retries to lock an index.
`MSINDEXSLEEP` | Interval between retries to lock an index.
`MSLOCKRETRY` | Number of retries to actually make a lock entry.
`MSLOCKSLEEP` | Interval between retries to actually make a lock entry.

Table 5-5: Query Language Specific System Variables

Variable | Description
`MSQLAUTOPAGE` | Flag to send all command output to a paging program.
`MSQLCMDSAVE` | Number of commands saved by history mechanism.
`MSQLCOUNT` | Flag to display number records selected, updated, deleted.
`MSQLECHO` | Controls commands echoing.
`MSQLONELINE` | Indicates that a new line terminates a command.
`MSQLPROMPT1` | Primary Empress prompt.
`MSQLPROMPT2` | Secondary Empress prompt.
`MSQLTRANSACTION` | Each command is a transaction and may be canceled.
`MSQLVARCHARS` | Characters used in Empress variable notation.

Table 5-6: Select Formatting Specific System Variables

Variables | Description
`MSQLGCHARWIDTH` | Column width for non-parametric character values.
`MSQLGDATEWIDTH` | Column width for non-parametric date values.
`MSQLGDECIMALWIDTH` | Column width for non-parametric decimal values.
`MSQLGFLOATWIDTH` | Column width for non-parametric float values.
`MSQLGINTEGERWIDTH` | Column width for non-parametric integer values.
`MSQLSELBOX` | Puts a box around the output.
`MSQLSELCOLSEP` | Column separator.
`MSQLSELGROUPCOLCROSS` | Group separator crossing column.
`MSQLSELGROUPSEP` | Group separator.
`MSQLSELHEAD` | Flag to print/suppress headers.
`MSQLSELHEADCOLCROSS` | Heading crossing column.
`MSQLSELHEADSEP` | Separates headers from rows.
`MSQLSELKEEPDUPLICATE` | Flag to keep duplicate group values.
`MSQLSELROWCOLCROSS` | Row crossing column.
`MSQLSELROWSEP` | Row separator.
`MSQLSELTRUNCATE` | Flag to truncate long lines.
`MSQLSELWARN` | Print warning if function encounters null argument.

Table 5-7: Operating System Specific System Variables

Variables | Description
`MSGETPW` | Use getpw instead of getwuid system call to obtain the user id. This is for backward compatibility reasons.
`MSGCWDSIGCHLDRESET` | Resets the signal for some operating system call getcwd.

Table 5-8: Empress Report Writer Specific System Variables

Variables | Description
`MSMWNULLOK` | Suppress error on printing null.
`MSPAGELENGTH` | Default page length for reports.
`MSPAGEWIDTH` | Default page width for reports.