CHAPTER 3: Empress System Variables

#	(c) Copyright	Empress Software Inc.  1983, 2006

MSPATHNAMES=
	MSHELPPATH="${EMPRESSPATH}/rdbms/help"
	MSNLSFILE="${EMPRESSPATH}/common/nls/nlsfile_"

# Empress 4GL paths

	MSTERMDB="${EMPRESSPATH}/rdbms/4gl/termdb"
	MSAPFMDB="${EMPRESSPATH}/rdbms/4gl/apfmdb"
	MS4GLPSHEADER="${EMPRESSPATH}/rdbms/4gl/header.ps"

# Empkill log file
	MSKILLLOGDIR="${EMPRESSPATH}/rdbms/spool/log"

# Cray Empqdel log file
	MSCRAYQDELLOGDIR="${EMPRESSPATH}/rdbms/spool/log"

# Empress GUI path
	MSGUIDB="${EMPRESSPATH}/rdbms/gui/empguidb"
	MSGUIDEFCOLORFILE="${EMPRESSPATH}/rdbms/gui/colortab"

# Memory Mapped file directory
# for the platform which uses mmap.
	MSSHAREDMEMORYDIR="${EMPRESSPATH}/rdbms/spool/shm"

MSPATHNAMESEND=

# general

MSBULKSEGMENTSIZE=
MSCASEINSENSITIVE=\
  [SYS_OS_WIN32]		X
  [ALL]
MSDATELIMIT=1950
MSDATEPIC="dd aaaaaaaaa yyyy"
MSDDLTRANS=X
MSDISPLAYKATAKANA=
MSDOLLAR=.,*$
MSEDITOR=vi
MSFILESOPEN=\
  [SYS_OS_UNIX_HPUX_64]		250
  [SYS_OS_UNIX_HPUX]		150
  [SYS_OS_UNIX_IRIX]		150
  [SYS_OS_UNIX_SOLARIS]		200
  [SYS_OS_UNIX_LINUX_COBALT]	200
  [SYS_OS_UNIX_LYNX]		50
  [SYS_OS_UNIX_SCO]		88
  [ALL]				250
MSFORCEPLOCK=
MSGETPW=
MSINDEXLISTCUTOFF=100
MSINDEXLISTCUTOFFMIN=0
MSINDEXSORTCUTOFF=3
MSKEEPNONPRINTCHAR=
MSLANG=
MSLINECONT="\\"
MSLKCOMMITADDEND=
MSLOCKPLAN=
MSNLSCODESET=
MSNTMPFILECACHE=
MSNULLVALUE=" "
MSPAGER=\
  [SYS_OS_WIN32]	"more <"
  [ALL]			more
MSPERMS=RW,RW,R	
MSPRINTER="pr | lpr"
MSQUERYPLAN=
MSQUOTEDIDENTIFIERS=
MSSELEXTFETCH=
MSSHELL=\
  [SYS_OS_WIN32]
  [SYS_OS_UNIX_AIX]	/bin/bsh
  [ALL]			/bin/sh
MSSORTBYPASS=X
MSSORTSPACE=
MSTHRESHOLDPFLSIZE=500
MSTMPDIR=\
  [SYS_OS_WIN32]
  [ALL]			/tmp
MSTMPFILECACHESIZE=
MSTMPPFX=ms
MSVALSEP=""
MSVERSIONMESG=X
MSWRAPMARGIN=0

# locking parameters

MSCFEXCLRETRY=50
MSCFEXCLSLEEP=0.05
MSEXCLRETRY=50
MSEXCLSLEEP=0.05
MSIAEXCLRETRY=10
MSIAEXCLSLEEP=0.06
MSIALOCKRETRY=10
MSIALOCKSLEEP=0.07
MSINDEXRETRY=20
MSINDEXSLEEP=0.08
MSLOCKRETRY=50
MSLOCKSLEEP=0.09

# transaction parameters

MSTRANSCOMMENT=
MSTRANSSYNC=
MSTRANSTABLELOCK=
MSTRANSUFNGFL=10
MSTRANSWARMPROTECT=

# query language

MSQLAUTOPAGE=
MSQLCMDSAVE=50
MSQLCOUNT=
# MSQLECHO options: batch, conv, run
MSQLECHO=run
MSQLONELINE=
MSQLPROMPT1="CMDNUM* "
MSQLPROMPT2=". "
MSQLTRANSACTION=
MSQLVARCHARS=${}

# query language -- select columnar

MSQLGCHARWIDTH=20
MSQLGDATEWIDTH=20
MSQLGDECIMALWIDTH="24 2"
MSQLGFLOATWIDTH=22
MSQLGINTEGERWIDTH=11
MSQLSELBOX=
MSQLSELCOLMAXDISPWIDTH=1024
MSQLSELCOLSEP="  "
MSQLSELGROUPCOLCROSS=
MSQLSELGROUPSEP=
MSQLSELHEAD=X
MSQLSELHEADCOLCROSS=
MSQLSELHEADSEP=" "
MSQLSELKEEPDUPLICATE=
MSQLSELROWCOLCROSS=
MSQLSELROWSEP=
MSQLSELTRUNCATE=
MSQLSELWARN=X

# Empress 4GL

MS4GLCHKNULVAL=
MS4GLCOMPATCHK=
MS4GLDEBUGSETUP=
MS4GLFLUSHTYPEAHEAD=
MS4GLFONTNAME=8x13
MS4GLNOLOADRUNMSG=
MS4GLPRINTSCREEN=SCREEN
MS4GLPRINTSCREENFORMAT=a
MS4GLPSWIDTH=6
MS4GLPSHEIGHT=11
MS4GLXASYNCOFF=\
  [SYS_OS_UNIX_DECUNIX]
  [SYS_OS_UNIX_IRIX]
  [SYS_OS_UNIX_SOLARIS]
  [ALL]			X
MS4GLXCOLORTOLERANCE=
MS4GLXCURSORCOLOR=
MS4GLXPOINTERCOLOR=
MS4GLXNEWCOLORMAP=
MS4GLXWINDOWTITLE=
MSTERM=
MSTERMSYS=pc

# Fortran Interface

MSF77BACKSCAN=X
MSF77BUFCOPY=\
  [SYS_OS_UNIX_AIX]
  [SYS_OS_UNIX_HPUX]
  [SYS_OS_UNIX_IRIX]
  [ALL]			X
MSF77IGNORELENGTH=
MSF77TERMCHAR=@

MSF90BACKSCAN=X
MSF90BUFCOPY=\
  [SYS_OS_UNIX_AIX]
  [SYS_OS_UNIX_IRIX]
  [ALL]			X
MSF90IGNORELENGTH=
MSF90TERMCHAR=@

# report writer stuff

MSMWNULLOK=X
MSPAGELENGTH=66
MSPAGEWIDTH=132

# internet stuff

MSGETHOSTTIME=5
MSHOSTNAME=
MSINETMESSAGERETRY=4
MSINETMESSAGETIMEOUT=30
MSINETPACKETRETRY=4
MSINETPACKETTIMEOUT=5
MSINETREPLYRETRY=4
MSINETREPLYTIMEOUT=60
MSSERVERHEARTBEAT=0
MSSERVERNETTYPE=INET_TCP
MSSERVERTERSELOG=X

# on-line backup stuff

MSCOORDTIMERFREQ=60
MSOLBBACKUPDEVICE=/dev/rst0
MSOLBBLOCKSIZE=16
MSOLBRECOVERYLOG=olbreclog

# replication

MSREPENABLEUPDATE=
MSREPLOCKRETRY=
MSREPLOCKSLEEP=
MSREPPURGEINTERVAL=

