Syntax

Parts Of A Business Rules Statement

Statements

A typical Business Rules! statement consists of the following:

1. A line number.
2. A line label (optional).
3. A primary keyword or its abbreviation.
4. One or more secondary keywords or phrases along with their associated values (sometimes optional).
5. One or more "error condition line-ref" conditions (optional).
6. Remark or comment (optional).

"Optional" items may be included but are not required.

Notice that the listed elements refer to a typical statement. Some statements consist mainly of a primary keyword RETURN or RETRY for instance, only the line number and optional programmer's remarks or a line label are permitted with these two statements. See the syntax diagrams for individual Statements for specific details.

Analysis of an Example Statement

The following formatted Print statement will be used to describe the components of a statement:

00020 BIG: PRINT USING F1: A$,T(5) CONV 00520 ! comments

00120	is a line number.
BIG	is a line label.
PRINT	is a primary keyword. Primary keywords specify the type of operation that you wish to perform.
USING F1	is a secondary phrase. This phrase consists of the secondary keyword USING and the line reference F1 (a line label). Secondary keywords and secondary phrases add detail to the instructions in the statement.
A$ and T(5)	are references to variables.
CONV 520	is an "error-cond line-ref" specification. It transfers control of the program to line 00520 if a CONV error occurs during execution of line 00120.
! comments	is an optional comment that follows the statement. An exclamation point signals the start of this remark; any comment the programmer wishes to make may follow. Note that certain statement keywords, for example, DATA, do not allow for comments on the same line, in which case comments must be placed on an adjacent line alone.

Each command in a procedure file may be followed by at least one space, an exclamation point (!) and a comment. Business Rules will ignore everything after the exclamation point.

Remarks may also reside on their own line in a procedure file, as follows:

LOAD MENU.BR
! Load the program MENU.BR
RUN

Line numbers

Line numbers in Business Rules! are five digit numbers which indicate the flow of the program. Each statement is assigned to a line number located at the beginning of that line.

The "line-num" parameter indicates that you must specify a line number rather than a line label, whereas the "line-ref" parameter allows for either a number or label. For most purposes, using a line label is recommended. Line numbers can be used only in programs (not in procedure files, which require line labels) and must be integers from 1 to 99999.

Every Business Rules! statement that is executed from within a program must be on a line with a line number. Line numbers may range from 00001 to 99999 (commas are not allowed). While a program may theoretically contain up to 99,999 lines, the actual limit depends on the statements used, the amount of memory available, and the release of Business Rules! being used.
It is not necessary to insert zeros before line numbers such as 10 or 4035, since Business Rules! automatically re-lists these numbers as 00010 and 04035.

During editing it is not necessary for line numbers to be in order. Business Rules! will reorder lines based on their line numbers so that code can be developed out of sequence and then cleaned into sequence.

While working with a program, it is often easier to work without line numbers. Lexi is a program which allows you to do so, then lists the line numbers back into your program before running it in BR.

Line number tools include the Auto and Renum commands,

Related external editor features are MyEditBR's refoctoring and Notepad++'s column renumbering.

Line labels - Program files

The Line label is an optional name for a program line. They are accepted at the beginning of all statements following the line number. The label may be from one to 30 alphabetic, numeric or underscore characters in length, but must begin with a letter. Each line label must be unique and immediately followed by a colon. Business Rules allows most statement and command keywords to be used as line labels. In the following statement, "LABEL_SAMPLE:" is a line label:

00900 LABEL_SAMPLE: Rinput #1, Select '2,40,Cr 10,[w]',Attr "[A]": Autoselect$

A line label can then subsequently be used in place of a line number to reference the line from a secondary expression. In the following example, the line label BIG is defined to represent line 120; it is then used as a line reference for the GOTO statement in line 300. (F1 is also a line label):

00120 BIG: Print Using F1: A$,T(5)
o
o
o
00300 GOTO BIG

Line labels are often used to easily refer to form statements:

1100 read #10,using Addressform: Mat Co$,City$,St$,Zc$,Mat Dd$
1110 Addressform: form 3*C 30,C 20,C 2,C 12,Pos 257,10*C 18

For information about the labels that are used in procedures, see Line Label (procedure).

Line labels - Procedure Files

Commands in a procedure file may start with a line label. The label must begin with a colon (:) and may be up to 800 alphabetic, numeric or underscore characters in length (spaces are not allowed). Procedure labels do not have to be followed by a command. Both the following procedure lines are acceptable:

:NEXTRUN
:START PROC MENU

When typed in without a line number and during READY mode, most statements can be executed immediately. Statements without line numbers or labels may also be included in procedure files. Statements used in both these ways may include a comment at the end of the statement.

The comment must be separated from the rest of the statement by at least one space and an exclamation point, or it may be set off with the use of the REM statement.

The following example shows the OPEN (Ope) statement being used in immediate mode:

OPEN #1:"name=test1",Internal,Input,Sequential

Line Continuation

An !: in Business Rules! code performs a line continuation.

