Configuration Parameters

Configuration Parameters

Top  Previous  Next

 

QM has a number of configuration parameters that determine major settings for the system. These are stored in a file named qmconfig in the QMSYS account directory. Only system administrators should have write access to this file. Modifications can be made with the EDIT.CONFIG command or any text editor such as ED or SED from within QM, Notepad on Windows, or vi on Linux. Note that copying this file between systems may have unwanted effects as it may also contain other system configuration data.

 

The file is divided into a number of sections, each with a section title enclosed in square brackets. Only the [qm] section must be present. This section contains the configuration parameters described below which may be global or private. Global parameters apply to all users of QM. Private parameters, although initially set to the state defined in the configuration file, may be updated for an individual process using the CONFIG command. Private configuration parameters are marked with an asterisk in the table below.

 

If a line includes a # character, this is treated as the start of a comment and all later text on the line is ignored

 

Parameters that take on their default values may be omitted from the qmconfig file.

 

Configuration parameters that are described below as having additive values can be set in a parameter line or as a series of lines. For example,

FILERULE=7

is identical in effect to use of three separate parameters

FILERULE=1

FILERULE=2

FILERULE=4

 

CHARMAP

Specifies the name of the character map to be loaded on a non-ECS mode system when a process starts. If not present, a default map is used.

CLEANUP

Interval in seconds between checks for abnormally terminated QM processes. The value must be in the range 30 to 3600 and defaults to 300 (five minutes) if this parameter is not present. See Lost Processes in Monitoring the System for more information.

CLIPORT

The port for incoming QMClient connections.  If not present or blank the default port 4243 is used.

Setting this port to zero disables incoming QMClient connections, including use of QMNet.

Take care not to confuse this parameter with the QMCLIENT parameter.

CMDLOG

Sets the directory pathname for use with command logging.

CMDSTACK *

Determines the default size of the command stack. The value must be in the range 20 to 999 and defaults to 99 if this parameter is not present. If modified with the CONFIG command, the change affects only the session in which it is applied.

CODEPAGE *

Windows only. Specifies the code page to be used for QMConsole connections. If omitted, QM uses the default console code page. Note that a restriction in Windows requires that the console session is set to use Lucida Console font for this feature to work. This parameter is not applicable to ECS mode systems. See Windows Code Pages for more information.

DEADLOCK

If set to 1, QM aborts any program that attempts to wait for a lock that would result in a deadlock situation. The default value (0) allows deadlocks to occur, potentially making analysis easier. Mode 2 is like mode 1 but saves the current state of all locks in the temp subdirectory of the QMSYS account as a file named deadlock.n where n is the QM user number.

DHCACHE *

Determines the size of the dynamic file cache. See Dynamic Files for more details

DIRSELSZ *

Sets the maximum number of directory file items in each stage of a partial select.

DUMPDIR *

The pathname of the directory to receive process dump files.  If this parameter is null, the QMSYS directory is used.  On some systems, users may not have write access to this directory. DUMPDIR may be specified as a full pathname or relative to the account directory.

ECSMAP

Defines a comma separated list of ECS character maps to be loaded into shared memory. The first map will be used as the default.

ERRLOG

Sets the maximum size in kilobytes of the error log maintained in the errlog file in the QMSYS account directory. When the file reaches this size, the first half of the logged data is discarded. If set to zero, error logging is disabled. The minimum non-zero value is 10. A lower value will be treated as 10.

EXCLREM *

If set to 1, remote files are omitted from ACCOUNT.SAVE unless this exclusion is over-ridden by other mechanisms within the ACCOUNT.SAVE command processing.

FEATURE

Enable a configurable feature. To enable multiple features, multiple FEATURE parameters must be provided.

The options available are

NO.VOC.UPGRADESuppress normal check for VOC changes on entry to QM after upgrading to a new release. When this feature is enabled, the UPDATE.ACCOUNT command must be used to apply changes.
TANDEMEnable use of the TANDEM command.

FILERULE *

Sets rules for special filename syntax usage. This value is formed by adding together the following options as required:

  1  Allow account:file

  2  Allow server:account:file

  4  Allow PATH:pathname

  8  Allow VFS:server:qualifier

 16  Allow Pick style filename pathing

The CONFIG command can be used to modify this value within an individual process but only to remove options. Thus, the setting of this parameter in the configuration file represents the most powerful set of filename option rules that can be used.

FIXUSERS

Reserves a range of user numbers for exclusive use of users specifying a fixed user number when logging in using qm -n where n is the required user number.

The format of this parameter is