# empkill stuff

MSKILLRETRY=10
MSKILLSIGNAL=TERM
MSKILLSLEEP=5

# for Cray only

MSCRAYQDELSLEEP=5
MSCRAYQDELRETRY=10
MSCRAYQDELSIGNAL=HUP
MSMIGRATERETRY=1
MSMIGRATESLEEP=0

# shared memory variables

MSSHMPERMS=
MSSHMLOCATION=
MSMKDBSHMEM=X

# GUI variables

MSGUIDEFAULTSTYLE=
MSGUIFONTSPEC="-*-%s-%s-%s-*-*-*-%s-75-75-*-*-iso8859-1"
MSGUIPRECREATE=
MSGUIRGBTEXT=/usr/lib/X11/rgb.txt
MSGUISYSMAIN=

# dirty read + validation 

MSVALIDATELEVEL=440
MSVALIDATERETRY=10
MSVALIDATESLEEP=0.09

# net server stuff
MSUSERAUTHCONFIGFILE=
MSNETSERVERCONFIGFILE=netserver.cfg
MSNETTYPECONFIGFILE=nettype.cfg

MSCONFIGFILEPATH=\
  [SYS_OS_WIN32]	"${HOME}/Empress;${EMPRESSPATH}/config"
  [ALL]			"$HOME/.empress;$HOME;${EMPRESSPATH}/config"

# ODBC INI File
MSODBCINIFILE=odbc.ini

# ODBC compile OPTION
MSODBCTRACEABLE=X

# internal variables (Please do not modify)

MSBUFFERRECORDFACTOR=1
MSFILELOCKNBUCKETS=11
MSFILELOCKNLOCKS=\
  [SYS_OS_UNIX_DECUNIX]			489
  [SYS_OS_UNIX_HPUX_1020_32] 		242
  [SYS_OS_UNIX_HPUX_32] 		242
  [SYS_OS_UNIX_HPUX_64] 		314
  [SYS_OS_UNIX_HPUX_64_ITANIUM]		489
  [SYS_OS_UNIX_IRIX_64] 		491
  [SYS_OS_UNIX_LINUX_ITANIUM]		489
  [SYS_OS_UNIX_SOLARIS_ULTRA_64]	235
  [ALL]					243
MSNRECORDCACHE=10
MSTRANSUFNBI=10

# License (Please do not modify)

MSLICENCE=228d2c3c208a5a88ec300a225b647d391013dc037975d183
MSMAXPROCS=

To change system defaults for the variable values, edit initfile. In setting variables, you may use the variable EMPRESSPATH in place of explicit path designations. This allows paths to be customized more readily. If you do modify initfile, we strongly recommend that you make a copy of the original file, naming it something like initfile.orig before you make changes. You will need to restore the original file if you ever run Empress system testing routines. It will produce spurious errors if the system variables do not have their original values.

The Empress system variables are described below in the alphabetical order.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

This is an Empress 4GL system variable. Please refer to Empress 4GL: Administrator's Guide for detail description.

When accessing a table with a lock level set to anything other than record level there is a potential to buffer the reads such that each record does not have to be accessed individually. If Empress is capable of applying a read ahead algorithm for data from a table, it will. This has the result that Empress does not have to go to the disk for each record read.

MSBUFFERRECORDFACTOR controls this buffering action. Buffering is turned off if the block cannot hold a minimum of records specified by MSBUFFERRECORDFACTOR or if the record size is a multiple of block size. A block size is determined by the MSDBBLOCKSIZE variable.

By default Empress has this variable set to 1.

This variable specifies the size of memory allocation (in bytes) for transferring bulk data in small pieces. This is worthwhile in applications which transfer huge (multi-megabyte or multi-gigabyte) bulks, because it keeps the resident size of the Database Server small. If MSBULKSEGMENTSIZE is not set, it defaults to 1 Megabyte.

MSCFEXCLRETRY determines the number of attempts the locking mechanism makes to gain exclusive access to the coordinator file. The default is 50 tries. MSCFEXCLSLEEP determines the number of seconds between each try. The default is 0.05 second.

Empress recommends that you do not alter the value of this variable without the assistance of Empress Support personnel.

This variable specifies the length of the time period (in seconds) within which a client must check in with the coordinator. This is necessary in order for the coordinator to manage on-line backup on an active database. The default is 60 seconds.

This variable is relevant to the Cray system only.

This variable specifies the directory in which empqdel (utility available on Cray system only) logs information about requests which had to be killed with a "sure" kill (SIGKILL) signal. By default, this variable has the value ${EMPRESSPATH}/rdbms/spool/log.

These variables relevant to the Cray system only.

MSCRAYQDELRETRY specifies the number of times empqdel attempts to send the termination signal specified by MSQDELSIGNAL. The default value is ten attempts; values less than ten result in the use of the default value.

MSCRAYQDELSLEEP specifies the number of seconds empqdel waits before checking whether a request has died. The default value is five seconds; values less than five result in the use of the default.

This variable relevant to the Cray system only.

This variable specifies the number or symbolic name of the signal which is sent when empqdel attempts to terminate a request. Valid values are: HUP, 1, QUIT, 3, TERM, 15. If this variable has any other value, empqdel exits with an error message.

This variable indicates your preferred century for entering dates. The default is 1950. As an example entering only two digits for a year, 35, results in 2035.

MSDATEPIC sets the default date picture for dates printed by Empress Report Writer, and for interpreting date input in Empress. Valid date pictures are listed in the Empress SQL: Reference manual under Data Types. The default for MSDATEPIC is "dd aaaaaaaaa yyyy". To set MSDATEPIC to the format "27 June, 1992" in SQL session:

   SET MSDATEPIC TO "dd aaaaaaaaa, yyyy";

When a date value is entered into a DATE attribute, Empress first checks whether the value is in universal date format (yyyymmdd), then whether it satisfies the day, month, and year order specified in the date format of the attribute. If it does not, the value is checked against the day, month, year order specified in MSDATEPIC. If this does not produce a valid date, the value is rejected.

When a date is used in an expression, Empress first checks whether the date is in universal format, then whether it satisfies the order specified by MSDATEPIC. If neither produces a valid date, the value is rejected.

For example, with MSDATEPIC set to "mm dd yy", and a DATE (1) attribute (the format of which is dd aaaaaaaaa yyyy), the values "24 5 92", "5 24 92", and "19920524" are accepted as 24 May 1992. The value "1992 24 5", however, will be rejected. Ambiguous inputs (e.g., 05 05 92) are assumed to give the day before the month.

For this variable to have effect when running Empress Report Writer directly, it must be set in the operating system.

   set MSDATEPIC='dd aaaaaaaaa, yyyy'

This variable is set by default. The Data Definition Language (DDL) commands (such as, ALTER, CREATE TABLE, DROP TABLE, CREATE INDEX, ... etc.) will be wrapped with transaction.

For example, in case of system failure in the midst of altering a tabel (ALTER TABLE), with this variable set, you will be able to use warm re-start command (empwarm) to recover the table.

This veriable is used in Empress Japanese version only.

In Japanese language, there are two types of characters. One is two-byte character, which is called Kanji and Full-Katakana, the other is one-byte character, which is called Half-Katakana.

If MSDISPLAYKATAKANA is not set, the Half-Katakana character will be displayed as what it is. If it is set to any value, the Half-Katakana character will be displayed as "?" mark. This is only for terminals that can not display Half-Katakana characters properly.