More than one clause (or statement) can reside on a single line when the statements are separated by a colon (:). When the statements are separated by both an exclamation point and a colon (!:), Business Rules will list them to separate physical lines, even though they continue to belong to the same line number. Each portion of a line seperated by an !: is referred to as a sub-line.

Paragraph labels following line continuations are not allowed. However they are allowed following a subline comment out (!), for example:

00010 TOP: ! !:
      Print Newpage

Comments

Business Rules! lines may include a comment after the statement(s). The comment must be separated from the rest of the statement by at least one space and an exclamation point or the REM statement.

The keywords for comments are:

Rem	Used to comment out a whole line number, or the remainder of a whole line.
!	Used to comment out just one sub-line (see line-continuation), or the remainder of a sub-line. Can be used in a Sort Control File.
Use	Not suggested, but preserved for legacy purposes. It is similar to Rem.

Uppercase VS Lowercase Letters

Throughout this reference material, uppercase letters are generally used to denote the names of commands, statements, functions and other specifications. Uppercase is also used with the names of most files or programs except where the file or program being referred to is exclusively used with the Unix or Linux operating system. Regardless of your operating system, Business Rules accepts both uppercase and lowercase letters as identical except when they are used in a literal string. It defaults to displaying all but literal strings in uppercase (see the BRConfig.sys STYLE specification to change this default).

Syntax Explanation

Each page contains both syntax notation and a diagram.

The non-diagrammed syntax conventions are as follows

• Uppercase syntax words are required BR keywords that may be specified as acceptable abbreviations.
• Although the keywords are uppercase in the diagrams, they may be specified in upper, lower or mixed case.
• Items in [square brackets] are optional.
• [,...] indicates the preceding term can be repeated (comma separated).
• A bar | within a braced group (e.g. {aaa|bbb} )signifies OR, meaning the braces enclose a bar separated list. One of the bar separated terms must be specified.
• Terms in <angle brackets> must be replaced with appropriate items. When not inherently logical i.e. #<integer>, item descriptions are found in its link or subsequent lines.
• Punctuation, other than "{}, [], <> and ...", must be specified - i.e. quotation marks, commas, colons etc.
• Spaces between items mean one or more space is required.
• Additional spaces may be specified ahead of or following commas.

Example:

blue {black|grey|white} red {pink|orange}

Satisfactory outcomes would be:

blue black red pink     
blue grey red orange  
blue white red pink 
etc...

• All program lines require a line number (although it's not included in syntax notation).

Example: Delete Statement

DELETE #<file number>[,REC=<numeric expression>|,KEY=<string expression>][,RESERVE|,RELEASE] : [<error condition> <line ref> [, ...]]

      numeric expression
      <number>|<numeric variable>|<numeric internal function>|<numeric user-defined function>|<conditional expression>
  
             number
             <A rational number up to 15 digits long>. See RD in BRConfig.sys.
  
             numeric variable
             <1-30 alphanumeric characters and underscores, the first of which must be a letter (but not FN). They also cannot be reserved words> 
  
             numeric internal function
             <An internal function which produces a numeric value>
  
             numeric user-defined function
             <A user defined function that returns a numeric value>

           conditional expression
           <number> <comparison operator> <number>
           |<numeric expression> <comparison operator> <numeric expression>
           |<numeric expression> <comparison operator> <numeric expression> {AND|OR} <conditional expression>
           |<string expression> <comparison operator> <string expression>
           |<string expression><comparison operator><string expression> {AND|OR} [NOT]<string expression><comparison operator><string expression>}

      Conditional expressions evaluate to a boolean numerical value where zero is regarded as false and non-zero is regarded as true. Parentheses, of course, are significant and affect the order of processing. Additional parentheses (properly specified) can be used for visual clarity with no affect on performance.  

      string expression
      <string internal function>|<string user-defined function>|<string constant>|<string variable> [<substring operations>] [<concatenation operations>]
  
             string internal function
             <An internal function with a string value>
  
             string user-defined function
             <One with a string value> 
  
             string constant
             <"a series of characters enclosed in quotation marks"> 
  
             string variable
             <1-30 alphanumeric characters and underscores, the first of which must be a letter (but not FN) which ends in a $. They also cannot be reserved words>

Syntax Diagrams and Special Considerations

Diagrams are used throughout this wiki to explain the syntax of Business Rules commands, statements, and various other syntactical specifications. This section explains how to read the conventions used in the diagrams. For more details, see diagram conventions.

Syntax diagrams provide a road map through a command or statement's syntax. Syntax diagrams always follow a logical pattern from left to right. If they require you to pass through a particular parameter, then that parameter is required. If they allow you to bypass a particular parameter, then that parameter is optional. If they allow you to return to the left, that parameter can be repeated multiple times, separated by a delimiter each time.

Although all syntax diagrams (whether for a command, statement or other specification) must be read the same way, the actual specification you are working with may be subject to other requirements or options as well. A statement, for example, must always have a line number. Continue reading for more about these requirements and options.

Parameter Explanations

Array Name

The "array-name" parameter is a name representing either a numeric or a string array. For rules regarding these names, see Variable.

Baud

BAUD=<transmission speed>