FIXUSERS=u,n

where

u is the lowest user number in the reserved range.

n is the number of user numbers to be reserved.

The highest available QM user number is normally 1023. Therefore, the value of u + n must not exceed 1024.

This feature is provided for compatibility with other environments in applications that rely on a fixed user numbers to recognise users. It is recommended that user login names should be used for this purpose in new applications as this gives a more secure system.

FLTDIFF *

The FLTDIFF configuration parameter determines how floating point values are compared.

Just as some numbers such as one third cannot be represented accurately in decimal, there are numbers that cannot be represented accurately in the binary notation used in computer systems.  Often, numbers that are accurate in one number base, are inaccurate in the other.  The inaccuracy is extremely small, typically at about the fourteenth decimal place.

A program that tests a floating point value for equality with some other value must allow for this inaccuracy rather than enforcing a strict equality.  The FLTDIFF parameter determines how close two values must be to be considered as equal.  The default value, 2.91E-11 (2-35), is an industry standard but this can be set to any positive value less than one.

The format of the data in the parameter setting may be either a simple number (0.0000000000291) or a number with an exponent (2.91E-11).

FSYNC *

Additive values determining when an fsync operation is performed to flush all updated data to disk:

1Every time that a file's header is updated.  This corresponds to all structural changes within the file (overflow, split, merge, etc) and on closing the file.
2At transaction commit.
4After every write. This will have a very severe impact on performance.
8Flush replication log data on every update. Changing the state of this element of the FSYNC value using the CONFIG command has no impact as it is a system wide setting.

Use of FSYNC can have a severe effect on performance but gives greater resilience to system failures.

File synchronisation always occurs on use of the QMBasic WRITESEQF or FLUSH statements regardless of the setting of this parameter.

GDI *

Setting this parameter non-zero on Windows systems causes the SETPTR command to use GDI mode by default.

GRPSIZE *

Determines the default group size in units of 1kb used when creating a dynamic file.  This parameter must be in the range 1 - 8 and defaults to 1.  For best performance, it should be a multiple of the operating system disk block size.

INTPREC *

Determines the rounding applied when converting a floating point number to an integer.

 

Just as there are numbers that cannot be written accurately in decimal such as one third, so there are numbers that cannot be stored accurately in the floating point formats used by computer systems. For example, entering a value of 17.9 will actually result in a stored value of approximately 17.8999999999999986.

 

The language definition for conversion of floating point values to integers states that the fractional part is discarded. To do so without rounding would mean that

DISPLAY INT(17.9 * 100)

would display the value 1789 rather than the more intuitively obvious 1790.

 

To avoid this problem, QM applies rounding to the floating point value based on the INTPREC setting when converting floating point values to integers in the INT() function or any implicit conversion such as dynamic array indices.

 

The parameter value identifies the decimal place at which rounding is applied. The default value is 11. Setting a value of 0 causes no rounding to be applied.

INVCASE *

Setting to 1 enables case inversion for terminal input, setting to 0 disables case inversion. If the parameter is not present, this feature is enabled by default. See also the PTERM command.

IPADDR

Specifies the IP address on which QM will listen for incoming network connections (telnet, QMClient, QMNet, replication). If omitted, QM listens on all available IP addresses. This parameter is most useful when a server hosts multiple separate instances of QM.

IPV6

Setting this parameter to a non-zero value indicates that IPV6 networking is supported by the underlying operating system and should be enabled in QM.

JNLDIR

Specifies the pathname of the directory used to store journalling log files. This directory will be created automatically if it does not exist.

JNLMODE

Additive value specifying the journalling modes to be supported:

  1  Enable before imaging (allows roll back)

  2  Enable after imaging (allows roll forward)

JNLSIZE

Sets the approximate maximum size of a journalling log file in Mb. The default value is 10. The valid range is 1 to 512.

LGNWAIT

Sets the maximum period in tenth of a second units for which a process will wait when attempting to login if the user limit has been reached. This can be useful, for example, with a web server application where peak loads could briefly hit the licensed user limit. The delay period can be retrieved using the QMBasic SYSTEM(1036) function, allowing applications to monitor the average delay and determine whether a licence with an increased user count is required. The SYSTEM(1055) function can be used to retrieve statistics relating to this parameter.

LICENCE

Licence parameters. Use the UPDATE.LICENCE command in the QMSYS account to apply new licence parameters.

LPTRHIGH *

Determines the default number of lines per page when a print unit is first referenced.  This must be in the range 1 to 32767 and may be overridden using the SETPTR command or equivalent QMBasic print unit modification functions.