MSDOLLAR controls input and output formats for DOLLAR data types. It is specified as a character string, where the first character is the dollar/cent separator, the second is the thousands separator, the third is the filler character (for DOLLAR Type 2 attributes), and the rest of the string (to a maximum of 50 characters) is the currency sign. The default value for MSDOLLAR is ".,*$".

For example, for German currency MSDOLLAR would be set to ",.*DM" so that a DOLLAR (6, 2) amount would print as:

   DM**1.234,56"

For U.S. currency, setting MSDOLLAR to "., US$". It prints the same amount as:

   US$  1,234.56

MSEDITOR sets the operating system editor invoked by the .zz command in the Interactive Interface and the Field Editor key in Empress 4GL. The default is set to:

For UNIX:

   EDITOR=vi

For Win32:

   MSEDITOR=edlin

MSEXCLRETRY determines the number of attempts the locking mechanism makes to gain exclusive access to the lock file for a table in order to create a lock. (It is essential that access to a lock file be exclusive so that deadlocks do not occur.) The default is 30 tries. MSEXCLSLEEP determines the number of seconds between each try. The default is 1. If you enter the command:

   SET MSEXCLRETRY TO 5;
   SET MSEXCLSLEEP TO 2;

When you try to access a table the lock file for which is in use, Empress will make five attempts to access the lock file at two-second intervals, for a total of eight seconds, before giving up with the "Lock Busy" message.

MSEXCLSLEEP may be set to a fraction. For example:

   SET MSEXCLSLEEP TO 1.0015
   SET MSEXCLSLEEP TO 0.357

This is internal setting to describe the behaviour of the Fortran compiler for string scanning. Do not modify.

This is one of three variables that govern the Empress Fortran Interface's handling of Fortran character strings. Please refer to Empress Fortran Interface manual for more detail information.

This is one of three variables that govern the Empress Fortran Interface's handling of Fortran character strings. Please refer to Empress Fortran Interface manual for more detail information.

This is one of three variables that govern the Empress Fortran Interface's handling of Fortran character strings. Please refer to Empress Fortran Interface manual for more detail information.

The variable MSFILELOCKNBUCKETS relates to the number of buckets that Empress requires to store the locks in the lock file. The optimal number is about one-seventh the number of locks and should be a prime number. Normally, this is chosen by Empress and should be changed only if the MSFILELOCKNLOCKS variable is changed.

The variable MSFILELOCKNLOCKS specifies the maximum number of locks that may be stored in any single lock file at any time. This value may be changed; it may need to be raised, for example, if transactions which lock a great number of records are run. Please note that if locking is done in "files" (versus in shared memory) raising the MSFILELOCKNLOCKS variable very high may impact negatively on performance since several disk reads may be required to read the large lock files.

MSFILESOPEN specifies the maximum number of files Empress can open at one time, hence the number of files available to the user at one time. You must alter this variable before Empress is invoked if it is to have any effect. The default value is 30.

This variable is useful when you need to open files in the program and cannot do so because Empress has used all available file descriptors, you will have to limit the number of files Empress will attempt to open. For example, to limit the maximum number of files Empress can open at one time to 10, at the operating system prompt, type:

For UNIX (in C shell):

   setenv MSFILESOPEN 10

For UNIX (in Bourne shell):

   MSFILESOPEN=10
   export MSFILESOPEN

For Win32:

   set MSFILESOPEN = 10

This will not prevent Empress from accessing more than 10 files. Empress will close the least-recently used file before opening another file, if the quota is reached. If the file that was closed by Empress is accessed again, Empress will automatically re-open it. Empress keeps track of these files internally and the closing and re-opening of files are transparent to the user.

MSFORCEPLOCK, if set, causes a process to lock itself into memory, assuming that it has the appropriate privileges. This will prevent swapping of the process. Note that:

1. On most systems, users need to be root to use plock successfully.
2. On Cray and HP, users must have permission to use plock.

While this is available in general, it should not be set without very carefully considering the whole system as it could seriously degrade system performance. It should only be used on very specific applications, and then only rarely. It should certainly never be set in the initfile, and it should not be set in the environment. It should be set only in a script file associated with a process in order that it be unset automatically with the termination of the script file.

For certain operating systems, the getcwd system call relies on the SIGCHLD signal for proper operation. Empress uses the getcwd system call to obtain current working directory information from the system. If an Empress client process traps the SIGCHLD signal, this will inhibit the use of getcwd with Empress, and cause Empress to hang. To avoid this situation, set the above variable so that Empress sets SIGCHLD to SIGDFL before calling getcwd and resets SIGCHLD to its original handler when getcwd is completed.

MSGCWDSIGCHLDRESET is not set by default.

When an Empress process starts, it attempts to find the network name and number of the machine on which it is running. If there is a network problem or the machine has not been configured correctly, it might take several minutes to retrieve the host information. In order to notify the user of such problems, any Empress process will issue a warning message if the time to retrieve the host information is longer than the value of this variable.

To avoid unnecessary warnings on a heavily-loaded machine, you may modify the value of this variable. The default value of 5 seconds is used if the value specified is anything other than a positive, non-zero integer.

Empress will use the getpwuid system call by default to obtain the user id. However, if the getpw system call is supported on the local system, then the user can set this variable to make use of getpw, instead of getpwuid. If getpw is not supported, then this variable has no affect. MSGETPW is not set by default. The getpw system call is the old implementation of getpwuid. This variable is provided for backward compatibility reasons. For systems working with NIS (Network Information System) or Yellow Pages, this variable should not be set.

This variable specifies the path of the Empress GUI system database. The default is ${EMPRESSPATH}/rdbms/gui/empguidb.

This variable defines the GUI application screen style. If it is not set, then it will use the same style as MSGUISYSMAIN. If it sets to a number, the style will be corresponding to the number that is defined for MSGUISYSMAIN. If it is set to a sting, then it will use the sting as a module name.

Path name of color file for Empress GUI Builder. The default is ${EMPRESSPATH}/rdbms/gui/colortab.

This variable is used for Empress GUI Builder. It defines the font definition for the xterm.

This variable contains the path of X Window rgb text file.

This variable specifies the color for the Empress GUI Builder environment. Please refer to Empress GUI: User's Guide for detail information.

MSHELPPATH specifies the directory in which the Empress help files are located. Usually, you only need to set this variable if you are using a set of help files other than the one provided.

This is for system that has more than one network. When this variable is set, Empress Database Server will use this name as system identity instead of default host name. For example, to use faster network instead of system default network.

MSIAEXCLRETRY determines the number of attempts the locking mechanism makes to gain exclusive access to the lock file for a table through the Interactive Interface or Empress 4GL. It will override the setting of MSEXCLRETRY. This second variable is necessary because a large number of retries may not be desirable while attempting to access the table interactively. The default is 2.

MSIAEXCLSLEEP determines the number of seconds between each try for the lock file. The default is 1. This variable may also be set to a fraction.

If you enter the command in SQL:

   SET MSIAEXCLRETRY TO 5;
   SET MSIAEXCLSLEEP TO 2;

When you try to access a table whose lock file is in use, Empress will make five attempts to access the lock file at two-second intervals, for a total of eight seconds before giving up with the "Lock Busy" message.

MSIALOCKRETRY determines the number of attempts made to create a lock for a table through the Interactive Interface. It will override the setting of MSLOCKRETRY. For example, the table may be locked in update mode, which prevents other locks being made, so that a lock attempt may fail on its first try. The default is 2.

MSIALOCKSLEEP sets the number of seconds between retries. The default is 1. This variable may also be set to a fraction.

If you enter the command in the SQL:

   SET MSIALOCKRETRY TO 5;
   SET MSIALOCKSLEEP TO 2;

