Syntax
Parts Of A Business Rules Statement
Statements (Immediate Mode/Procedure Files)
A typical Business Rules! statement consists of the following:
- A line number.
- A line label (optional).
- A primary keyword.
- One or more secondary keywords or phrases along with their associated values (sometimes optional).
- One or more "error-cond line-ref" conditions (optional).
- 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 each Statement 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 ! remarks
| 00120 | is a line number. |
| BIG | is a line label. |
| 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. |
| ! remarks | 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 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 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).
Multiple statements
More than one statement can reside on a line number 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.
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. |
Syntax Diagrams and Special Considerations
Diagrams are used throughout this manual 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.
Syntax diagrams provide a road map through a command or statement's syntax. Following the main line of the diagram will eventually bring you to the end of the syntax, although you may wish to take allowable detours to obtain certain features. Syntax diagrams always follow a logical pattern.
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.
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 reside on a line with a line number. See the parts at the end of this section for information about these additional requirements and options.
The "array-name" parameter is a name representing either a numeric or a string array. For rules regarding these names, see Variable.
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
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.
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" 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.
"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.
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.
In the following example, lines 100 and 110 illustrate the concatenation of three strings. Lines 120 and 130 use concatenation and the string functions RTRM$, LTRM$ and RPT$ to print and center X$ on the 80-column screen:
00100 LET LINE$ = A$ & B$ & C$
00110 PRINT RTRM$(CITY$) & ", " & STATE$
00120 LET X$ = RTRM$(LTRM$(X$))
00130 PRINT RPT$(" ",(80-LEN(X$))/2) & X$
The printing and centering in lines 120 and 130 can be performed more efficiently with the CC format specifications as follows:
00140 PRINT USING 150: X$ 00150 FORM CC 80
<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.
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
- The first Drive specification identifies the initial current directory when Business Rules! is started.
- 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.
- The only place that Drive can be specified is in the BRConfig.sys file; it is not valid with the config command.
- 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" 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.
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 about the various error conditions.
"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" represents an insertable syntax that is used to provide field definitions for the full screen processing statements. For additional information and a syntax diagram, 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 that equals 255 or any number 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 File I/O 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.
Form-Spec
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 File I/O for information about individual format specifications.
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
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. See String Expression for more information about string constants and string variables. See Functions for more information about string system functions. See DEF statement discussion for more information about user-defined functions.
In addition to the four elements listed above, 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 Substring and Concatenation for more information.
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.
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.
Others
The "INPUT" keyword identifies that the file is to be opened so that its data may only be used as input for the program.
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".
The "internal form-spec" parameter should be replaced with a format specification from the following group: B, BL, BH, PD, ZD. See File I/O for information about individual format specifications.
The "key-length" parameter should be replaced with a number that identifies the number of characters (or columns) in the key.
"Key start-pos" indicates the record position of the first key character for the index.
"Length" is an integer value that sets the maximum length of all elements in the string variable or array.
A line label is an optional name for a program line that is specified immediately after the line number. See description above, or refer to Line Label (program) or Line Label (procedure).
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.
The "line-ref" parameter indicates that you can specify either a line number or a line label as a parameter.
"Num-array" indicates that a numeric array name should be specified.
Numeric Values
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
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.
"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.
The "num form-spec" parameter should be replaced with a numeric format specification from the following group: G, GZ, N, or NZ. The specifications, which are applicable for a given statement, are identified in the parameters text for that statement. See File I/O chapter for information about individual format specifications.
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.
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=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).
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({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" 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.
"String-array" indicates that a string array name should be specified. For rules regarding these names, see "string variable" in this section.
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( 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 ' ( quote type single ) abcdef -> 'abcdef' 'abcdef -> abcdef' single quotes get doubled when embedded in singles quotes "abcdef -> '"abcdef' leading double quote is treated normally
Quote type double mirrors quote type 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