$OPTIONS RUN

General Form:
  1. $OPTIONS RUN = alpha_expression
  2. alpha_receiver = $OPTIONS RUN
Where:

Form 1 of $OPTIONS RUN is used to allow KCML programs to modify the value of the $OPTIONS RUN system variable which is an array of bit flags and constants that control the runtime behaviour of KCML. It extends the $OPTIONS variable which is supported for compatibility with other language variants. There is a similar $OPTIONS LIST variable to control how programs are recreated in the KCML Workbench.

Form 2 allows the contents of $OPTIONS RUN to be examined.

Any byte of this variable can be preset at the time KCML starts up by use of the OPTIONS_RUN_XX environment variable.

For example:

STR($OPTIONS RUN,20,1)=BIN(1)

It important that $OPTIONS RUN is modified directly in this way as the number of bytes in $OPTIONS RUN may be increased in a future version.

Note that many of the bytes in $OPTIONS RUN are Booleans and therefore can be set any value, i.e. HEX(01), to select the option. However the use of HEX(01) as the value for TRUE is recommended as protection against the definition being extended in the future. Setting the byte to HEX(00) reverts back to the default FALSE setting.

Any of the bytes in $OPTIONS RUN can be preset by defining the environment variable OPTIONS_RUN_xx (where xx is the decimal byte number) in the connection manager before KCML is started and setting it to the two HEX digits required.