When you try to create a lock for a table, Empress will make five attempts to do so at two-second intervals, for a total of eight seconds before requesting further instructions. For updating, if the table cannot be accessed or Empress cannot start to find the necessary records, you may specify retrying or quitting. Once the update has started, if a given record is inaccessible, you may specify retry, skip or quit. For inserting, you may specify retrying or quitting.

This variable indicates a percentage of the total number of records in a table, beyond which the index will no longer be used for retrievals. If the number of records in the selected set exceeds this percentage of the total number of records in the table, then the use of the index will be abandoned. For example, if this is set to 10, then a search with an index will begin to retrieve records which meet the search criteria, and when 10% of the total records in the table match the search requirements the index will be abandoned and the table itself will be used. This variable is useful for optimizing retrievals since if a large percentage of records is selected it is more efficient to go directly to the base table.

The default setting for this variable is 100, that is, the index is always used.

This variable specifies a minimum number of records that will be read from the indices regardless of the setting of MSINDEXLISTCUTOFF. For example, if this were set to 100, then MSINDEXLISTCUTOFF is ignored until 100 records are read from the indices. If the retrieval set exceeds this, MSINDEXLISTCUTOFF will be considered.

The default setting for this variable is 0, that is, when an index is available, the retrieval behavior will be controlled by MSINDEXLISTCUTOFF.

MSINDEXRETRY sets the number of times Empress will attempt to make a lock on an index. The default is 5.

MSINDEXSLEEP sets the number of seconds to wait between attempts to make a lock on an index. The default is 1. This variable may also be set to a fraction.

To set up for 10 retries and 2 second intervals, do the following in SQL:

   SET MSINDEXRETRY TO 10;
   SET MSINDEXSLEEP TO 2;

This variable indicates a percentage of the total number of records in a table, above which the index will be used for sorting the records. If the number of records to sort is below this percentage of total records, Empress will not use the index for sorting but will perform it in memory. With a large index and only a few records to sort, it is more efficient to forego the use of the index for sorting. If this is set to 10 for example, then only if more than 10% of the records in the table need to be sorted, will the index be used for the sort.

The default setting for this variable is 3.

MSINETMESSAGETIMEOUT and MSINETMESSAGERETRY are the timeout value and number of retries, respectively, for the client's message handler awaiting acknowledgement.

These variables must be set in the server configuration file and are not picked up when set in the environment.

MSINETPACKETTIMEOUT and MSINETPACKETRETRY are the timeout value and number of retries, respectively, for the client's packet handler awaiting acknowledgement. The timeout values are in seconds. Any or all of these timeout and entries are optional. Setting too short a reply or message timeout can lead to unnecessary request re-transmissions when the request or reply is large. This may cause serious performance degradation.

These variables must be set in the server configuration file and are not picked up when set in the environment.

MSINETREPLYTIMEOUT and MSINETREPLYRETRY are the timeout value and the number of retries, respectively, for the client awaiting a high-level response.

These variables must be set in the server configuration file and are not picked up when set in the environment.

Characters that cannot be printed, such as <Tab> and <Backspace>, are normally discarded from Empress output. To have these characters interpreted, set MSKEEPNONPRINTCHAR to any value.

This variable specifies the directory in which empkill should log information about processes which are gkilled with a "sure" kill (SIGKILL) signal. By default, this variable has the value ${EMPRESSPATH}/rdbms/spool/log. The log will then be found in the file ${EMPRESSPATH}/rdbms/spool/log/username.log where username is the login name of the person who initiated empkill.

MSKILLRETRY specifies the number of times empkill attempts to send the termination signal specified by MSKILLSIGNAL. The default value is ten attempts; values less than three result in the use of the default value.

MSKILLSLEEP pecifies the number of seconds empkill waits before checking whether a process has died. The default value is three seconds; values less than three result in the use of the default value.

This variable specifies the number or symbolic name of the signal which is sent when empkill attempts to terminate a process. Valid values are: HUP, 1, QUIT, 3, TERM, 15. If this variable has any other value, empkill exits with an error message.

3.3.65 MSLANG

Setting MSLANG=specific_language tells Empress to look for the table nls_specific_language in the NLS database; this table will have Empress messages in that specific language. When your process starts up, it takes the following steps:

1. It looks in the environment for the variable MSLANG, and if it is set, it sets the Secondary Language to its value. If MSLANG is not set, and LANG is set, then the Secondary Language is set to the value of LANG.

2. If the NLS database contains a message table whose name is nls_specific_language, where specific_language is the Secondary Language name, then that table is used for all Empress messages.

3. If the NLS database does not contain a message table whose name is nls_specific_language, then the Primary Language message table is used. The Primary Language is set either by Empress, or your distributor. It is the default language in which Empress messages are printed out.

For example, an Empress user may have a version of Empress in which the Primary Language is German. Then, the NLS database would contain a table nls_german which contains all the Empress messages. A mono-lingual English-speaking user of that copy of Empress could still get understandable messages by setting (in the environment) MSLANG=english, since the nls_english table is always available.

Note that:

• Users cannot change the Primary Language.
• All copies of Empress have the english message set available.
• Some copies of Empress may have other message set(s) available.

This variable contains licence information. This is system internal variable. Do not modify.

3.3.67 MSLINECONT

MSLINECONT sets the character string you will use to continue the current line on the next line (that is, to mask a new line). The default is a backslash ( \).

Set SQL-style line continuation, with "-" as the continuation character, with the the Query Language command:

   SET MSLINECONT TO "-";

This variable affects the behavior of Empress when inserting into a table which has record-level locking. If set, it reduces the number of lock manager accesses between consecutive insertions. This can result in some speed improvement since fewer accesses to the lock manager are made. For example, in inserting a series of records the usual behavior of Empress is to repeatedly:

1. acquire an update lock
2. write out the record
3. release the lock

With this variable set, Empress will:

1. acquire an update lock on the first record, and then repeatedly (for each insert)
2. write out record n, and
3. release the lock on record n, and acquire a lock on record n+1.

Over many inserts, this compounded last stage will produce half as many lock manager accesses as usual. For those using mr programs, steps 2 and 3 would correspond to mradd(); calling mraddend() will release the final lock on record n+1. mraddend() should be called as soon as possible after the last insert since the last lock will be held on to until it is invoked.

By default, this variable is unset.

The Empress variable MSLOCKPLAN provides information about locking as database operations are performed. The output that is produced shows the types of locks that are placed, the mode of those locks (read, deferred, update) and the success or failure of the attempted operation.

MSLOCKPLAN can be set in the environment, or in the initfile in the Empress custom directory, or in an SQL session with the SET command. To set MSLOCKPLAN in an SQL session, use the following command:

   SET MSLOCKPLAN TO 'X';

MSLOCKPLAN can be set to any value.

MSLOCKRETRY determines the number of attempts made to create a lock for a table once access to the lock file has been achieved. For example, the table may be locked in update mode, which prevents other locks being made, so that a lock attempt may fail on its first try. The default is 50.

MSLOCKSLEEP sets the number of seconds between retries. The default is 0.09 second. This variable can be set to a fraction.

For example, if you enter the command in SQL:

   SET MSLOCKRETRY TO 5;
   SET MSLOCKSLEEP TO 2;

When you try to create a lock for a table, Empress will make five attempts to do so at two-second intervals, for a total of eight seconds before giving up with the "Lock Busy" message.

The three variables MSMAXPROCS, MSFILELOCKNLOCKS and MSFILELOCKNBUCKETS control the size of the lock managers which are maintained in the _lock directory within each database. These govern the case of locking performed in "files" (versus in shared memory).

