Configuration Parameters

Top  Previous  Next

 

QM has a number of configuration parameters that determine major settings for the system. On Windows systems, these are stored in a file named QM.INI in the Windows directory. Modifications should preferably be made using the Configuration Editor from the QM program menu rather than by editing the file itself because the Configuration Editor includes some validation of the parameter values. On other platforms, the configuration parameters are stored in /etc/qmconfig.

 

The file is divided into a number of sections, each with a section title enclosed in square brackets.

 

Configuration parameters 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.

 

The QM configuration parameters are:

 

CMDSTACK

Determines the size of the command stack for all users. The value must be in the range 20 to 999 and defaults to 99 if this parameter is not present.

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 the PDA version of QM.

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. This parameter is not applicable to the PDA version of QM.

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.

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. This parameter is not applicable to the PDA version of QM.

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. This parameter is not applicable to the PDA version of QM.

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

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. This parameter is not applicable to the PDA version of QM.

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.

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. This parameter is not applicable to the PDA version of QM.

GDI *

Setting this parameter non-zero on Windows systems causes the SETPTR command to use GDI mode by default. This parameter is not applicable to the PDA version of QM.

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 13. Setting a value of 0 causes no rounding to be applied.

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. This parameter is not applicable to the PDA version of QM.

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. This parameter is not applicable to the PDA version of QM.

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. This parameter is not applicable to the PDA version of QM.

MAXIDLEN

Sets the maximum allowed length of a record id. This must be in the range 63 to 255 and defaults to 63. Increasing this value has a significant effect on 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 will correct the recorded longest id value if records have been deleted from the file.

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. This parameter is not applicable to the PDA version of QM.

NETFILES

By default QM does not allow access to files on remote drives.  This is because the locking system cannot detect that 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. This parameter is not applicable to the PDA version of QM.

NUMFILES

The maximum number of QM data files that may be opened at one time. This is a system wide limit. 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.

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.

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 available QM user number 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 QMSRVR PORT configuration parameter.

Note that this parameter appears in the QM section of the configuration file as it relates to both QM and QMSvc.

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 98/ME or on the PDA version of QM.

On a Linux system, it will be necessary to create corresponding files in the /etc/xinetd.d directory for each port to be monitored. The format of these is

service qmsrvr

{

id              = qmsrvr4001

port            = 4001

bind            = 0.0.0.0

type            = UNLISTED

protocol        = tcp

flags           = REUSE

socket_type     = stream

wait            = no

user            = root

server          = /usr/qmsys/bin/qm

server_args     = -n

log_on_failure  += USERID

disable         = no

}

where the value 4001 in the above example is replaced by the port number.

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() can only be used to call subroutines 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. This parameter is not applicable to the PDA version of QM.

QMSYS

Identifies the location of the QMSYS account directory.  If the QMSYS directory is moved for any reason, change this parameter to point to the new location and the system should operate with no other changes. This parameter is not applicable to the PDA version of QM.

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.

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. This parameter is not applicable to the PDA version of QM.

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/bash -i" on Linux and "/bin/sh -i" on FreeBSD. This parameter is not applicable to the PDA version of QM.

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/bash -c" on Linux and "/bin/sh -c" on FreeBSD. This parameter is not applicable to the PDA version of QM.

SORTMEM *

The size in kilobytes at which a sort switches from memory based to disk based.  The default value is 1024 (1Mb).  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. This parameter is not applicable to the PDA version of QM.

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. This parameter is not applicable to the PDA version of QM.

STARTUP

Sets a command to be executed when QM starts. This may not exceed 80 characters and may not contain double quotes. This parameter is not applicable to the PDA version of QM.

This process will run the MASTER.LOGIN and LOGIN paragraphs in the same way as any other QM session.

On Windows. persistent shared memory must be enabled with the QMSRVR OPTIONS parameter. The command will be executed when the QMSvc service starts. Note that it will run as the powerful System user which could represent a security risk.

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. This parameter is not applicable to the PDA version of QM.

TERMINFO *

The pathname of the directory holding the terminfo database. This defaults to a subdirectory named terminfo under the QMSYS directory. This parameter is not applicable to the PDA version of QM.

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.

 

 

The QMSRVR configuration parameters control the QMSvc service (Windows NT and later) or its predecessor, QMSrvr (Windows 98/ME and USB installations). They are not used on other platforms. These parameters are:

 

MAXLOG

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.

OPTIONS

An additive value formed from QMSvc/QMSrvr option flags:

1Log client disconnection (QMSvc only). There is a very small system overhead for this but it should be negligible.
2Persistent shared memory (QMSvc only). With this mode set, the shared memory structures used by QM are created by QMSvc (unless they already exist) and remain present until all user have logged out of QM and QMSvc is shut down. This mode of operation gives faster entry to QM and may be of use in web servers or other applications that use frequent, short life QM sessions..

PORT

The port for incoming client telnet connections.  Leave blank to use the default port (4242).  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 described above.

QMCLIENT

The port for incoming QMClient telnet connections.  Leave blank to use the default port (4243).

Setting this port to zero disables incoming QMClient connections.

RETRIES

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

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)

TIMEOUT

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