# Emulation

Updated: 1/18/2022, 5:31:44 PM
Created: 1/18/2022, 5:31:44 PM
Last Updated By: dependabot[bot]
Read Time: 26 minute(s)

Tags: configuration config_emulate

# Description

Emulation support is provided by the Config_EMULATE file. This file is located in $JBCGLOBALDIR/config (on Linux/AIX) or %JBCGLOBALDIR%\config (on Windows). All text in the file is case insensitive. A companion file, Config_EMULATE.txt, with descriptions of all of the configuration options can also be found in the same location.

The format of that file is:

Code Definition
# Denotes a comment and the line is ignored.
label: Denotes the name of the emulation, signifying the start of an emulation definition.
key = value Denotes a configuration entry within the emulation definition, where key is the configuration option and value is the setting.

Labels must be alpha-numeric, i.e. no periods, commas, semi-colons, dashes, underlines, etc. If one label directly follows another then the label is a synonym for the same emulation definition. The emulation definition ends when another label is found or the end of file encountered.

Multiple emulation definitions can be defined on the same line with each definition delimited by a comma or a semicolon. Emulation definitions can be interrupted by blank lines and can contain any amount of white space, i.e. one or more spaces or tab characters.

Emulation definitions can be declared 'on', 'yes' or 'true' to mean the emulation is enabled or similarly use the strings 'off', 'no' or 'false' to mean the emulation effect is disabled.

To use a different set of emulation definitions from the default set, set the environment variable JBCEMULATE in your current environment to the required emulation label. When the environment variable is not configured then the emulation definition defined by the default label is in effect. If the default label is not present then the first label detected will be used for the default emulation.

Generally any emulation definitions which affect BASIC, (such as the @(-n) codes), use the JBCEMULATE environment variable when the programs are compiled, whereas the other definitions tend to be used at runtime, when the program is executed.

You can create your own custom emulation sections in the Config_EMULATE file but it is strongly recommended to use Alternate Emulations instead. This will ensure that important updates are not missed when upgrading to newer versions of jBASE.

# Alternate Emulations

An alternate (custom) emulation has the general form:


where name is the name of the custom emulation. For example, if the custom emulation is named "acme" then the alternate emulation file must be named "Config_EMULATE_acme".

These emulations must be stored in the same location as the master Config_EMULATE file and they follow the exact same rules as above.

Alternate Emulations can contain any combination of configuration options. The first label in the custom file must be the name of the custom emulation (see example below). Any emulation defined in the config directory or in the master jBASE Config_EMULATE can be used as a template for a custom emulation by using the dup directive, in which case all of the configuration settings in the template are inherited in the custom emulation. Additional configuration entries can be added after dup and if the key matches one of the template entries then it will override the inherited entry.

When jBASE is processing dup in an alternate emulation, first the alternate file is searched for the target value of dup and, if not found, then the main jBASE Config_EMULATE file is searched.

If a dup entry is specified and the target emulation is not found then a warning is displayed and the default emulation is used.

For example, to create a custom emulation called jbased3, which inherits from the D3 emulation in the master Config_EMULATE which, in turn, has a dup = jbase entry that inherits from the jbase emulation in the master Config_EMULATE, we will create a file in the config directory called Config_EMULATE_jbased3 with these contents:

      dup = d3
      named_common = unassigned
      md_int_only = true
      md_int_only_emulate_jbase3 = true

In this example, the dup = d3 entry will inherit all configuration options in the d3 section. The d3 section will inherit all of the configuration options in the jbase section. If the jbase section had any dup entries then they would also be inherited, and so on.

All other configuration settings below the "dup" line are either new or will override the inherited setting. This will ensure that you continue to make use of any changes made to the standard D3 emulation.

In this example, the named_common entry overrides the jbase setting. The others are new settings that don't exist in the either of the d3 or jbase sections in the master Config_EMULATE file.

To use the jbased3 emulation, set the JBCEMULATE environment variable to jbased3:

export JBCEMULATE=jbased3    [Linux]
set JBCEMULATE=jbased3       [Windows]

Use the config-strings command to review your configuration.

# Configuration Definitions

The following table is a sample of the available configuration options. A complete list is in the Config_EMULATE.txt file in the config directory.