The "BAUD" parameter sets the transmission speed in bits per second. It is found in the Open Communications statement. The default is 1200 bps. The valid baud rates for DOS and NetWork versions are 110, 150, 300, 600, 1200, 2400, 4800 and 9600. The valid baud rates for Unix / Linux versions are 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800 and 9600. BR now supports extended communications speeds which test the limits of conventional serial IO hardware. In particular, the following baud rates are permitted:

       19200      38400      57600      115200

Border=Spec

The "BORDER=spec" parameter represents an insertable syntax which is used in the OPEN window statement to identify a border type for the window being opened. See the BORDER=spec for additional information and the syntax diagram.

Bufsize

The BUFSIZE parameter specifies the size of the buffer for DOS versions of Business Rules. The default is 2000 bytes, which is low for high-speed data transmission. To avoid losing data with rates of 2400 bps or higher; an increased BUFSIZE is recommended.

In Business Rules, Unix and Linux versions ignore the BUFSIZE parameter, as the operating systems handle the buffering for these versions instead.

Col

"Col" or "Column" (not to be confused with "columns") is an integer value from 1 to 80 (or the specified width of the window), which indicates a column number on the screen.

Columns

"Columns" (not to be confused with "column") is an integer constant, which indicates the maximum size for the second and following dimensions of an array.

FINE GRAIN FIELD POSITIONING

As of 4.30, ROW/COL and ROWS/COLS in FIELDS operations may be expressed as decimal fractions.

Concatenation

Concatenation is the joining of two or more strings. In Business Rules, the ampersand (&) is the concatenation operator. Concatenation may be used in any output or assignment statement to join any number of string expressions.

See Concatenation for examples.

Corners

<character> <character>

The "corners" parameter is used to specify custom-designed borders for both I/O windows and field help windows. Two characters must be specified for this parameter: the character to be used for the top left corner of the window and the character to be used for the bottom right corner of the window. Business Rules fills in the rest of the characters for you.

Drive

The Drive BRConfig.sys specification abstracts ( translates ) hardware disk storage and network setups to make applications more portable. The Drive specification also allows Linux files to be accessed with MS Windows naming conventions.

Syntax

DRIVE <drive letter>[:], <server-full-pathname>, [<client-full-pathname>], \[<subdirectory-name>]

"drive-letter" is the letter to be assigned and may be followed by a colon. Commas must be used as separators between parameters.

"server-full-pathname" is the OS full pathname and may include the OS drive reference (see examples below). Within BR this will appear to be the root directory on that drive.

"client-full-pathname" is optional and identifies the initial working directory on the client computer.

"subdirectory-name" is optional and specifies a directory beneath the directory specified in the second parameter. The specified name becomes the current directory and must be preceded by a forward slash. This parameter is case-sensitive; Business Rules will not translate uppercase specifications into lowercase letters.

Technical Considerations

1. The first Drive specification identifies the initial current directory when Business Rules! is started.
2. At least one Drive specification is required in the BRConfig.sys file. This makes it clear where the initial working directory is. While the Windows model permits startup with no Drive statement, and permits references to drives with no Drive statement, file sharing protection is not implemented for such drives.
3. The only place that Drive can be specified is in the BRConfig.sys file; it is not valid with the config command.
4. Drive statements must have four parameters. The third parameter may have a null value (be left empty). A backslash in the fourth parameter may be used to startup in the OS directory specified by the second parameter.

Comments and Examples

Business Rules! utilizes a file naming structure similar to MS Windows for file and path references. In BR pathnames backslashes ( \ ) are used to separate directory names even when running on Linux. Also on Linux all filenames specified in programs are set to lowercase when converting to OS filenames irrespective of the case used by BR programs. This is done to simulate case insensitive filenames. Note: this feature may be overridden by the FileNames configuration statement.

Windows uses case insensitive filenames, whereas all Unix derivatives (Linux and Mac) use case sensitive filenames. Therefore, the second parameter of the drive statement is case sensitive for Linux and Mac, but not for Windows. All other drive statement parameters are case insensitive.

The Windows model of BR permits accessing drives without drive statements, but the Status command does not report the configuration of such drives, and file and record locking is not performed on such drives. Therefore you are encouraged to get familiar with the drive statement, and begin using it.

Other BRConfig.sys statement pathnames are subject to preceding drive definitions. In other words any pathname references in the BRConfig.sys file (other than tose appearing in Drive statements) will be translated to OS pathnames via preceding Drive statements. To use actual OS pathnames in BR, begin the names with a colon (which is removed when the pathname is utilized by BR).

"drive-letter" is the Windows-like drive letter (A-Z) appearing in a BR program OPEN string filename (e.g. C:).

"server-full-path" is the actual OS full pathname to the directory referenced by the drive-id. (e.g E:\CUSTFILES or \\MYSERVER\CUST_SHARENAME\) Note that UNC names (beginning with \\server-name) operate significantly faster than drive letter mappings.

"subdirectory" is the parameter of an implied beginning CD command on the drive. BR acts as though your application changed to this subdirectory during startup.

DRIVE C:,F:\MYAPP,SERVER-2,\PRL