The maximum number of Empress processes that will be allowed to access the lock manager simultaneously is taken the minimum value of MSMAXPROCS and the value specified by the installation key. This variable can be set to the upper limit allowed by your installation key and cannot normally be raised by the Empress user.

These variables are used for Cray only.

MSMIGRATERETRY determines the number of attempts Empress will make to open a file through the server that a CRAY has migrated off disk. The CRAY's operating system may migrate files to another storage device if they have not been used for a specified amount of time. When Empress tries to open one of these files the CRAY will indicate to Empress that the requested file is offline and that the media is pending. Empress will retry number of times specified by MSMIGRATERETRY before failing.

MSMIGRATESLEEP sets the number of seconds to wait between attempts to open the file. This variable may also be set to a fraction.

If you enter the command:

   set MSMIGRATERETRY to 4;
   set MSMIGRATESLEEP to 1.25; 

then when you try to access a file through a server, Empress will make four attempts to do so at 1.25 second intervals, for a total of 5 seconds before giving up.

Note that This variable has no effect on a local access. The file must be accessed through a server.

If MSMKDBSHMEM is set, the database will be created with shared memory even without -shmem option specified in the empmkdb command.

The default is unset.

MSMWNULLOK is used to suppress printing of error messages when Empress Report Writer attempts to print a null. It is set by default. To turn off error suppression, unset the variable.

The codeset is a lookup table which determines:

1. The translation of characters from the keyboard to the Empress internal standard (EIS), and,

2. From the EIS to the output device. The EIS is the ISO Latin 1 codeset. This translation to an internal standard allows users with different hardware to enter data into, and read data from, the database.

Please note that:

• The mapping from input to the Empress internal standard does not have to be the same as the EIS to output mapping.
• The user cannot add new codesets.
• The codesets which are available include latin1 (the ISO 'Latin 1' standard), ibmpc (for IBM PC's), vt200 (for DEC vt200's), and any others that may have been added by your distributor.

The NLS database contains all the Empress messages, and it is defaulted to msnlsdb under the nls directory where Empress is installed. If msnlsdb=specific_language, then the database specific_language is used for NLS messages. The MSNLSDB overrides the default.

Whenever a table is opened (in an SQL SELECT, for example), Empress sets up a cache to speed up operations. The cache is discarded when the table is closed. MSNRECORDCACHE sets the cache size in terms of the number of records it can hold (consequently, each opened table might have a different cache size). Reading into the caches, and writing out/flushing from them is closely synchronized with locking. However, note that record caching is always implemented except in the following situation:

• when a table has record-level locking, and at least one of the following statements is true:

  • not within a transaction
  • table access occurs locally (i.e., not through an Empress Server).

This variable is set to 10 by default. For reasons of efficiency, it should be set to a multiple of the variable MSTRANSUFNGFL; setting it to zero will result in no record caching.

MSNULLVALUE defines a string to replace null values in Empress output. The default is nothing, so that nothing is printed.

MSODBCINIFILE defines the file name that the ODBC client will use to resolve data sources. The default value is odbc.ini

This variable specifies the default device or filename to which the database on-line backup will be copied. It may be a tape or DAT drive or a filenmae. If it is the latter, care shuld be taken that the file system in which the file resides is large enough to receive the backup.

This variable specifies the block size of the on-line backup device.

This variable specifies the name of the non-continuous recovery log which will be used to record database activity that occurs during an on-line backup. The file will be removed when the backup is complete. The default file will be created in the local directory with the file name olbreclog from which the backup is invoked.

MSPAGELENGTH sets the default page length for Empress Report Writer reports. It is set to 66 by default. To set the default page length to 23, using the following command at the operating system prompt:

For UNIX:

   setenv MSPAGELENGTH 23

For Win32:

   set MSPAGELENGTH=23

MSPAGER sets the operating system program used for paging Query Language command output. Like MSEDITOR, it may be set to a shell script (reading from standard input) including pipes (e.g., "pr | more"). Note that if a shell script is used, its syntax must be for the shell specified by MSSHELL. The default is more.

To change the pager to "pr | more" in SQL, use:

   SET MSPAGER TO "pr | more";

MSPAGEWIDTH sets the page width for Empress Report Writer reports. The default is 132. Set the page width to 80 from the operating system by the command:

For UNIX:

   setenv MSPAGEWIDTH 80;

For Win32:

   set MSPAGEWIDTH=80

MSPERMS sets the access permissions for Empress output files. The access permissions are any combination of R (read), W (write), and E (execute). They are given in order of owner, group and other. For example, to set new files read-write by owner, read by group, read by other in the initfile:

   MSPERMS=RW,R,R

The permissions will not override restrictions set by the operating system but can place additional restrictions on new files.

MSPRINTER specifies the operating system device name you will use to send output to a printer.

For example, for UNIX system, it may be set to a shell script (reading from standard input), including pipes. Note that if a shell script is used, its syntax must be for the shell specified. The default is "pr |lpr". To set the printer to "lpr" by the Query Language command:

   SET MSPRINTER TO "lpr";

Setting MSQLAUTOPAGE to any value appends INTO PAGER to each command, thereby automatically paging Query Language output (alternate instructions in a command, such as INTO PRINTER, override the INTO PAGER). Note that this adds some overhead to each command, so response will be slightly slowed. The default is to have automatic paging off.

Example on enable automatic paging using the Query Language command:

   SET MSQLAUTOPAGE TO x;

MSQLCMDSAVE determines the number of commands saved by the history mechanism. The normal default is 50 commands. For example, to have only the last 20 commands saved, use the Query Language command:

   SET MSQLCMDSAVE TO 20;

Setting MSQLCOUNT generates a count of the number of records affected by SELECT, DELETE, and UPDATE commands. It is not set by default. For example, to set this variable using the Query Language command:

   SET MSQLCOUNT TO true;

MSQLECHO controls the echoing of commands. It can take any combination of the values BATCH, CONV or RUN separated by spaces. It is set to RUN by default, so Query Language RUN commands are echoed (that is, the command that is executed by the run command is echoed). If MSQLECHO is set to BATCH, then commands executed by empbatch and commands executed by the RUN FROM file Query Language command are echoed. If MSQLECHO is set to CONV, all on-line Query Language commands are echoed (that is, both your typed command and its echo appear on screen).

The syntax for setting MSQLECHO in SQL is:

   SET MSQLECHO TO |BATCH| {|BATCH|};
                   |CONV |  |CONV |
                   |RUN  |  |RUN  |

For example, to turn on command echoing for empbatch as well as the run command with:

   SET MSQLECHO TO BATCH RUN;

When an expression is evaluated, the result is returned as non-parametric data. For character values, MSQLGCHARWIDTH determines the column width for the output. The default is 20.

When an expression is evaluated, the result is returned as non-parametric data. For date values, MSQLGDATEWIDTH determines the column width for the output. The default is 14.

When an expression is evaluated, the result is returned as non-parametric data. For decimal values, MSQLGDECIMALWIDTH determines the column width and number of decimal places for the output. MSQLGDECIMALWIDTH will only control the format of data appearing in a column. It will not, for instance, control the format of a decimal value result of a function that appears beneath a group. The default is 14 columns and 2 decimal places. For example, to set this variable to 10 columns and 4 decimal places in SQL:

   SET MSQLGDECIMALWIDTH TO '10 4';

When an expression is evaluated, the result is returned as non-parametric data. For float values, MSQLGFLOATWIDTH determines the column width for the output. The default is 22.

When an expression is evaluated, the result is returned as non-parametric data. For integer values, MSQLGINTEGERWIDTH determines the column width for the output. The default is 11.