Variable Description Set At:
allow_bad_day_of_month = true|false If set, allows invalid date conversions like 31 Sep to convert to valid dates (1st Oct). Run Time
allow_unassigned_assignment = true|false Suppress "UNASSIGNED VARIABLE" message where "X=Y" and Y has not been assigned. Run Time
alternate_chain_exit = true|false If set then under certain circumstances drops an extra run level on returning from a CHAIN command. This is an emulation of jBASE 3.4 behaviour. Current behaviour is believed to be preferable. Only set this if necessary for backwards compatibility. Run Time
alternative_oconv = true|false If set then for the "DD" and "DM" output conversions, single digit results are prefixed by zero. Default for Sequoia. Run Time
breakon_l_suppresses_blank_line = true|false If set then "L" in a "BREAK-ON" clause means suppress the blank line before the data line. The default is to skip the break line, i.e. only output a blank line. Run Time
byexp_mv_dup_like_d3 = true|false If set, when using BY-EXP, reuse the first, and only, value in single valued attributes. The default behaviour, i.e. with "byexp_mv_dup_like_d3" unset or false, is to assume a null value for the 2nd and subsequent values. Run Time
case_insensitive_file_ids = true|false If set, try and ignore the case of file names, default behaviour will be to open the first UPPER CASE version of the file name. Run Time
case_insensitive_md = true|false If set, the MD does not care about case, everything should end up as UPCASE. Run Time
case_insensitive_queries = true|false If set, verbs used in jQL queries and dictionaries ignore case. Run Time
case_insensitive_runtime_strings = true|false If set, any jBASE functions which accept a VAR as a parameter will UPCASE it. Run Time
chk_typeahead_on_inputminus = true|false If set then check for type-ahead when INPUT x,-1 syntax is used. Run Time
compiler_case_insensitive_subroutines = true|false If set, all SUBROUTINE names are case insensitive. Compile Time
compiler_case_insensitive_variables_keywords = true|false If set, the compiler ignores the case on variable names and keywords. Compile Time
compiler_options = list of options This list is pre-pended to the JBC_JPP2 environment variable (see "jpp2 -h" for options). Compile Time
compiler_requires_explicit_item_list = true|false If set, forces the BASIC, CATALOG, DECATALOG commands to require an explicit item-list or "*". Compile Time
conv_mct_uv_compat = true|false Universe compatible capitalisation after non-alpha characters. Run Time
conv_old_mct = true|false Capitalise character following non-alpha character, e.g. "-" (hyphen). Run Time
dates_upper_case = yes|no
If "yes" then date conversions (e.g. "DM" and "DW") force the text to uppercase format, e.g. "March" is forced to "MARCH". Without this option, the casing for dates is dependent upon the operating system.
Run Time
defer_header_output = true|false
Set by default under Ultimate emulation. Any Basic HEADER will be output at the next natural page break. Normally the HEADER is issued immediately. The output of the HEADER can also be deferred, to the next natural page break, by prefixing the HEADER data with an Attribute Mark (@AM).
Run Time
dict_sub_call = true|false
On some emulations, when calling a SUBROUTINE from a DICT item, a parameter will be passed to the SUBROUTINE which is the current item -- if this is the case, set this to "true".
Run Time
dot_not_numeric = true|false
Set to true for compatibility with systems that expect ".", "+" and "-" to be treated as non-numeric characters.
Run Time
dup = name
Duplicates the definition "name", where "name:" is a previously defined "label:", i.e. this "definition" inherits the behaviour defined for "name:", "option" settings following a "dup" override the inherited behaviour for that "option".
enter_keeps_common_data = true|false
Set if you want the ENTER statement to retain global common when "(I" option is used.
Run time
error_numbers_are_single_attribute = true|false
If set, check that the first value is a number, if so use it as the error message, (i.e., return 401 instead of 401]QLSELNO) (Could be problematic).
Run time
ext_pattern_match = true|false
For systems which use extended pattern matching.
Compile Time
format_defaults_no_decimals = true|false
If set, a format mask that does not specify decimal places will not output any decimals. Default is to output all decimal places.
Run time
generic_pick = true|false
The emulation will otherwise behave as if coming from a Pick environment.
Compile Time1
generic_prime = true|false
The emulation will otherwise behave as if coming from a Prime environment.
Compile Time1
generic_reality = true|false
The emulation will otherwise behave as if coming from a Reality Operating System environment.
Compile Time1
generic_universe = true|false
The emulation will otherwise behave as if coming from a Universe system.
Compile Time1
generic_unidata = true|false
The emulation will otherwise behave as if coming from a UniData environment.
Compile Time1
header_with_s = yes|no
For systems (Sequoia) S-types with null "header" WILL use the default column heading.
Run Time
hush_input_and_output = true|false
If set then control both input and output on HUSH.
Run Time1
iconv_nonnumeric_return_null = true|false
If true then ICONV will return null instead of the original value when that value is non-numeric and numeric is expected.
Run Time
insert_default_zero_to_one = true|false
If set, treat a param value of zero as one for INSERT function.
Run Time
invert_F_correl = yes|no
Set this for systems (Reality) where the F correlative operates on the top stack elements in the reverse order to that expected for certain operators
Run Time
itype_trans_replace_delim = true|false
Set to replace delimiters with spaces in the TRANS() function ( ITYPES only ).
Run Time
itype_unquoted_numeric_literal = true|false
Set for systems (Universe/UniData ) where the 3rd and 4th parameters of the 'FIELD'' function can be specified as an unquoted numeric. The unquoted numeric will be treated as a numeric literal in these cases, rather than an attribute reference.
Run Time
jbase_field = yes|no
For systems (jBASE and Prime), FIELD function will use the entire delimiter not just the first character.
Run Time
jpqn_replace_semicolon = true|false
Set by default under Ultimate emulation. When moving data from the Input buffer to the Primary Output buffer using the A command in PQN Procs, any semicolons are replaced with specified delimiter, e.g. : A' changes abc;def;xyz to abc"def"xyz.
Run Time
jql_A_substring_literal = true|false
For systems (as yet unknown) which assume unquoted numerics (inside substring extraction) should be treated as Numeric literals (NOT attribute references as expected by default).
Run Time
jql_acalc_int_only = true|false
Set for systems (Reality, R83, Universe) where integer only arithmetic is performed in calculations within "A;" correlatives/conversions.
Run Time
jql_divide_by_zero_zero = true|false
For systems (R91), division by zero in conversions/correlatives will return zero. (The default behaviour is to return the numerator unchanged).
Run Time
jql_mv_subcall = true|false
For systems (Sequoia) the user subroutine will be called for each multi-value and sub-value in data being processed by jQL. Default is false
Run Time
length_field_formatting = true|false
For systems that precede formatting with a length field.
Run Time
list_keys = yes|no
If set then commands such as T-DUMP , T-LOAD , COPY will by default display all the record keys and use the (I) option to suppress this. Without this option then by default the reverse is true e.g. T-DUMP will not list any record keys but the (I) option indicates that record keys should be displayed
Run Time2
locate_null_only_in_array = yes|no
Set for systems requiring null to only match within the real array, not the implied array, e.g. : FIND "" IN "abc" will return 'true' under the default mode.
Run Time
long_who = yes|no
If set, the WHO command is extended to give the node name and UNIX account name.
Run Time
log_runtime_errors = true|false
If true, runtime errors such as divide by zero are logged in the $JBCRELEASEDIR/runtime-errors directory, assuming the error message in $JBCRELEASEDIR/jbcmessages contains the string ^LOGERRORS^.
Run Time
make_locate_dr_like_dn = true|false
Set for systems requiring the DR of the LOCATE statement to act like DN.
Compile Time
match_last_delimiter = true|false
If set to 'true' then the last delimiter in pattern match string is used within the pattern to match, e.g.: "a]b]c]" will match "c]".
Run Time
matread_assigns_to_end = true|false
Additional attributes are appended to the last element of a DIMensioned array by 'MATREAD'. By default additional attributes are returned in element '0' of the DIMensioned array. Set 'true' under Sequoia emulation.
Run Time
md_int_only = true|false
If set, only integers will be allowed in MD or MR conversions. If a decimal number is used then it will be treated as non-numeric, returning the original value, e.g. OCONV(12.99,'MD2') returns '12.99' instead of '0.13' .
Run Time
multiple_cmd_execution = true|false
For systems that allow execution of multiple commands if provided as a dynamic array to 'PERFORM'/'EXECUTE' statements.
Run Time
named_common = unassigned|null|zero
Indicates how to set named common when first referenced. Default is unassigned.
'setting' can be :