LPTRWIDE *

Determines the default number of characters per line when a print unit is first referenced.  This must be in the range 1 to 1000 and may be overridden using the SETPTR command or equivalent QMBasic print unit modification functions.

MAXCALL *

Sets the maximum depth of nested subroutine calls including internal components of QM such as the command processor. If this limit is reached due to, for example, a program error resulting in a recursive call loop, QM will abort the program gracefully rather than failing in unpredictable ways when it runs out of memory. The value must be in the range 10 to 1000000 and defaults to 1000.

MAXIDLEN

Sets the maximum number of characters allowed in a record id. This must be in the range 63 to 255 and defaults to 63. Increasing this value increases the size of the internal lock tables. It is therefore recommended that the value used should be consistent with the needs of the application.

QM tracks the length of the longest id ever written to a file. Attempting to access a file where this exceeds the value of the MAXIDLEN parameter will cause the operation to fail. The qmfix utility and select operations that scan the whole file when no updates occur during the scan will correct the recorded longest id value if records have been deleted from the file.

MAXRLOCK *

Sets the maximum number of record locks that may be held by a QM process. Attempting to lock a record when at the limit will take the ON ERROR clause of the QMBasic statement trying to acquire the lock or, if no ON ERROR clause is present, will throw a SYS.LOCKS.LIMIT exception or abort. Setting this parameter to zero (the default) disables the lock count check.

MUSTLOCK *

Setting this parameter to 1 enforces use of locks when writing or deleting records.  If a program attempts to write or delete a record when it does not own a record update (READU) lock on the record or a file lock on the file being updated, the program will abort with error ER$NOLOCK.  The ON ERROR clause can be used to trap this error.  Leaving the parameter at its default value of 0 allows writes or deletes when no lock is in place but can lead to data integrity errors.

NETDELAY *

Sets the period in seconds for which a connection to a QMNet server will remain open after the last file on that server connection is closed. This can improve performance in applications that repeatedly open files on the same server. This parameter defaults to zero if omitted, resulting in the server process being terminated immediately when the final file on that connection is closed. Connections are also closed on return to the command processor or any other action that flushes the file cache.

NETFILES

By default QM does not allow access to files on remote drives.  This is because the locking system cannot detect if two systems are accessing the file simultaneously.  Where it is certain that a file will never be opened from two systems concurrently, setting this parameter to 1 will enable access to remote files.  Incorrect use of this feature can result in corrupt data files.

Setting NETFILES to 2 enables incoming connections from other QM servers accessing files via the QMNet interface.

These two mode settings are additive and can be used together.

NETWAIT *

Timeout (seconds) in the range 0 to 3600 when opening a QMNet connection. A value of zero implies no limit.

NUMFILES

The maximum number of QM data files that may be opened at one time. This is a system wide limit and has a maximum value of 32767. Use of the same file by multiple users counts as one file. Attempting to open more than this number of files will cause an application to fail. Setting the parameter significantly too high may have a small performance impact. The LIST.FILES command can be used to determine whether the value of this parameter is appropriate.

NUMLOCKS

The maximum number of record locks that can be held at one time as a system wide limit. If the limit is reached, processes attempting to get locks will wait for space to become available in the lock table. Setting the parameter significantly too high may have a small performance impact. The DETAIL option of the LIST.READU command can be used to determine whether the value of this parameter is appropriate.

OBJECTS *

The maximum number of programs which may be loaded into memory before discard is attempted. A program is a candidate to be discarded when it is not part of the call stack and it is not referenced from any subroutine variables from indirect calls. Setting this parameter to zero implies no limit on the number of concurrently loaded programs.

OBJMEM *

The maximum size of all loaded programs in Kb before discard is attempted. Setting this parameter to zero implies no limit on the size of concurrently loaded programs.

OPTIONS

An additive value affecting the QMSvc service (Windows), QMUSBSrvr (Windows USB installations) and qmlnxd on other platforms formed from:

1Log client disconnection. There is a small system overhead for this. (QMSvc only)
2Do not log authentication errors in the main QM error log file.
4Controls socket inheritance. Use only if directed by QM support. (QMSvc only)
8Enables extended diagnostic logging.
16Do not log successful incoming telnet connection.
32Do not log successful incoming QMClient connection.
64Do not log successful incoming serial port connection. (QMSvc only)

PAM

Enable (1) or disable (0) Pluggable Authentication Module support. The default setting varies by platform and is usually correct. If network logins fail, try changing this setting.

PDUMP