Setting MSQLONELINE to any value indicates that a new line terminates a command, rather than the normal semicolon. Commands which span more than one line must end with the line continuation character (see MSLINECONT) when this variable is set.

For example, to have new lines end commands, use the Query Language command:

   SET MSQLONELINE TO 'x';

MSQLPROMPT1 indicates the primary Empress prompt. The default prompt is the number of the current command, an asterisk, and a space. The first command prompt appears as "1* ", the second as "2* ", and so on. This is represented when setting the variable in SQL by the syntax:

   SET MSQLPROMPT1 TO "CMDNUM* ";

The word CMDNUM instructs Empress to insert the number of the current command in that position.

MSQLPROMPT2 gives the secondary Empress prompt, which appears for commands split over more than one line. Normally, this is a period followed by a space (". ").

For example, to reset the primary prompt to "emp: " and the secondary prompt to "more: " using the Query Language commands:

   SET MSQLPROMPT1 TO "emp: ";
   SET MSQLPROMPT2 TO "more: ";

To have a box drawn around output from the SELECT command, set MSQLSELBOX to any value. The default is set to nothing (no box). For example, the commands:

   SET MSQLSELBOX TO 'x';
   SELECT FROM personnel;

give the output:

   --------------------------------------------------------
   |number    name           phone            credit_limit|
   |                                                      |
   |    10    Kilroy         426-9681              $500.00|
   |     5    Mosca          544-2243              $750.00|
   |    17    Wladislaw      723-6073               $50.00|
   |     3    Jones          667-2951              $500.00|
   |     8    Peterson       978-6060              $250.00|
   |     4    Scarlatti      961-7363              $100.00|
   |     9    Jordan         964-3335              $250.00|
   --------------------------------------------------------

When retrieving an attribute in empsql, empcmd or empbatch the maximum number of characters to be displayed on one line is determined by the value of this variable. The default is 1024.

3.3.101 MSQLSELCOLSEP

MSQLSELCOLSEP gives the character string which separates columns in output from SELECT commands. The normal default is two spaces. For example, to set a vertical bars as columns separator using SQL command:

   SET MSQLSELCOLSEP TO " | ";

Output from the command "SELECT FROM personnel;" now appears as:

   number | name            | phone          | credit_limit
          |                 |                | 
       10 | Kilroy          | 426-9681       |      $500.00
        5 | Mosca           | 544-2243       |      $750.00
       17 | Wladislaw       | 723-6073       |       $50.00
        3 | Jones           | 667-2951       |      $500.00
        8 | Peterson        | 978-6060       |      $250.00
        4 | Scarlatti       | 961-7363       |      $100.00
        9 | Jordan          | 964-3335       |      $250.00

MSQLSELGROUPCOLCROSS specifies a string to be printed where the group separator (MSQLSELGROUPSEP) crosses the column separator, in the output from SELECT commands. It should be the same width as the column separator. The default is nothing (null) if the group separator is not set, and the column separator if it is. The commands:

   SET MSQLSELGROUPSEP TO "-";
   SET MSQLSELGROUPCOLCROSS TO "**";
   SELECT FROM loans GROUP BY name;

produce the output:

   name            date                             amount
   
   Jones            7 February  1992                $33.95
                    3 April     1992                $25.00
                   12 August    1992               $300.00
   -------------**------------------**--------------------
   Kilroy          16 February  1992               $250.00
   -------------**------------------**--------------------
   Mosca            2 February  1992               $148.00
                    4 May       1992               $200.00
   -------------**------------------**--------------------
   Peterson         6 June      1992                $50.00
   -------------**------------------**--------------------
   Scarlatti       14 October   1992               $123.00
                    9 September 1992               $148.00
   -------------**------------------**--------------------
   Wladislaw       25 June      1992                $75.00
                   27 February  1992                $55.00
                   12 May       1992                $25.00

MSQLSELGROUPSEP specifies a character to be used as the group separator in the output from SELECT commands. This character is repeated to form a line between the output for each group. The default is nothing (null), so there is no line between groups.

Sample output using MSQLSELGROUPSEP is shown on the previous section.

MSQLSELHEAD is a flag that controls whether headers are printed in a SELECT command. If it is set to anything, headers are printed. If it is not set no headers are printed. The variable is set by default. To suppress the printing of headers, using SQL command:

   UNSET MSQLSELHEAD;

MSQLSELHEADCOLCROSS gives a string to be printed at the intersection of the heading separator and column separators, in the output from SELECT commands. The string should be the same width as the column separator. The default is nothing (null) if the heading separator is not set, and the column separator if it is. The following commands in SQL:

   SET MSQLSELHEADCOLCROSS TO "**";
   SELECT FROM personnel;

produce the output:

   number  name             phone             credit_limit
         **               **               **
       10  Kilroy           426-9681             $500.00
        5  Mosca            544-2243             $750.00
       17  Wladislaw        723-6073              $50.00
        3  Jones            667-2951             $500.00
        8  Peterson         978-6060             $250.00
        4  Scarlatti        961-7363             $100.00
        9  Jordan           964-3335             $250.00

MSQLSELHEADSEP specifies a single character to be used as a heading separator in the output from SELECT commands. The character is repeated to form a line under the headings. The default is one space, resulting in a blank line between headings and output records. The following commands in SQL:

   SET MSQLSELHEADSEP TO "-";
   SELECT FROM personnel;

produce the output:

   number  name                phone             credit_limit
   ------  -----------------   ---------------   ------------
       10  Kilroy              426-9681               $500.00
        5  Mosca               544-2243               $750.00
       17  Wladislaw           723-6073                $50.00
        3  Jones               667-2951               $500.00
        8  Peterson            978-6060               $250.00
        4  Scarlatti           961-7363               $100.00
        9  Jordan              964-3335               $250.00

When grouping is requested in a SELECT command, the duplicate values of the attributes on which grouping is done are normally not printed. To print the duplicates, set MSQLSELKEEPDUPLICATE to any value.

3.3.108 MSQLSELROWCOLCROSS

MSQLSELROWCOLCROSS specifies a string to be printed at the intersection of rows and columns in the output from SELECT commands. The string should be the same width as the column separator. The default is nothing (null) if the row separator is not set, and the column separator if it is. The following commands in SQL:

   SET MSQLSELROWSEP TO "-";
   SET MSQLSELROWCOLCROSS TO "**";
   SELECT FROM personnel;

produce the output:

   number  name              phone            credit_limit
   
       10  Kilroy            426-9681              $500.00
   ------**---------------**--------------**--------------
        5  Mosca             544-2243              $750.00
   ------**---------------**--------------**--------------
       17  Wladislaw         723-6073               $50.00
   ------**---------------**--------------**--------------
        3  Jones             667-2951              $500.00
   ------**---------------**--------------**--------------
        8  Peterson          978-6060              $250.00
   ------**---------------**--------------**--------------
        4  Scarlatti         961-7363              $100.00
   ------**---------------**-------------**---------------
        9  Jordan            964-3335             $250.00

MSQLSELROWSEP specifies a single character to be used as a row separator in the output from SELECT commands. The character is repeated to form a line between rows. The default is nothing (null),i.e. no lines between rows.

Sample output from setting this variable is shown above.

In the output from a SELECT command, column widths are normally expanded to fit the widest data value. If column widths are specified, data values are normally wrapped onto the next line. If MSQLSELTRUNCATE is set, data lines longer than explicit width specifications will be truncated. Set MSQLSELTRUNCATE to any value to turn truncation on. Setting this variable does not affect the output of commands in which column widths are not specified.