no_equate_on_call = true|false
If set, inhibit the Equate processing on the 'Subroutine' name specified in CALL statements but not CALL @ statements.
Run Time
no_extra_delimiter = true|false
For systems ( currently Sequoia and R83 ) which do not insert a delimiter (AM/VM/SVM) if the current string being appended to ( by specifying '-1' as the parameter to append/insert before ) has a 'trailing' delimiter (AM/VM/SVM ) already. This behaviour is true for all of :

no_id_prompt = true|false
For systems (Sequoia) which do NOT 'prompt for ids' when using 'QSELECT' (for example) and no items are specified. If 'no_id_prompt' is set do NOT 'prompt' for the item ids but assume '*' (i.e. ALL items) are required.
Run Time
no_value_maths = true|false
If set to 'true' then jBASE will NOT perform automatic multi-value maths on a non-numeric string, e.g. : A = "12":@AM:"3" + 1 will fail with a 'NON_NUMERIC' error.
Run Time
nopage_null_header = true|false
For systems (as yet unknown) which do NOT expect a pause at the end of Page when a Null HEADING is requested in Basic. The default behaviour is to leave this 'flag' unset.
Run Time
null_eq_zero = true|false
For systems (Universe) right justified null fields will sort equal to zero.
Run Time
oconv_format_null = true|false
For systems whose OCONV functions force formatting of null values.
Run Time
oconv_no_mask_formatting = true|false
For systems that do not use OCONV mask formatting when value is null or nonnumeric.
Run Time
oconv_no_scale_formatting = true|false
For systems that do not using a scaling factor by default for OCONV formatting.
Compile Time
old_jql_output_style = true|false
If set then the number of spaces between columns, for the jQL LISTand SORTcommands, is always 1.