Additive flags to configure PDUMP (process dump) features. At this release the only flag value is

1Ban use of PDUMP to dump processes running under other user names except when performed by a user with administrator rights.

PHANTOMS

Defines a fixed range of user numbers that are reserved for phantom processes started with the USER option to the PHANTOM command.

PHANTOMS= u,n

where u = lowest user number, n = number of user numbers to be reserved.

POOL

Defines a connection pool.

POOL= name,limit,timeout

where name is the case insensitive pool name of up to 15 characters, limit is the maximum number of processes to be allowed to be in the idle wait state at one time, and timeout is the period in seconds after which an idle process will terminate. A timeout value of zero implies no timeout. This parameter may be repeated to define multiple pools.

PORT

The port for incoming client telnet connections. If not present or blank, the default port 4242 is used. If QM is the only telnet style service used on the host system, it may be useful to set this to 23, the standard port used by telnet software.

Setting this port to zero disables incoming telnet client connections. See also the PORTMAP QM configuration parameter.

PORTMAP

Allows users to create a fixed mapping between tcp/ip port numbers and QM user numbers. The format of this parameter is

PORTMAP=p,u,n

where

p is the lowest port number to be mapped.

u is the lowest corresponding user number.

n is the number of ports to be mapped.

The highest QM user number that may be mapped in this way is 1023. Therefore, the value of u + n must not exceed 1024.

Use of PORTMAP does not prevent users entering QM via the normal shared port defined by the PORT configuration parameter.

This feature is provided for compatibility with other environments in applications that rely on a fixed port number to user number relationship to recognise users. It is recommended that user login names should be used for this purpose in new applications as this gives a more secure system.

This feature is not supported on Windows USB installations of QM.

PWDELAY

The pause in seconds between successive attempts to enter the user name and password on network connections.  This parameter defaults to 5.

QMCLIENT

Provides additional security control for QMClient sessions.  This parameter has one of three values:

0No restrictions.
1Bans use of QMOpen() and QMExecute(), limiting clients to calling subroutines.
2In addition to the level 1 restrictions, QMCall(), QMCallx() and QMCreateObject() can only be used to call subroutines or class modules compiled with the $QMCALL compiler directive.

This parameter can be modified to a higher level in an individual process using the CONFIG command but cannot be taken to a lower level in this way.

RECCACHE *

Sets the size of the record cache (default zero, maximum 32). When a QM process reads a record, a copy of this record is retained in the cache. A subsequent read for the same record can find it from the cache rather than requiring an operating system call. The cache mechanism is most likely to benefit an application that makes heavy use of the TRANS() function to read the same record many times during a long query, for example when looking up a tax rate that is applied to every record processed. Writing or deleting records will invalidate the affected cache entries in all processes.

REPLDIR

Pathname of directory to be used for replication log files on the publisher system. This directory will be created automatically when QM is started if it does not already exist.

REPLMAX

Sets the limit on the number of simultaneous replication targets that may be active from a publisher. This parameter must be in the range 1 to 255 and defaults to 8.

REPLPORT

Port number on which QM will  listen for incoming network connections from a replication subscriber system. Use of the default port 4244 is recommended as this is also the default port used by the subscriber.

REPLSIZE

Sets the approximate maximum size of a replication log file in Mb. The default value is 10. The valid range is 1 to 512.

REPLSRVR

Server name of a replication subscriber system. This must match the name used on the publisher when setting up replication.

RETRIES

The maximum number of attempts allowed for entry of a valid username and password on network connections. This parameter defaults to 3.

RINGWAIT *

QM uses a ring buffer to hold type-ahead characters received from the keyboard.  If this becomes full, incoming data is thrown away and a bell character is sent back to the terminal.  Some applications may need to send a large burst of data which would fill the ring buffer and hence be truncated.  Setting the RINGWAIT parameter to 1 causes QM to wait for space to become available in the buffer rather than rejecting input.  Enabling this feature could result in the inability to use the break key if the ring buffer is full. The AccuTerm terminal emulator requires this parameter to be set to 1. (This parameter currently only applies to the Windows version of QM).

SAFEDIR *

Setting this parameter to 1 causes QM to adopt a careful update process when writing records to directory files. The new record is written to a temporary file, the old record is deleted (if it exists) and the temporary item is renamed to replace it.

This mechanism results in reduced performance but ensures that the original data is not lost if the write fails because, for example, there is insufficient disk space available.

SECURITY

Additive value controlling system wide security options.