If MSQLELWARN is set to any value, an error message is printed if an expression in a SELECT command evaluates to an error value. MSQLELWARN is set by default; it can be unset with the command:

   UNSET MSQLSELWARN;

When MSQLTRANSACTION is set to any value, Empress issues COMMIT TRANSACTION and START TRANSACTION commands just before each Query Language command (excluding commands with syntax errors and RECALL, HOLD, HELP, CHANGE or EDIT commands). Hence, individual Query Language commands may be cancelled if desired.

This variable is unset by default. To enable automatic per-command transactions issue the following command in SQL:

   SET MSQLTRANSACTION TO 'x';

MSQLVARCHARS sets the three characters used for Empress variables: the character by which variable values are referenced, normally a dollar sign ($), and the delimiters which separate a variable name from surrounding text, normally curly brackets ({}). Three, and only three, characters must be specified, and they may not be alphabetic or numeric.

For example, to set the variable characters to an ampersand and square brackets use the command:

   SET MSQLVARCHARS TO "&[]";

If you have a variable called P with value personnel, you may now reference it by &P, and delimit it from the rest of a character string by "[" and "]". You can load the personnel table from a file of data called personnel_data by the command:

   INSERT &P FROM &[P]_data;

To escape the special function of the variable expansion character, it must be doubled, e.g., "&&P" evaluates to the string "&P".

The Empress variable MSQUERYPLAN provides information about index usage when query operations are performed. MSQUERYPLAN can be set in the environment, or in the initfile in the Empress custom directory, or in an SQL session with the SET command.

If MSQUERYPLAN is set, for every query operation that is performed, the indices that are available for use by the query optimizer, and the mode in which they can be utilized will be reported. This variable is useful for determining the optimum usage of indices by query optimizer in Empress. To set MSQUERYPLAN in an SQL session, use the following command:

   SET MSQUERYPLAN TO 'x';

For each database opened, a call to determine the current working directory (CWD) well be made. If this variable is set, then Empress will assume that the program does not explicitly change the current directory. Empress, therefore does not need to check the CWD but can just reset it to the path determined at the msinit call. This will boost performance slightly in sections of code where several databases are first opened.

MSSELEXTFETCH solves backward comatibility issues related to the usage of Empress mr and mx routine calls mrprev and mxprev. If mrprev and mxprev are not used, MSSELEXTFETCH should be set to nothing (i.e. MSSELEXTFETCH=) in order to gain performance in Empress C-API mr/mx applications.

Database Server checks itself every MSSERVERHEARTBEAT seconds, prints a message if it has been idle for that period of time. The default is set to 0. This means Database Server will not check for idle time.

This variable is set by default. It prints the server log information in compact format, that is, only client connect/disconnect and user name, client id, process id, and machine id will be printed.

Memory mapped file directory for the platform which uses mmap (memory mapping). Default directory is ${EMPRESSPATH}/rdbms/spool/shm.

MSSHELL indicates the operating system shell to be used for shell escapes from Empress. You must specify a full pathname. The value of MSSHELL is the name of the program used to execute the shell scripts specified for MSEDITOR, MSPAGER, and MSPRINTER.

The default is to the variable SHELL. For example, to set the escape shell to the C shell use the command:

   SET MSSHELL TO "/bin/csh";

This is the system address where the shared memory segment will exist. The value maybe different from system to system. When it sets to nothing, the system default will be used. This is internal variable. Do not modify.

MSSHMPERMS sets the default access permissions for shared memory partitions. The access permissions are any combination of R (read), W (write), and X (execute). They are given in order of owner, group and other.

This variable is set in initfile and has no value by default, so the operating system default applies. This is usually the umask setting.

To overwrite the default value this variable should be set in tabzero (e.g., MSSHMPERMS=RW,R,R) before the creation of shared memory segments.

MSSORTBYPASS is a flag that controls the behaviour of Empress during sorting when it encounters a locked record. If the flag is not set, processing stops and a "lock busy" message is printed. If the flag is set the locked record is ignored, and the message "record(s) locked during sort phase unavailable" is printed. To set the flag, set MSSORTBYPASS to anything, such as:

   SET MSSORTBYPASS TO 'x';

This variable controls all sorting in Empress. It is set by default.

MSSORTSPACE sets a limit on the amount of space Empress will attempt to acquire during sorting. The limit should be expressed in bytes. This variable should only be used in a restricted virtual memory environment. To set the limit to 100 kilobytes, enter:

   SET MSSORTSPACE TO 102400;

If you specify less than 2 blocks (based on the system block size) Empress will attempt to acquire the default amount of 512 kilobytes.

MSTERM identifies the type of terminal in use. Set it whenever you change the type of terminal you are using. While TERM is used if MSTERM is not set, we recommend that you set MSTERM separately since TERM is shared with other software and there is some risk of conflict. Note that MSTERM is used by Empress 4GL.

This variable specifies the location of the terminal database used by Empress 4GL. The default location is ${EMPRESSPATH}/rdbms/4gl/termdb.

If you wish to use an alternate terminal database, MSTERMDB should be set to the pathname of the new terminal information database.

This variable is used by Empress 4GL. It specifies the prefix of the terminal type.

In the past, xterm of different machine has different definition. This is mainly because of different types of keyboard were used. Hence, MSTERMSYS was used to indicate different keyboard types, for example,

   MSTERMSYS=hp
   MSTERMSYS=ix

Today, most system are using the similiar 101 keyboard. Therefore, pc is used as default value.

this variable is introduced to facilitate the deletion of large numbers of records from a table. It controls the maximum size which the internal PFL (Process Free List) can reach, before an automatic flush/merge is performed to the GFL (Global Free list). When the number of deletions specified by MSTHRESHOLDPFLSIZE have been done by a process, the process will make these slots available to other processes (for inserts) by making the free slots accessible through the header of the file. In order to be able to safely perform the flush/merge at the threshold point we needed to ensure that (for cases where locking is involved) an update CRIT lock is acquired for the duration of the flushing/merging.

It is set in initfile to 500.

MSTMPDIR specifies the directory in which temporary files are created by Empress.

In UNIX, its normal default is /tmp.

MSTMPPFX specifies the prefix used for temporary files created by Empress. Its default is ms (the rest of the file name is the process number). If you want temporary Empress files to be prefixed with me, do the following command:

   SET MSTMPPFX TO 'me';

Note that the new prefix cannot be longer than two characters. Additional characters will cause the file name to be truncated, making it impossible for Empress to find the files.

MSTRANSCOMMENT defines a comment to be placed on all transactions. If this variable is set when a transaction is started, the value of the variable is placed as a comment on the transaction. This can be useful if several people are working from the same account and they wish to distinguish their transactions. The value should be given as a string with a maximum length of 64 characters. If the string contains embedded blanks, it must be quoted. The variable is not set by default.

An example of placing a comment on transactions is:

   SET MSTRANSCOMMENT TO "This is joe's transaction;"

MSTRANSSYNC is set to ensure that all data is written immediately to file during a transaction. This variable must be set to guarantee that the warm restart facility will be successful. It is set by default.

If MSTRANSTABLELOCK is set and a lock level has been set with the LOCK LEVEL command, any tables involved in a transaction are automatically locked at the table level. This is desirable during a transaction to ensure that successive reads of a given table will show the same records in the same order. It is more efficient than record level locking since only one lock is placed per table, rather than one lock per record.

For example, set table level locking during transactions with the command:

   SET MSTRANSTABLELOCK TO 'x';

Empress handles transactions by recording an image to a transaction log of the record before it is changed. If, while in a transaction, the same record is altered multiple times then multiple images of that record are stored in the log. When a transaction is cancelled Empress will go backwards through the log file and restore all records one at a time until the entire log file has been exhausted. This will result with a single record being restored multiple times even though it is only the first image (the last one to be restored) that we care about.