If not set then jQL adjusts the spacing between columns depending on the number of columns and the width setting of the TERM command. The maximum number of spaces between columns is 4.

This option is only effective when the jQL display is in columnar format.
Run Time
openseq_creates = true|false
When set, the jBC OPENSEQ statement will create the specified file if it does not exist. This parameter is set by default for Sequoia.
Run Time
page_0_header = true|false
For systems (Sequoia) PAGE 0 will clear any existing HEADINGs and FOOTINGs.
Run Time
para_stacked_data = true|false
Set by default under Unidata emulation.
Externally stacked 'DATA', passed from a Basic program to an 'EXECUTE'd PAragraph, is only used to satisfy 'INPUT' requests within the PAragraph and is not passed indirectly to programs 'EXECUTE'd from the PAragraph, e.g. :

pq_Aquote_prepends_space = true|false
( Currently not enabled under any emulation by default).
This option can be enabled to assist in the construction of 'commands' within the Proc Output buffer.
Specifically for Proc's where a required trailing space has been omitted during creation of the Proc, e.g. :

pq_backslash = true|false
If set, PQ procs will use backslash delimiters when extending past the end of input buffer with Sn or Rin. Default for Sequoia.
Run Time
pq_indirection = true|false
If set then PQ procs can execute PQN proc commands (Universe).
Run Time
prime_runtime_errors = true|false
'ZERO_USED' , 'DIVIDE_ZERO' and 'NON_NUMERIC' errors generate message ids appended with '_PRIME', eg 'ZERO_USED_PRIME' , 'DIVIDE_ZERO_PRIME' and 'NON_NUMERIC_PRIME' etc.
Run Time
print_initial_formfeed = true|false
Set by default under Ultimate emulation.
Under normal circumstances the leading form feed, from a HEADER, is suppressed in PRINTed output.
This emulation mode causes such form feeds to be PRINTed at the start of the PRINT jobs.
Run Time
prt_video = true|false
Support the following extensions, mainly for printer definitions : @(-27) to @(-33) , @(-47) to @(-55) and @(-59) to @(-126) , and @(-220) through @(-239).
Run Time
quit_eq_end = true|false
Quit (or Stop) from the debugger has the same effect as End or Abort, meaning any calling proc or paragraph is terminated.
Run Time
read_reset_as_null = true|false
For systems which, when a read fails, reset the read variable to a null string.
Run Time
readnext_dont_null_last_key_on_eof = true|false
If set, then retain the value of the last key on a READNEXT instead of setting it to NULL when EOF is reached.
Run Time
readv0 = binary|dcount|key
When a READV (or READVU) is performed and attribute 0 is specified, this defines what to return:

reality_video = true|false
Support the Reality video extensions from @(-128) through @(-191) for video effects such as combinations of reverse, underline, flashing and so on. These can usually be added to all emulations without harmful effects.
Run Time
reformat_append = true|false
By default the REFORMAT command overwrites existing attributes. With this set, then the REFORMAT command will append a multi-value to existing attributes.
Run Time
report_bad_tapeblksz = true|false
Attempting to write a 'NULL' tape block or a block which is larger than the attached tape block size will return the appropiate error code in SYSTEM(0).
This option is NOT set by default for any emulation.
Run Time
resize_array = true|false
If true then the re-DIMensioning of arrays is permitted. Set to 'true' under 'Universe', 'Prime', 'Unidata' and 'Ultimate' emulations.
Compile Time
returning_am_delimited = true|false
If set then data returned from the RETURNING/SETTING clause of the EXECUTE statement will be attribute mark delimited. Otherwise the data will be value mark delimited.
The default is true for Sequoia, otherwise false.
Run Time
round_neg_tozero = true|false
Round -0.5 to 0 instead of to -1. This does not affect 0.5.
Run Time
scale_masked_string = true|false
For systems (Reality) where formatted strings are descaled by the specified scaling factor, e.g.:

selected_count_not_binary = true|false
SYSTEM(11), which returns the status of the default select list will, by default, return 1 if a default select list is present, or 0 if no default select list is present. If this option is set, 'SYSTEM(11)' returns the number of items in the default select list.
Run Time
single_space_timedate = true|false
The TIMEDATE() function uses a single space separator (default is two spaces).
Run Time
skip_pib_on_ip_null = true|false
If set, leave PIB unchanged when null entered at IP command in PQ proc.
Run Time
skip_spaces_and_tabs = true|false
For systems which ignore leading and trailing spaces when handling values for maths.
Run Time
sline_with_heading = true|false
For systems (Prime), specifying a heading in jQL will NOT suppress the "n Records listed." messages.
Run Time
sp_assign_all ==true|false
For systems (Reality), where SP-ASSIGN without a 'channel' number will assign the specified form to ALL 'channels'. By default SP-ASSIGN without a specified 'channel' number only assigns to 'channel 0 (zero).
Run Time
spooler4_only_recent_jobs = true|false
Set by default under Reality emulation.
Under normal cicumstances ALL print jobs for the specified port will be returned by the SPOOLER(4) function. This emulation limits the information returned to those Print jobs created by the specified/current port, since the program issuing the SPOOLER(4) was started.
Run Time
stacked_input_global = true|false
Set if the DATA stack operates globally or traditionally i.e. : determines whether 'unused' stacked DATA is still available on return from 'EXECUTE'.
Run Time
substring_zero_eq_one = true|false
For systems (Reality) which treat a starting position of '0' as '1' in substring assignment, e.g. : x[0,1] = bla is equivalent to x[1,1] = bla.
The default behaviour, for 'x[0,n] = value' is to prepend to the original string. With 'substring_zero_eq_one' set, the first 'n' character(s) are replaced, e.g. : where 'x' is originally 'abc', x[0,1] = 'z' will give : 'zbc' with 'substring_zero_eq_one' set and 'zabc' by default.
Run Time
system_19_timedate = true|false
SYSTEM(19) will return a unique 'date + time' stamp, e.g. '1103361234' when compiled under this emulation, (rather than the 'account name'). (Sequoia emulation).
Run Time
tconv_no_replace = true|false
By default the T conversion in OCONV will replace system delimiters. This causes that effect not to happen.
Run Time
time_is_hours = true|false
For systems (Reality and Sequoia) ICONV(1,"MTS") will return 3600 (not 60).
Run Time
treat_with_as_and_with = true|false
If set treat jQL WITH <Clause> WITH <Clause> as AND WITH - default is OR WITH.
Run Time
treat_with_as_or_with = true|false
If set treat jQL WITH <Clause> WITH <Clause> as OR WITH - [ this is the default behaviour].
Run Time
unnamed_common = unassigned|null|zero
Indicates how to set un-named common when first referenced. Same as 'named_common'.
Run Time
use_id_lptr_reporting = true|false
For systems (Prime) that use @ID and @LPTR for default listings.
Run Time
use_sql_syntax_for_select = true|false
Use SQL syntax in SELECT commands.
Run Time
use_uv_locate = true|false
When set to 'true', use the Universe syntax for the Basic 'LOCATE' function, i.e. 'search string' and 'array to search' parameters are interposed.
Compile Time
ux1ad_use_four_digits = true|false
If set, user exits U11AD, U21AD and U31AD will generate four digit rather than two digit numbers. i.e. nnnnP vs nnP
Run Time
wrap_r_just = true|false
For systems (Universe and Prime), right justified data will wrap in jQL.
Run Time
writelist_on_select_from_var = true|false
If set then write any select list, generated by basic "SELECT Var" to the default select list.
Run Time