Defines a network node (F:\MYAPP) as the C: drive and performs an implied CD \PRL on this drive during startup.

BR assumes that any references to undefined drives (F:, G:, etc.) refer to the root directory on those drives. Also, RECORD LOCKING IS NOT PERFORMED ON SUCH DRIVES. The Protect Reserve command only works on filenames that pertain to drives that are identified by a drive statement.

BR file search order during file OPEN processing

BR executable

Windows Working Directory or Linux/MAC current directory at the time BR is invoked. Note that this may be different from the actual location of BR if a full pathname is given as the executable ( typically from within a startup script ). This "current working directory" is regarded as the BR executable directory.

BRConfig.sys	Command Line Parameter or BR executable directory
WBCmd.wbh	First Drive location
BRServer.dat	BRServer configuration statement or first Drive location
BRSerial.dat	BR executable directory
WBTerm.out	BR executable directory
Initial 'current' directory	First Drive location

Note that pathnames given in BRConfig.sys statements are subject to preceding DRIVE statements. To use actual OS pathnames, begin the names with a colon (which is stripped by BR).

Drive Num

"Drive-num" is a digit which indicates a System/23 drive; Business Rules translates it into a DOS drive letter. This parameter may not be specified with a redirection symbol (>) or when a drive letter is specified.

Error-Cond Line-Ref

The "error-cond line-ref" parameter is replaced with one or more pairs of specifications. "Error-cond" is a specific error condition and "line-ref" is a line number or line label to which control should be transferred if that error occurs. See Error Conditions for more information.

For example:

...EOF donereading...

When the program runs this statement and comes to an End of File error, it will transfer to the line labeled "donereading".

Field Length

"Field-length" is an integer value, which identifies the number of columns in the specified field. This parameter is required as a part of any numeric format specification except PIC.

Field Spec

"Field-spec" represents an insertable syntax that is used to provide field definitions for the full screen processing statements. See Field Specs.

Filenames

"Filename" is a name consisting of alphabetic, numeric or underscore characters and an optional period and extension of up to three consecutive letters. Wildcard characters (* and ?) may be used in file names specified with the COPY, DIR, DROP, and FREE commands. (Prior to Version 3.9, filenames were limited to eight characters) Unix defaulted to case sensitive and DOS/Windows defaulted to case insensitive. Business Rules! defaults to lower case on all platforms, unless overridden by a FILENAMES configuration statement in BRconfig.sys.

This new BRCONFIG.SYS statement controls the appearance of newly created files:

FILENAMES    UPPER_CASE | LOWER_CASE | MIXED_CASE [SEARCH]

The file name requirements for all types of files are identical. However, one item to be aware of is that procedure files which use an extension of .$$$ will automatically delete themselves after closing. See Proc for additional information.

File Num