To optimize this problem Empress will maintain a list of records that have been altered during a transaction. If a record is being altered, Empress first looks to see if this record is already in its list. If it is, then Empress knows that it already has a, "before image", of this record and that it does not need to log another image in the transaction file. If it is not, then Empress adds the record number to its list and saves the before image to the transaction log.

The size of this list is controlled by the Empress variable MSTRANSUFNBI. A reasonable setting for this variable would be the same as the average transaction size, the default is 10.

Note that this setting is especially useful if identical records are altered more than once within a single transaction, otherwise, the list causes extra overhead to be incurred. The overhead comes from having to linearly search the list to see if a record already exists in it.

This variable controls access to free records during a transaction, to optimize performance. Empress recommends that you do not alter the value of this variable without assistance.

MSTRANSWARMPROTECT is a flag that controls whether transactions will be acted on (resolved) by the automatic warm restart utility empwarm. If this variable is set to any value when a transaction is started, the transaction is protected from the warm restart utility. That is, the utility empwarm will ignore the transaction if it can be recovered to a save point. This feature is useful if the automatic warm restart is included as part of the system re-boot process. Since an unprotected transaction will certainly be rolled back unless a commit command has been issued, unprotected long transactions that are interrupted will tend to be rolled back. Protecting a transaction allows you to recover it to a save point with the "START TRANSACTION FROM savepoint" command after the warm restart utility has been run.

The variable is not set by default, so the warm restart utility will resolve all interrupted transactions by default. To set the variable, enter:

   SET MSTRANSWARMPROTECT TO 'x';

This variable controls the behavior of dirty read in the cases of reading the main table file (i.e., .rel file), the overflow file (i.e., .dtf file) and reading border records.

Refer to Dirty Read and Checksum chapter of this manual for detail description.

MSVALIDATERETRY specifies the number of retries Empress will make to read an invalid record. If the record still appears to be invalid after all the retries, Empress will either deliver the invalid record to the user or discard the invalid record depending on the setting of the variable MSVALIDATELEVEL. Refer to Dirty Read and Checksum chapter of this manual for detail description.

MSVALIDATESLEEP specifies the interval in seconds between retries to read invalid records. Refer to Dirty Read and Checksum chapter of this manual for detail description.

This variable is no longer supported in version 8.62

MSVALSEP gives the string used to separate attribute values in an Empress dump file. Its default is <Ctrl+V> (octal 26). For example, to set the attribute separator character to a colon use the command:

   SET MSVALSEP TO ":";

You should take care not to set MSVALSEP to any value which is normally found in data, or attribute values may be broken unexpectedly. Similarly, if a table is to be loaded from a dump file, MSVALSEP must be set to the string used as the separator in the dump file or the INSERT will not work.

MSVERSIONMESG is a flag that controls whether the Empress version number will be printed on startup. If set, the Empress version number will be printed. It is set by default. To unset the variable and prevent printing the Empress version number, use:

   UNSET MSVERSIONMESG;

MSWRAPMARGIN sets the floating right field margin for Empress reports. The default is 0. If white space occurs within MSWRAPMARGIN characters from the right margin of a field, a new line will start. For example, to set the floating right margin to eight characters from the end of the field use the command:

   SET MSWRAPMARGIN TO 8;

Name of user authorization configuration file. Refer to Empress Replication User's Guide : References for detail information.

Name of network server configuration file. Refer to Empress Replication User's Guide : References for detail information.

Name of network type configuration file. Refer to Empress Replication User's Guide : References for detail information.

Path for Network Server Related Configuration Files. Refer to Empress Replication User's Guide : References for detail information.

MSREPLOCKRETRY determines the number of attempts to be made to obtain a lock on a master table, when the master table is the replication master in a replication synchronization. For example, the master table may be locked in update mode, which prevents other locks being obtained, so that a lock attempt may fail on its first try. The default is 5.

MSREPLOCKSLEEP sets the number of seconds between obtaining lock retries. This variable can be set to a fraction.

For example, if you enter the command in SQL:

   SET MSREPLOCKRETRY TO 5;
   SET MSREPLOCKSLEEP TO 2;

trying to obtain a lock on a master table for replication synchronization, Empress will make five attempts to do so at two-second intervals, for a total of eight seconds before giving up.

By dafault, a Replicate Table is not update-able. All the updates to a Replicate Table are done through Replication Synchronization with a Replication Master Table. Setting MSREPENABLEUPDATE allows the users with sufficient privileges to make updates to a Replicate Table. Setting this value is strongly discouraged. The behaviour of a Replicate Table, and other dependent Replicate Tables is not predictable after updating a Replicate Table. This variable is unset by default. This variable is for internal usage.

The deleted records of a replication table are not purged (physically deleted) until they are synchronized with their dependent repication replicates. If the dependent replication replicates are synchronized, the deleted record of a replication table will be purged. MSREPPURGEINTERVAL sets the maximum amount of time in hours which will be allowed for a replication table to be synchronized with its dependent replication replicates, before a deleted record is purged automatically. If the replication table containing a deleted record is not synchronized with its dependent replication replicate table within this interval, the deleted record , will be purged. Its default value is 1 week (7 * 24 = 168 hours).

MSCASEINSENSITIVE forces Case Insensitivity. The database components such as table, view, attribute, index, reference, constraint and stored procedure, created after above setting was made, support Case Insensitivity.

By default Empress has this variable set to X on Win32 platforms and set to nothing on all other platforms.

MSNTMPFILECACHE defines a number of the caches used for temporary files associated with temporary tables used during retrieval tasks.

There will be 4 of 512 kilobyte cache buffers (governed by Empress variable MSTMPFILECACHESIZE) set internaly by Empress.

MSQUOTEDIDENTIFIERS, when set, allows quoted identifiers. If set, "abcd" used in SQL statement is treated as an identifier and 'abcd' is treated as a literal. If set to nothing or not set, both "abcd" and 'abcd' are treated as literals.

By default MSQUOTEDIDENTIFIERS is set to nothing.

Empress JDBC drivers implicitly set MSQUOTEDIDENTIFIERS to a double quote character (") according to the Sun's JDBC standard.

MSSELMAXROWS sets a maximum number of rows/records to return in Empress interactive SQL for any SELECT statement. By default this variable is not set.

MSSELTIMEOUT sets a number of seconds to wait for an SQL SELECT statement to execute before returning to the Empress Interactive SQL interface. By default this variable is not set.

MSTMPFILECACHESIZE defines a size of the cache used for temporary files associated with temporary tables used during retrieval tasks.

There will be 4 of 512 kilobyte cache buffers set internaly by Empress.

Size of cache buffers would be set in bytes. To set the cache buffer to 100 kilobytes, enter:

   SET MSTMPFILECACHESIZE to 102400;

When the set value is exceeded the rest of the file will be stored on disk.

MSPSMREPOSITORYDB defines a number of databases that can serve as a Persistent Stored Module (PSM) repository. PSM repository is a designated place for Empress RDBMS to look for PSM objects invocation.

In order to resolve/invoke PSM objects (user defined functions, operators, procedures and aggregate functions) Empress RDBMS will firstly look for them in the database in use, then it will look in the databases (in the reverse order) defined by the variable MSPSMREPOSITORYDB and finally it will look into the designated location in the Empress installation directory.

MSPSMREPOSITORYDB can be set in the initfile or in the environment, for example:

         MSPSMREPOSITORYDB="/usr2/joe/db1; /usr2/peter/db2"