1Query processor EVAL construct requires write access to the file's dictionary. Note that this is the file's dictionary regardless of possible use of the USING clause to select an alternative dictionary.
2Do not allow SET.PRIVATE.SERVER to create a definition that has the same name as a public server.

SERIAL

Defines a serial port to be monitored for incoming QM connections. Multiple SERIAL parameters may be specified. The format is

SERIAL=port,rate,parity,bits,stop

where

port = the port name (e.g. COM1)

rate = baud rate (e.g. 9600)

parity = none(0), odd(1), even(2)

bits = bits per byte (7 or 8)

stop = number of stop bits (1 or 2)

SH *

(Not Windows) Determines the shell processor and its options to be used when the SH command is used to start an interactive shell. If not set, this parameter defaults to "/bin/sh -i" on FreeBSD and "/bin/bash -i" on all other Unix/Linux based systems.

SH1 *

(Not Windows) Determines the shell processor and its options to be used when the SH command or the QMBasic OS.EXECUTE statement is used to execute a single command. If not set, this parameter defaults to "/bin/sh -c" on FreeBSD and "/bin/bash -c" on all other Unix/Linux based systems.

SORTMEM *

The size in kilobytes at which a sort switches from memory based to disk based.  This value is per user and defaults to 4096 (4Mb).  Setting values lower than this may lead to poorer performance unless you are severely restricted by memory size.  Setting values larger than this will require more memory for large sorts.

SORTMRG *

A disk based sort produces a series of intermediate files that must be merged to produce the final result.  The SORTMRG parameter specifies the number of files merged in each pass. This must be in the range 2 to 10 and defaults to 4.  The effect of changes to this parameter on sort times is dependant on the relative performance of the disk and processor.

SORTWORK *

The pathname of the directory to hold temporary sort workfiles. These are automatically deleted on normal completion of a sort.  If this parameter is null or the specified directory does not exist, the directory defined by the TEMPDIR parameter is used.

SPOOLER *

Sets the name of the default spooler on non-Windows platforms. If this parameter is not specified or is a null string, the lp spooler is used. The name specific may be another standard spooler (e.g. lpr) or a user written program or shell script to perform custom print management.

The qualifying data to this configuration parameter can include other options to be passed to the selected spooler.

See the description of the $SPOOLERS control record in the section on printing.

SRVRLOG

Sets the maximum size of the log file (QMSvc only). A value of zero causes QMSvc to start a new log each time the service is started, saving the previous log as QMSvcLog.old. A non-zero value sets the maximum size of the QMSvc.log file in kb. When this size is reached, the first half of the data in the file is removed.

STARTUP

Sets a command to be executed when QM starts. This may not contain double quotes. See Startup for more details.

TEMPDIR *

The pathname of the directory to hold temporary files. These are normally automatically deleted when no longer required but it is recommended that this parameter points to a directory that is cleared on restart of the system so that any files left behind at a system failure will be deleted.  If this parameter is null or the specified directory does not exist, QM uses the TEMP subdirectory of the QMSYS account on Windows or the operating system temporary directory on other platforms. Applications may find the location of this directory using CONFIG("TEMPDIR") or SYSTEM(38) and may use it to store temporary items but developers should be careful not to overwrite items created by other software. Internal parts of QM will never create items that have a leading underscore in their name.

TERMINFO *

The pathname of the directory holding the terminfo database. This defaults to a subdirectory named terminfo under the QMSYS directory.

TIMEOUT

The maximum wait period in seconds allowed during entry of a valid user name and password on network connections. This parameter defaults to 30.

TIMEZONE *

The time zone to be used by the epoch conversion code. The value of this parameter must match the format required for the operating system TZ environment variable. The default value is taken from the TZ environment variable on entering QM. If this variable is not defined, the time zone of the process that started QM is used.

TXCHAR *

Windows only. Determines whether QM uses the OEM character set translation functions on terminal i/o. The default value is 1 (use translation). A value of zero disables translation. This parameter is ignored on ECS mode systems.

UMASK

Linux and Unix only. Sets the default umask value for network connections to QM that do not enter via the operating system shell (direct telnet, QMClient, QMNet). The mask is specified as an octal value as in the operating system umask command. If this parameter is not present, a default of 002 is used.

USERPOOL

Determines the maximum user number that will be allocated by QM, default value 1023, maximum 16383. The actual maximum user number will be the greater of the value of this parameter and the number of simultaneous processes permitted by the licence.

VFSCACHE *

Sets the size of the file cache for the Virtual File System.

YEARBASE *

The earliest year in the 100 year range of dates entered with two digit year numbers.  This parameter is optional and defaults to 1930.