"File-num" is a numeric expression or an integer from zero to 999 and is always immediately preceded by a pound symbol (#). A file number matches a logical file to a physical file or device. File numbers are defined in OPEN statements, then used in I/O statements for that file or device.

Two special file numbers which do not require OPEN statements are 0 (for input or output to the main BR screen) and 255 (for output to the printer).

No file numbers are required when INPUT, LINPUT, RINPUT, or PRINT are used for I/O from the keyboard or to the display screen.

>file-ref

The ">file-ref" (not to be confused with just "file-ref" which only names the file to be used) parameter causes all information which would normally be printed on the screen to be sent to the file specified in the file-ref (see the "file-ref" description for information about the correct syntax). One special case is the RUN command in which ">file-ref" redirects printer output to a file. Wherever ">file-ref" or ">>file-ref" (with two redirection arrows) may also be specified.

Using one redirection arrow causes the screen information to write directly over any contents that currently exist in the specified file. Using two redirection arrows cause the information that would normally go to the screen to be appended to the end of the specified file. The TYPE command with the >>file-ref parameter may thus be used to append a display file to another file. Likewise, the LIST command may be used with >>file-ref to append the contents of a program to another program which has been saved in source.

(Be careful about line numbers when using this technique, as line numbers that are duplicated in the same file will replace one another upon loading from source.)

Fixed point numbers

Fixed-point numbers are numbers with a decimal point in a fixed position.

"Floating point form-spec" represents a format specification from the following group: D, S, or L. These format specifications are fast, but non-portable. See Format Specifications for more information.

Floating-point numbers are numbers which allow the decimal point to "float" to any position. The Business Rules syntax is nEm, where n is a numeric constant indicating the sign and significant digits in the number, E represents base 10, and m is a signed integer representing the power to which 10 is raised.

The largest and smallest numbers available to the system vary according to the hardware and operating system being used. The system function INF can be used to print the largest possible number on any given system; 1/INF generates the smallest number. For all DOS, Unix and Linux versions available at the time of writing, the largest number is 1.000E+307; similarly, the smallest number is 1.000E-307. Some caution should be used in working with numbers near these extremes (e.g., using exponential notation in SORT). Also, for any given combination of hardware and Business Rules, the system infinity function INF and some testing should be combined to determine whether or not intermediate values used in calculations will be truncated.

Fraction Length

The "fraction-length" parameter is an integer value that identifies the number of digits contained in the fractional portion of the item to be printed or input. This integer must be preceded by a decimal point.

Window Number

"Wind-num" is the number of a window file that has been opened by an OPEN window statement. It must be a numeric expression or integer value that equals a value between 1 to 999. No other open file or open window may use the same value. Open windows do not count against the operating system limit on open files.

Wildcard Characters

Wildcard characters (? and *) may be used in file names and extensions in place of alphabetic or numeric characters. They may not be used in drive, path, or directory specifications. They have the following meanings:

?	means that any character in that position (including null) is regarded as a match.
*	denotes any number of ? characters.

For example:

A:VOL\NAME?.*

The above references all files in subdirectory VOL on drive A with a name consisting of NAME followed by any one character, a period, and any extension, for example NAMES, NAME1, NAME2.txt, NAME3.doc, and NAMET.brs would all be referenced.

Variable Name

A "var-name" or "Variable Name" may be either numeric or string. It may be a subscripted or un-subscripted variable, or an array name preceded by MAT. Var-name items are used mainly in various types of input statements to assign values to variables. They typically occur in lists separated by commas.

String Form Spec

{C|CC|CR|CU|G|GL|GU|V|VL|VU}

The "string form-spec" parameter should be replaced with a string format specification from the following group: C, CC, CR, CL, CU, G, GL, GU, V, VL, VU. The specifications that are applicable for a given statement are identified in the parameters text for that statement. See Format specifications for details.

The CL, CU, GL, GU, VL, and VU specifications are valid only in full screen processing statements (PRINT FIELDS, INPUT FIELDS, and RINPUT FIELD); they cannot be used in either type of FORM statement.

String Expression

<string internal function>|<string user-defined function>|<string constant>|<string variable> {<substring operations>} {<concatenation operations>}

The "string-expr" parameter represents one of several kinds of string elements, including string system functions, string user-defined functions, string constants, and string variables. A string in Business Rules always ends with a dollar sign, for example: STRING$

String expressions may utilize Substring operators (to specify that only a portion of the string be used) and the concatenation operator (to specify that multiple string expressions be combined together).

See also string constants and string variables, functions for string system functions, and the DEF statement discussion for more information about user-defined functions.

Helpstring

The "helpstring" parameter represents an insertable syntax, which is used in the full screen processing statements to specify the user level, window placement and text for field help windows. For additional information and the "helpstring" diagram, see Field Help.

Increment

The "increment" parameter is used in the AUTO ATT and RENUM commands. It represents an integer value, which indicates how much the system should increase the numbers from one line number to the next.

Input

The "INPUT" keyword identifies that the file is to be opened so that its data may only be used as input for the program.

Int and Integer

The "int" parameter represents an unsigned, positive, non-zero whole number.

The "integer" parameter represents a whole number (no decimal points or fractions allowed). NOTE the difference between "integer" and "int".

Internal Form Spec

{B|BL|BH|PD|ZD}

The "internal form spec" parameter should be replaced with a format specification from the following group:

B - Binary
BL - Binary Low
BH - Binary High
PD - Packed Decimal
ZD - Zoned Decimal

See format specifications for information about others.

Key Length

The "key-length" parameter should be replaced with a number that identifies the number of characters (or columns) in the key.

Key Start Position

"Key start-pos" indicates the record position of the first key character for the index.

Length

"Length" is an integer value that sets the maximum length of all elements in the string variable or array.

Line Label

A line label is an optional name for a program line that is specified immediately after the line number. See Line Label (program) or Line Label (procedure).

Line Num

The "line-num" parameter indicates that you must specify a line number rather than a line label. Line numbers can be used only in programs (not in procedure files) and must be integers from 1 to 99999.

Line Ref

{<line ref>|<line label>}

"Line ref" (or "Line-ref") can be either a line number or a line label.

00250
L350
nextone

are all suitable line references.

Numeric Array

"Num-array" indicates that a numeric array name should be specified.

Numeric Constant

The "numeric constant" parameter represents a number consisting mainly of the digits 0-9; other optional elements are a decimal point (.), a minus sign (-) to indicate a negative number, and a plus sign (+) to indicate a positive number (unsigned numbers are assumed to be positive). If a sign is specified, it must precede the digits. Spaces are not allowed in a numeric constant.

Integers, fixed-point numbers and floating point numbers (numbers in exponential notation) are three types of numeric constants. See the following examples:

Number

44

+15.38

-86.34

10,000

Integer

44

n/a

n/a

10000

Fixed Point

44

+15.38

-86.34

10000

Exponential

4.4E+1

1.538E+1

-8.634E+1

1E+4

Numeric Expression

numeric expression
{<number>|<numeric variable>|<numeric internal function>|<numeric user-defined function>|<conditional expression>}
 
number
<A rational number up to 15 digits long>. See RD in BRConfig.sys.

numeric variable
<1-30 alphanumeric characters and underscores, the first of which must be a letter (but not FN). They also cannot be reserved words> 
 
numeric internal function
<An internal function which produces a numeric value>
 
numeric user-defined function
<A user defined function that returns a numeric value>

The "num-expr" or "numeric expression" parameter represents one of five kinds of numeric elements: conditional expressions, numeric constants, numeric variables, numeric system functions, and numeric user-defined functions.

See each definition in this section for more information about conditional expressions, numeric constants and numeric variables. See Functions for more information about numeric system functions. See the DEF statement discussion for more information about user-defined functions.

Numeric Variable

<1-30 alphanumeric characters and underscores, the first of which must be a letter (but not FN). They also cannot be reserved words>

"Num-var" or "numeric variable" is a name that a programmer assigns to a storage location in the computer's memory; it is used for storing a number. Variables are created by being referenced in expressions or by being specified in the DIM statement. When used in numeric expressions, numeric variables can be either subscripted or un-subscripted. When specified in syntax diagrams in this book, however, num-var must be a simple (i.e., un-subscripted) variable name -except when stated otherwise in the "parameters" section for the specific statement.

A numeric variable name can be 1-30 alphanumeric characters and underscores, the first of which must be a letter. Examples of simple numeric variable names include A5, TOTAL, RATE, and EMPLRATE.

The same character sequence may be used as a name for both a variable (scalar) and an array. By adding a $ on the end, the same character sequence may be used for a string variable and a string array. Thus A, MAT A, A$, and MAT A$ all may co-exist in the same program.

Certain words are reserved by Business Rules, and cannot be used as variable names. Note that all words starting with the letters "FN" are reserved, as they are considered user-defined function names. See also Reserved Words.

Numeric Form Spec

{G|GZ|N|NZ}

The "numeric form spec" or "num form-spec" parameter should be replaced with a numeric format specification from the following group:

G - Generic
GZ - Generic Zero Suppress
N - Numeric Display
NZ - Numeric Display Zero

The specifications, which are applicable for a given statement, are identified in the parameters text for that statement. See Format Specifications for information about others.

Outin

The "OUTIN" keyword indicates that the file is to be opened so that information may move in two directions: both into and out of the data file.

Output

The "OUTPUT" parameter indicates that the file is to be opened so that information may only be output from the program to the file.

Parity

"PARITY=spec" is an OPEN communications parameter. The "PARITY" keyword and equal symbol (=) must be followed by one of three replacements for "spec": N (no parity checking), E (even parity) or O (odd parity).

Path

The "path" parameter identifies the sequence of directories to be used. Each directory must be separated by a backslash "\\". When the path does not begin with a backslash, searching begins at the default directory.

PIC

PIC({Z|#|$|*|+|-|^|B|D|CR|DR|DB|,|.}[...])

The PIC format specification converts a number into characters according to the "picture" specified within parenthesis. The "pic-spec" parameter consists of PIC() and one or more characters, which are either insertion characters to be printed as is, or digit identifiers to be replaced with a digit when printed.

PIC may be used with both types of FORM statements (for internal and external files or for display files), and may be used with full screen processing statements. Unlike all other format specifications, PIC has its own set of specifications. These specifications generally fall into two groups: digit identifiers and insertion characters.

As of 4.3, #PIC can be used to process numeric data from a string variable. Similar to #FMT and #G, #PIC indicates that string data should be processed numerically. This works for INPUT FIELDS as well as GRIDs and LISTs.

For example, when used in conjunction with the strings "231.45", "430", etc.:

#pic($##,##0.00-)

will be able to use the numeric values.

Digit identifiers

Digit identifiers indicate that the position they mark should be replaced with digits on output. The symbols that operate as digit identifiers include Z, #, $, *, -, +, ^, ( and ). In some cases (as noted in the following descriptions), these characters act both as digit identifiers and as insertion characters.

Z

The Z (zero suppress) identifier is used to suppress a digit of zero. Zs that are placed to the left of the decimal point will suppress zeros on a digit-by-digit basis. In the following example, the left-most zero is suppressed but the next four are printed:

00010 PRINT USING 20: 000.00
00020 FORM 2*PIC(Z##.##)

The output from this example would be as follows:

00.00

If Zs are to have any effect on the right side of the decimal, all specified positions to the right must contain a Z. Suppression will occur only when the value of the entire number to be output is zero and, in such a case, a blank value will be output. The Zs to the right of the decimal will take precedence over any other digit identifiers or insertion characters in the PIC specification. Output from the following example would be a blank line:

00010 PRINT USING 20: 000.00
00020 FORM PIC(###.ZZ)

#

The # identifier is used for zero fill, for example:

00010 PRINT USING 20: 1000,0
00020 FORM 2*PIC(ZZZ,ZZ#)

Outputs:

1,000 0

When the # symbol is used for numeric input with PIC specifications in INPUT FIELDS or RINPUT FIELDS statements, the cursor will automatically skip over non-numeric characters displayed in the field. (The # symbol must be the only digit identifier in the specification.) For example, when slashes are used in inputting a date, the following line 20 will create an output field eight positions long, but the operator will only be able to key into the six numeric positions:

00010 LET D = 112588
00020 RINPUT FIELDS "5,10,PIC(##/##/##),r": D

$

The dollar symbol ($) character operates as both an insertion character and a digit identifier, with the added rule that only one dollar symbol will be printed. The right-most specified dollar symbol, which is not replaced with a digit, will be output as a dollar sign. Any dollar symbols in PIC positions to the left of this one are output as blanks.

In the following example, the first value is output with no spaces between the dollar sign and the value because the PIC specification is designed to use a floating dollar symbol. In contrast, the second PIC specification identifies only one position where the dollar symbol is allowed: all other characters must either be digits or blanks.

00010 PRINT USING 20: 1000,1000
00020 FORM PIC($$$,$$$),X 2,PIC($ZZ,ZZZ)

Output from the above example would look as follows:

$1,000 $ 1,000

*

The asterisk (*) character operates as both a digit identifier and an insertion character, and it is normally used for printing check amounts. Any specified positions, which are not replaced with a digit, will be output as asterisks. Asterisks may be placed either to the left or to the right of the decimal, as in the following example:

00010 PRINT USING 20: 523.50
00020 FORM PIC($********.**)

Output from this example would appear as follows:

$*****523.50

If the amount to be printed in line 10 were 0 rather than 523.50, the output would appear as follows:

$********.**

-

The minus (-) symbol operates as both a digit identifier and an insertion character, with the added rules that the minus sign will be output only when the value to be printed is negative and that only one minus sign (the one closest to the printed value) will be output per value. (Additional minus symbols will be output as blanks.) The minus symbol can be used to indicate either a leading or a trailing sign, as in the following example:

00010 PRINT USING 20: -100,100,-100,100
00020 FORM 2*PIC( - - -),2*PIC(ZZZZZ-)

Output from the above example would look as follows:

-100 100 100- 100

+

The plus (+) symbol operates as both a digit identifier and an insertion character, with the added rules that plus signs will be output only when the value to be printed is positive, and only one plus sign (the one closest to the printed value) will be output per value. (Additional plus symbols in the PIC specification will be output as blanks; a minus sign will be output in the position specified by the plus symbol when the value to be printed is negative.) The plus symbol can be used to indicate either a leading or a trailing sign, as in the following example:

00010 PRINT USING 20: -100,100,-100,100
00020 FORM 2*PIC(++++++),2*PIC(ZZZZZ+)

Output from the above example would appear as follows:

-100 +100 100- 100+

^

The carat (^) symbol is used to input and output data in exponential format. The carat must occupy the three, four or five rightmost positions in the PIC specification. The output positions will be the mantissa value, the letter E, the exponent sign (+ or -) and the exponent value. Values are rounded before printing. The following examples show the output when the number 1.2345E+20 is printed using the following PIC specifications:

Specifications	Output
PIC (# # # # # # # # ^ ^ ^ ^)	1234500E-14
PIC (# #. # # #^ ^ ^ ^ )	12.345E+19
PIC (# # . # # ^ ^ ^ ^ ^)	12.35E+019
PIC (. # # # # # # ^ ^ ^ ^ )	.12345E+21
PIC (ZZZ.# # ^ ^ ^ ^)	123.45E+18
PIC (# # .^ ^ ^ ^ ^)	2. E+019

Parentheses - ( )

PIC((ZZZ,ZZZ.##)) now supports parentheses as digit identifiers (left side of the number only) and insertion characters, with the rule that parentheses will be output only if the number is negative. The left parenthesis that is closest to the number but not replaced with a digit will be output when the number is negative.

00100 PRINT USING "FORM C 4,PIC((((ZZ,ZZZ.##))":"XXXx",-200

output

XXXx   (  200.00)

00100 PRINT USING "FORM C 4,PIC((((ZZ,ZZZ.##))":"XXXx",-200000

output

XXXx (200,000.00)

Insertion Characters

Insertion characters are output exactly where they appear in the PIC specification. The five special insertion characters are: B, D, CR, DR and DB. Any keyboard character other than the digit identifiers listed above is treated as an insertion character. The following example shows two typical uses of insertion characters. The first PIC specification in line 20 prints slashes between the month, day and year of a date. The second prints a colon between the hours and minutes of a time, and it prints the letters "AM" after the time.

00010 PRINT USING 20: 102088,1130
00020 FORM PIC(ZZ/ZZ/ZZ),PIC(BB##:##AM)

The above example outputs:

10/20/88 11:30AM

B Insertion Character

B is a special insertion character: it is always replaced with a blank when formatted. It is used only for System/23 compatibility (a space may be used to accomplish the same result). In the following example, B occupies the second position in the PIC specification.

00010 PRINT USING 20: 100
00020 FORM PIC(ZBZZ)

Output from the above example would look as follows:

1 00

D Insertion Character

D is a special insertion character: it is always replaced with a dash when formatted. This feature is useful for formatting social security numbers and phone numbers, as in the following example

00010 PRINT USING 20: 123456789
00020 FORM PIC(###D##D####)

Output from this example would appear as follows:

123-45-6789

CR, DR and DB

CR, DR and DB are special insertion characters: they print only if the sign of the number is negative.
The following three examples show each of these insertion characters in use:

00010 PRINT USING 20: -100,100
00020 FORM 2*PIC(ZZZZCR)

Output

100CR 100

00010 PRINT USING 20: -100,100
00020 FORM 2*PIC(ZZZZDR)

Output

100DR 100

00010 PRINT USING 20: -100,100
00020 FORM 2*PIC(ZZZZDB)

Output

100DB 100

Conversion errors on G, N, and PIC formats can now be avoided on output to display files when the CONV=parameter is used in the OPEN DISPLAY statement. Also when CONV=is used, PIC processing will first try removing the commas from the output if doing so will prevent an overflow condition.

Other

See the OPEN DISPLAY statement for more information.

See also FMT, a similar method for formatting fields.

When PIC is used with non-numeric data it is processed very similar to the character string specifications C, V and G. Output is not formatted with insertion characters, but during keyboard entry insertion character positions are skipped.

Row

As a parameter in syntax:

"Row" is an integer value that indicates a row number from 1 to the total number of rows in the screen or window

"Rows" (not to be confused with "row") is an integer constant which indicates the maximum size for the first dimension of an array.

In Grids and Lists, ROW is a READ type that reads all cells in the specified rows.

FINE GRAIN FIELD POSITIONING

As of 4.30, ROW/COL and ROWS/COLS in FIELDS operations may be expressed as decimal fractions.

String Array

"String-array" indicates that a string array name should be specified. For rules regarding these names, see "string variable".

String Constant

A "string constant" is a series of characters enclosed in quotation marks. Before version 4.2, each constant was limited to 250 characters. Version 4.3 and following allow up to 99,999,999 characters.

Quotation marks are used as delimiters in string constants. They signal the beginning and end of a string. You may use either single or double quotation marks. If the enclosed string contains one kind of quotation mark, however, you must either use the other kind as a delimiter or express the inner quotation mark as a pair. Examples of string constants are:

"Montana"
'Montana'
'The "Big Sky" Country'
"The ""Treasure"" State"

Note that in a "LIST" command single quotes represent case insensitive searching while double quotes represent case sensitive matching.

Quote Processing

Quotation marks suppress the recognition of separators in accordance with the following rules.

Standard BR Quote Processing

When examining str$ left to right, the first character (and the first character after each separator) is checked to see if is either (') or ("). If it is ether of those then it activates quotation processing which suppresses the recognition of separators until quotation processing is deactivated. The first character thus becomes the governing quote type until quotation processing is deactivated.

The string is copied until it ends or until an odd number of successive occurrences of the governing quote type is encountered. During this processing, two adjacent occurrences of the governing quote character denote an embedded occurrence of the quote character. Examples:

"abc,def" ->	abc,def	where the comma is not recognized as a separator and is part of the data.
abc"def ->	abc"def	naturally embedded quotes may occur anywhere within a string after the first character
"abc"def" ->	abcdef"	quotation processing is deactivated by the center quote mark
"abcdef" ->	abcdef	normal data
"abc'def" ->	abc'def	the single quote is treated like any other character while double quotes govern
'abc"def' ->	abc"def	double quotes are treated like any other character while single quotes govern
"abc""def" ->	abc"def	pairs of governing quotes denote a single embedded quote
"abc"""def" ->	abc"def"	the third successive occurence deactivates quote processing

MAT2STR

MAT2STR( MAT zzz$, str$ [, sep$ [, flags$]] )

Where flag$ is in the format:

[ quote-type ] [ :LTRM ] | [ :TRIM ] | [ :RTRM ]

Where quote-type can be Q, QUOTES, ('), or ("), case insensitive. Quote-type denotes that each element should be enclosed in quotation marks. The trim flags denote pre-processing of array elements and the leading colon is only present when quote-type is specified.

If Q or QUOTES is specified the BR automatically determines which quote type to apply as follows:

The element is scanned left to right for either type of quote character. If a quote character is encountered, then only the next character is examined. If two occurrences of the same quote character are encountered then that character is used to enclose the element. However, if a single occurrence of a quote character is encountered then the element is enclosed in the alternate quote type. If no quote character is encountered then double quotes are applied. Examples:

Quote Type is Q or QUOTES

abcdef ->	"abcdef"
abc'def ->	"abc'def"
abc"def ->	'abc"def'
abc""def ->	"abc""def"
'abcdef ->	"'abcdef"

Quote Type is ' (single)

abcdef ->	'abcdef'	...
'abcdef ->	abcdef'	single quotes get doubled when embedded in singles quotes
"abcdef ->	'"abcdef'	leading double quote is treated normally

Double quotes are the same as single

When using MAT2STR on a 2 dimensional array, the first delimiter is used for individual elements and the second delimiter at the end of each row. This principle also applies to three to seven dimensions. Example Given the following two dimensional array zzz$ containing the values-

1	2
3	4

The following statements-

   10 Sep$(1)=","
   20 Sep$(2)=hex$("0D0A") ! CRLF
   30 MAT2STR( MAT zzz$, str$, MAT Sep$ )
   40 PRINT str$

Will produce-

   1,2
   3,4