# Note

Some of the "generic" emulation behavior will change at run-time, but for a complete change, the code should be recompiled.

Despite being set at Run-time, if running from jshell, requires that a new jshell be invoked before the behavior will change.

On many platforms, @(-n) codes are used to control special terminal characteristics. However the definition of these codes differs between platforms. Rather than "hard coding" the @(-n) codes, jBASE allows their definition in the Config_EMULATE file. This allows legacy applications to use existing @(-n) codes and so reduces the time required to port an application to jBASE. A knowledge of terminfo capabilities can be useful when defining these codes.

Code Action Description
@(-n) clear_screen Move cursor to position 0,0 and clear to end of screen
@(-n) cursor_home Move cursor to position 0,0
@(-n) clear_eos Clear the screen from current position to end of screen
@(-n) clear_eol Clear the screen from current position to end of line
@(-n) blink_on Turn on blinking video
@(-n) blink_off Turn off blinking video
@(-n) prot_on Turn on protected fields
@(-n) prot_off Turn off protected fields
@(-n) reverse_on Turn on reverse video
@(-n) reverse_off Turn off reverse video
@(-n) underline_on Turn on underline video
@(-n) underline_off Turn off underline video
@(-n) bold_on Turn on bold video
@(-n) bold_off Turn off bold video
@(-n) printer_on Turn on the slave printer
@(-n) printer_off Turn off the slave printer
@(-n) print_screen Dump the entire screen to the printer
@(-n) status_line_on Turn the line 25 status line on
@(-n) status_line_off Turn the line 25 status line off
@(-n) cursor_down Move the cursor down one position
@(-n) cursor_up Move the cursor up one position
@(-n) cursor_right Move the cursor one position to the right
@(-n) cursor_left Move the cursor one position to the left
@(-n) cursor_on Turn the visible cursor on
@(-n) cursor_off Turn the visible cursor off
@(-n) delete_line Delete a single line
@(-n) insert_line Insert a single line
@(-n) scroll_forward Scroll the screen display up one line
@(-n) scroll_backward Scroll the screen display down one line
@(-n) delete_char Delete a single character at present cursor position
@(-n) insert_char Insert a blank character at present cursor position
@(-n) insert_on Begin insert mode
@(-n) insert_off End insert mode
@(-n) effects_off Turns off ALL the video effects
@(-n) graphics_on Turn on the alternate character set
@(-n) graphics_off Turn off the alternate character set
@(-n) graphics_vertical In graphics mode a vertical bar
@(-n) graphics_horizontal In graphics mode a horizontal bar
@(-n) graphics_upper_left In graphics mode a top left hand corner
@(-n) graphics_upper_right In graphics mode a top right hand corner
@(-n) graphics_bottom_left In graphics mode a bottom left hand corner
@(-n) graphics_bottom_right In graphics mode a bottom right hand corner
@(-n) graphics_intersection In graphics mode + intersection character
@(-n) graphics_tee_left In graphics mode a left hand tee character
@(-n) graphics_tee_right In graphics mode a right hand tee character
@(-n) graphics_tee_up In graphics mode a top tee character
@(-n) graphics_tee_down In graphics mode a bottom tee character
@(-n) background colorname Set the background to one of the supported colors , where "colorname" is one of: black , blue , green , cyan, red , magenta , yellow , white
@(-n) foreground colorname Set the foreground to one of the supported colors , where "colorname" is one of: black , blue , green, cyan , red , magenta , yellow , white

Back to Articles