Available byte settings for $OPTIONS RUN
Byte(s)KCML_OPTIONS_RUN fieldDescription
1 A Boolean parameter used to set the COMPAT30 flag.
2 A Boolean parameter used to set the UNIXPROGS flag.
3Reserved
4 A Boolean parameter used to set the TOMFILE flag.
5 A Boolean parameter used to set the TOMDIR flag.
6OPTIONS_RUN_NoEndDoError A Boolean parameter used to set the NOENDDOERROR flag.
7 A Boolean parameter used to set the DOSELECT flag.
8 A Boolean parameter used to set the BREAK30 flag.
9 Reserved
10 Reserved
11OPTIONS_RUN_KeepShared A Boolean parameter used to set the KEEPSHARED flag.
12-13 Reserved
14 If set to HEX(01), KCML removes files before a RESAVE is performed. The implication is that any links are broken and the file is ownership, permissions and date-stamp are set for the current user.
15 Reserved
16 A Boolean parameter used to set the COMPAT32 flag.
17 Sets the keys used to change between the Edit/Debug window and the Console Window. Setting this byte to HEX(FF) will disable the full screen editor/debugger. The default value is HEX(7E) for the TAB key.
18-19 Used to set the programming mode password. A value of zero means that programming mode passwords are not in use.
20OPTIONS_RUN_Language Used to select the language when multi-language (multilingual) strings are being used. To make KCML software more interoperable the standard KCML language codes are the recommended settings for this variable. To be noted, BYTE20 is not used to define the encoding code page for $PACK and $UNPACK. For those purposes, please refer to byte 61 here.
21-22 Reserved
23OPTIONS_RUN_HelpStart$ Defines the character used to start a $HELP special sequence. By default this byte is set to a ‘{‘.
24OPTIONS_RUN_HelpStop$ Defines the character used to end a $HELP special sequence. By default this byte is set to a ‘}’.
25-26OPTIONS_RUN_MaxPart Stores the value of the highest available partition number, taken from the BCDPART environment variable. This value was used when KCML started up and is copied here for information only. Directly modifying these bytes will have no effect on partition numbers allocated to subsequent KCML processes
27 Soft return character, HEX(83) by default, used when loading ASCII source in order to preserve Niakwa style line terminators in ‘;’ comments. Can be set to HEX(00) to suppress this function.
28 Replacement character for the ‘@’ sign at the beginning of variables when compiling ASCII source when importing from environments where the ‘@’ prefix does not denote a global variable. The default character is the ‘@’ sign for no replacement. If set to HEX(00) the value of the environment variable ATREPLACE will be substituted if it exists.
29OPTIONS_RUN_EditorHistory Changes the maximum number of statements that can be held in the immediate mode command history buffer of the line editor. Defaults to 16.
30 Changes the maximum number of program lines that can be held in the program line modification history buffer of the line editor. Defaults to 16.
31 Changes the maximum number of items held in the immediate mode cut/paste history buffer of the line editor. Defaults to 16.
32 A Boolean parameter used to set the HANGUP flag.
33 Setting this byte to HEX(01) enables Niakwa compatibility mode at runtime. This byte is automatically set if KCML is started with the -n command line parameter. It disables the special treatment of global variables with an '@'; prefix, forces 24 lines for INPUT SCREEN on terminals with more than 24 lines and disables scrolling in PRINT AT(.
34 Modified mouse behaviour. Setting this byte to HEX(01) instructs KCML to use Niakwa style mouse drags. This byte is automatically set if KCML is started with the -n flag. Normally KEYIN does not process any mouse operations but passes them straight through. All mouse drags (unless this byte is set) are returned as drag North.
35OPTIONS_RUN_Win32Mode Changes the way that KCML handles execution of Windows routines defined by the $DECLARE statement and called with the GOSUB' statement. This byte uses a bit pattern mechanism to set the various options. The valid bits are as follows:
HEX(00) Always wait for a reply from the routine, this is the default case
HEX(01) Do not wait for a reply from the routine. With this bit set the routine must be called from a GOSUB’ statement and not from within an expression.
HEX(02) Tests for the availability of the routine only. No attempt is made to actually execute the routine. If the routine does not exists the GOSUB’ statement will error with a recoverable P38 Remote function not found error.
HEX(80) Forces calls to $DECLARE to execute on the server and not the client
36OPTIONS_RUN_DisableProg If set to HEX(01) all programming functionality is disabled. If a STOP or END statement is executed or if the program errors then KCML will automatically execute a PANIC statement. To reinstate programming set it to "P".
37OPTIONS_RUN_ShellMode Used to determine how SHELL is executed.
HEX(01)Under KCML4 setting this determined if DOS boxes were minimized. Not used in KCML5.
HEX(02)Force execution without using command processor.
HEX(04)Force execution in a separate visible window. Note that this may not be visible if the server is a different machine.
HEX(08)Create a pseudo-tty to execute an interactive Unix command.
38 A Boolean parameter used to set the COMPAT40 flag.
39 In versions of KCML > 04.00 any modifications to environment variables performed with the ENV( function are exported to any child processes. Setting this byte to HEX(00) disables this action and therefore reverts back to the non-exporting method used by older versions of KCML.
40OPTIONS_RUN_SaveOptions Options that control $COMPILE and, in some circumstances, SAVE and LOAD. This byte uses a bit pattern mechanism to set the various options which can therefore be combined.
HEX(00) Perform a normal compilation
HEX(01) Forces $COMPILE to assume that all files are compiled program files when loading.
HEX(02) All programs saved to native files with $COMPILE will be saved in ASCII format. This does not affect SAVE.
HEX(04) All programs saved to native files as ASCII will have ".src" added as an extension. This affects LOAD and SAVE as well as $COMPILE. When LOADing ".src" is added to the filename before it is loaded.
HEX(08) When saving or loading ASCII program automatically translate spaces in filename to underscores. This affects LOAD and SAVE as well as $COMPILE.
HEX(10) When $COMPILEing back to a platter translate filenames to lowercase.
HEX(20) Used in conjunction with the HEX(02) to force $COMPILE to create ASCII files in LIST S format.
HEX(40) Forces $COMPILE to overwrite destination files if they exist, otherwise any error is reported.
HEX(80) Does not add the ".src" extension when saving $COMPILEd programs.
41OPTIONS_RUN_HelpOptions $HELP options. This byte uses a bit pattern mechanism to set the various options, the valid bits are as follows:
HEX(01) Suppress $HELP functionality entirely.
HEX(02) Enable support for multi-page help file with Next and Back buttons.
HEX(04) Instructs KClient/WKCML to spawn a Windows browser to display the Help files. This requires the HELPSERVER environment variable to be set.
HEX(08) Used in conjunction with the HEX(04) to instruct the Windows browser not to check for the file on the local machine.
HEX(10) Instructs KClient/WKCML to spawn MS Windows Help (WINHELP) to view a .HLP file from the local PC.
HEX(20) Instructs KCML to display HTML help as a text window event when a form is up. Useful if it is known that the client machine does not have an HTML browser installed.
42 Size in MB of the memory buffer used by FSORT and KI_REBUILD. Defaults to 4 NT systems. On Unix systems it defaults to 8 for 32bit file access systems and 64 for 64bit systems.
43 Reserved
44 Maximum number of lines used to LIST DIM a variable in a PANIC listing.
45 SELECT @PART " " options
HEX(00) Keep global partition mapped
HEX(01) Detach global partition
46OPTIONS_RUN_LoadOptions Options for LOADing and SAVEing programs. Does not affect $COMPILE.
BIN(0) The default value. Just LOAD "file". A runtime check will be made to see if the program is compiled or in source form. SAVE will save the program in compiled format.
BIN(1) Try LOAD "file.src" then LOAD "file". Always SAVE as source.
BIN(2) Try LOAD "file" then LOAD "file.src". SAVE will save the program in compiled format.
BIN(3) Try LOAD "file.src" only. Always SAVE as source.
BIN(4) Always LOAD compiled "file" but SAVE both "file" and "file.src". If "file.src" is newer that "file" then compile before LOADing.
BIN(5) As per BIN(1), try LOAD "file.src" then LOAD "file". If the file is recognized as an text source file then it will be loaded using the text format rules. When SAVEing only the source file with a .src extension will be saved. This option was introduced in KCML6.10. See also BYTE 66
47OPTIONS_RUN_PRINTUSINGMode PRINTUSING and PRINTUSING TO options
HEX(01) No count in first two bytes of buffer
HEX(02) Put a Tab character between columns
HEX(10) Enables the use of dollar signs to replace hashes within PRINTUSING images. Used in conjunction with the $CONVERT statement to enable automatic currency conversion within PRINTUSING output.
HEX(20) Indicates if the native or alternative currency has been selected by the user. If set then the alternative currency is being used. This bit is set when the client connects to the server, and is updated when the client changes the current currency.
48OPTIONS_RUN_Century Start of current century. Defaults to 32 so years 0 to 31 will be assumed to be 2000 to 2031. Year 32 will be considered as 1932.
49OPTIONS_RUN_GlobalFLDs Global field variable options
HEX(00) Ignore (this was the default prior to 6.20)
HEX(01) If not in local symbol table then lookup in global.
HEX(03) Save global value in local symbol table.
HEX(04) All undefined fields are looked up in the global at resolve time and copied to the local symbol table. This option is necessary if using $COMPLIANCE to check for all undimmed variables.
As of KCML 6.20 the default is HEX(03) for a runtime lookup of undefined fields.
50OPTIONS_RUN_LangTable Language table for $UPPER, $LOWER and $STRCOLL on non-Unicode systems where USING_UTF8 is not set
HEX(00) US ASCII 7 bit code page (default)
HEX(01) ISO Latin-1 code page
HEX(02) User defined code page
If HEX(00) then HEXPRINT+ will use '.' for the character representation of all characters above HEX(7F) as well as those below HEX(20). Otherwise it will assume that characters above HEX(7F) are printable.
51 $REWIND/$CLOSE options. The default setting is HEX(03).
HEX(01) implied $REWIND in $CLOSE
HEX(02) explicit $REWIND
52OPTIONS_RUN_LogThreshold WRITE LOG threshold.
HEX(00) report all messages, eg _LOG_INFORMATION, _LOG_WARNING & _LOG_ERROR.
HEX(01) report messages of level 1 or higher, eg _LOG_WARNING & _LOG_ERROR.
HEX(02) report messages of level 2 only, eg _LOG_ERROR.
The default value is HEX(00) to allow all messages.
See WRITE LOG for more information.
53OPTIONS_RUN_PanicEndOptions Controls the actions of statements such as $END, PANIC and CATCH in a running interactive program if programming is enabled, HALT is enabled and the programmer has previously invoked the debugger. It is a bit mask field with bits set controlling different statements thus:
HEX(01) set then $END will drop into the editor instead of terminating the session.
HEX(02) set then a PANIC will be treated as a special A08.41 error and no file will be produced. PANIC can still be typed in immediate mode in the console window to generate a file after the error.
HEX(04) set then an error inside a TRY block which would be caught and handled by an outer CATCH clause in another subroutine will still error but continue will be allowed and will resume execution in the CATCH block. This allows the programmer to see why control has transferred to another subroutine.
HEX(08) is like HEX(02) except that the special error will be produced even if the workbench has not been previously entered in that session.
The default value is HEX(07).
54 If set to >=1 then SAVE ASCII, or SAVE operating in ascii mode (see byte 40 above), will create backup files with a .bak extension. If the value is greater than one a sequence of n backup files will be created. The oldest backup file in the sequence of files will be overwritten on each save. The default is HEX(00) in which no backup is created.
55-56 Stores the value of the minimum available terminal and partition number, taken from the BCDPART environment variable. This value was used when KCML started up and is copied here for information only. Directly modifying these bytes will have no effect on terminal and partition numbers allocated to subsequent KCML processes
57 Reserved
58 Controls the formatting of LIST RETURN. Setting the HEX(01) bit will list programs loaded without the platter or directory to be consistent with KCML 5.02 and before. Unsetting it (the default) display the full absolute path name.
59OPTIONS_RUN_Constants This byte controls the use of symbolic constants which are numeric symbols with a leading underscore e.g. _BUFSIZE. If this byte is HEX(00) then they are treated as regular variables for compatibility with previous versions of KCML (constants were introduced in KCML 6.0). If the HEX(01) bit is set then KCML will parse such tokens as constants as disallow any statement other than DIM or COM which attempts to set the value. See Constants in KCML programs. Starting with KCML 6.10 constants are enabled by default. Prior to this it was disabled by default.
60 This byte controls the code page used by the client to interpret the text on forms. On most systems the default value (0 meaning to use the default code page) will do because the default code page on the client's system will support the same language as the text on the forms. Where the default code page is different to the language the wrong characters will be displayed. This is only likely to occur on a small number of test systems using a different code page to the language. (Most of Western Europe uses Latin1, much of Eastern Europe uses Latin2 and there various DBCS character sets for individual languages in the Far East.) You may need to set this byte if you need to display Latin2 characters on a US system for instance. Clearly the client must also have suitable fonts installed. If non-zero the byte must be set one of the standardized language codes as used by $OPTION RUN byte 20. Note that these exact codes must be used even if you are using a non-standard numbering for the strings in chevrons.
61OPTIONS_RUN_Locale This byte controls the encoding used by the extended form of $PACK and $UNPACK to convert to and from UTF-8 and UTF-16. This has a default value of 0 meaning the current server locale (usually the C locale for Unix). However if the USING_UTF8 environment variable is set then it is defaulted to HEX(FF), meaning data is encoded in UTF-8 so no translation in and out of UTF-8 is needed. If non-zero the byte must be set to one of the required language code as used in byte 20 here for chevron strings. Note that these exact codes from the table must be used even if you are using a non-standard numbering for the strings in chevrons. If no codepage is defined, it will be set to EN_GB by default. For invalid character conversion, an error message will pop up mentioning the converted character is not in the defined codepage character set range.
62OPTIONS_RUN_Compatibility This byte controls the reporting of some errors for backward compatibility. These errors trap programming conditions that are wrong, but would have silently failed in previous versions of KCML. Because they are known to introduce run-time errors in applications that previously worked, these errors are by default disabled. They may be enabled using this byte, and developers are encouraged to do so. Currently three bits are defined:
HEX(01) Error attempts to retrieve properties from the grid cells that are not stored on the server (they are sent directly to the client). See grid cell properties to see what properties are available (this is dependent on the version of KCML).
HEX(02) Error illegal grid cell references. This means cells where the row is negative or greater than rows, or the column is negative or greater than cols.
HEX(04) Error out of range field array access. This means that in expressions such as FLD(a$.b<x>) the value of the fld .b must be declared to have an occurs including x in its range. Traditionally this has never thrown a run-time error and some legacy code will declared flds with no array information but using them in array situations knowing that the string is sufficiently sized.
HEX(08) Error illegal grid cell references in Form.Imports.
HEX(10) For a callback function that is nested inside a parent function, the parent function must be active at the point the callback function is called, as the callback function may want to access the parent function's local variables. The testing for this error can be quite expensive when the callback is in a tight loop and should not be enabled in production code.
HEX(20) Enable warnings in the client. This catches problems such as bad tab order, edit controls not inside their edit groups, edit controls whose typing means that the control is too small to display all possible values and other issues.
HEX(40) Enable warnings about misuse of anchoring on controls. For instance it does not make sense to adjust the width of a control that has both left and right anchoring.
HEX(80) Enable errors parsing invalid utf8 chars in rems and literals
63Reserved
64 Modifies form of SAVE ASCII files
HEX(01) Save in a flat format. Does not add indenting for the bodies of loops or functions. This mimimises the differences when the file is saved.
65OPTIONS_RUN_Compatibility2 This byte controls the reporting of some errors for backward compatibility. These errors trap programming conditions that are wrong, but would have silently failed in previous versions of KCML. Because they are known to introduce run-time errors in applications that previously worked, these errors are by default disabled, unless indicated otherwise. They may be enabled using this byte, and developers are encouraged to do so. Currently four bits are defined:
HEX(01) Error setting DataField$ to a field that does not exist in the record defined by the data binding. This bit is set by default.
HEX(02) Error references to controls that do not exist (e.g. a form control declaring the menu, but no menu exists on the form). This bit is set by default.
HEX(04) Throw an O30 runtime error for certain fatal database return codes such as KE_BADHANDLE which indicate programming bugs rather than run time exceptions. See here for a list of fatal error codes. This bit is set by default but will be ignored on systems with the environment variable LIBRARY set.
HEX(08) Throw a P59.20 if attempting to DIM a scalar string to a different size than a previous DIM statement. This was an error in KCML 6.0 and was then disabled in later versions of KCML.
HEX(10) Allow SELECT #0 as an alternative to SELECT DISK without throwing a P34.6 error. This makes KCML 7.21 and above behave like KCML 6 where this is permitted. The error was introduced to stop code that accidentally used an unset variable in SELECT # not to have unintended side-effects.
HEX(20) Do not use certain operators that prevent binary incompatibility betweeen 7.21/7.22 KCML and 7.18 KCML. These operators allow the storing of exact case for reflection and determining of the parent function of nested functions in diagnostics, at the expense of being able to load binaries in 7.18.
66OPTIONS_RUN_LoadOptions_NewAscii This BYTE combined with BYTE 46 controls how programs are loaded.
BIN(0x01) This is a bit that can be combined with any of the values above. Behaviour is as before except that whenever source file is loaded it will be loaded using the text format rules. This options was introduced in KCML 7.02.
67OPTIONS_RUN_Disable_CanConvertSetting this BYTE to HEX(01) will prevent any CanConvert properties being passed to KClient. This means that any NUM(prec, scale) fields will display according to type without reference to locale settings for Currency on the client machine.
68OPTIONS_RUN_AssertsBitmask controlling the behaviour of ASSERT statements at runtime. Two bits are defined, plus a zero constant for convenience:
HEX(00) (_KCML_ASSERT_DEFAULT) Default options - all bits disabled
HEX(01) (_KCML_ASSERT_TEST) Enables testing of ASSERT statements - if unset, they will be skipped
HEX(02) (_KCML_ASSERT_CONTINUE) Failed ASSERTs will not stop execution, instead acting like PANIC CONTINUE
HEX(04) (_KCML_ASSERT_NOFILE) Failed ASSERTs will not write panic files
69OPTIONS_RUN_DollarIfControls the behaviour of $IF statements at runtime. Three levels are defined:
0 Default behaviour: $IF will not behave differently inside a transaction
1 Optimistic transactions will be committed
2 As above, and will error when running in WHILE TRANS
70OPTIONS_RUN_DeleteNonEmptyPoolHookControls the behaviour of the DeleteNonEmptyPool hook. Two bits are defined.
HEX(01) (_KCML_DELETE_NON_EMPTY_POOL_HOOK_SUPPRESS_FOR_DELETES) Do not call the DeleteNonEmptyPool hook for DELETE PTR or DELETE POOL statements
HEX(02) (_KCML_DELETE_NON_EMPTY_POOL_HOOK_SUPPRESS_FOR_ENDSUBS) Do not call the DeleteNonEmptyPool hook for allocations cleaned up at the end of a function
71OPTIONS_RUN_PromoteLocalDimStruct If TRUE, LOCAL DIMmed strings that are single instances of DEF STRUCTs will be backed by NEW PTR.

$OPTIONS RUN as a record

KCML defines a KCML_OPTIONS_RUN built in DEFRECORD that can be used to access the fields in $OPTIONS_RUN e.g. 

klang = FLD($OPTIONS RUN.OPTIONS_RUN_Language)

See also:

$OPTIONS, $OPTIONS LIST, Internal structures