DEF Release 3.70

Overview of Enhancements:
Three enhancements have been made to the DEF statement and/or to user-defined function processing in general:

1. In support of the Library Facility, DEF now accepts the LIBRARY parameter for specifying a user-defined library function. See the remainder of this DEF discussion for details.
2. The DEF statement's syntax now allows the use of a semi-colon to indicate that all parameters specified to the right of the semi-colon are optional. See the remainder of this DEF discussion for details.
3. When a function is expecting an array or matrix, but a function call passes a scalar (simple variable), the function now treats the passed variable as an array of one element. Alternately, if a DEF parameter is defined as a scalar to be passed by reference (&), and an array is passed, the first element of the array will be used as the scalar.

In the following example, a value of 1 is placed into X, as scalar Y is interpreted as a single element array:

10 X=FNA(Y)
20 DEF FNA(MAT A)
30 FNA=UDIM(A)
40 FNEND

Syntax:

Defaults:

1. User-defined function is not a library function.
2. Maximum string variable length of 18 characters.
3. Pass by value, not by reference.
4. Do not pass any required variables.
5. Do not pass any optional variables.
6. Do not pass any variables.
7. Multi-line function.

Parameters:
The DEF statement's "LIBRARY" keyword allows a user-defined function to be defined as a library function. When this keyword is used, the function may be defined either within the main program or within a separate program. In either case, the function must be named on a LIBRARY statement that is processed before the first call to the function. For complete information about the Business Rules! Library Facility, see the following in this chapter: the Library Facility section; "CLEAR", "LOAD" and "STATUS" in the Commands section, and "LIBRARY" and "OPTION" in the Statements section.

The DEF statement's ";" parameter is now allowed within the definition of passed parameters. It indicates that all variables to theright of the semi-colon (;) are optional. If the program does not pass a parameter to the function which is listed as optional in the function definition, a temporary variable is created with a value of zero or null. Optional parameters may be passed by reference. In that case, arrays not passed default to a dimension of 1 and strings default to a length of 18.

Business Rules! accepts function definitions that pass only optional values (i.e., DEF FN(;A,B)). However, a calling statement cannot pass more variables than are defined for the function, and variable types (numeric or string) must match for passed variables.

Examples:
The user-defined function in the following example might be used to print an employee list that also names the members of the employee's family. It utilizes DEF's ";" parameter to specify that two optional parameters (SPOUSE$ and MAT CHILD$) may be passed. Because this function also uses the LIBRARY keyword, it will be handled according to the rules and requirements for library functions.

01000 DEF FNEMPFAM$(&EMP$;&SPOUSE$,MAT CHILD$)
01100 PRINT "Employee name: ";TAB(20);EMP$
01200 IF SPOUSE$<>"" THEN !:
             PRINT TAB(8);"Spouse: ";TAB(20);SPOUSE$
01300 IF CHILD$(1)<>"" THEN
01400   PRINT TAB(6);"Children: ";TAB(20);CHILD$(1)
01500   FOR X=2 TO UDIM(CHILD$)
01600   PRINT TAB(20);CHILD$(X)
01700   NEXT X
01800 END IF
01900 FNEND

DELETE

Release 3.50

1. The positional parameters FIRST, LAST, PRIOR, NEXT, and SAME can now be used with the DELETE statement, as well as with READ, RESTORE and REWRITE. See the "READ" statement discussion for details.

Release 3.61

2. The DELETE statement may be used to delete any anchor record or subrecord from a linked list. The DELETE statement must be preceded by a successful READ of the record to be deleted.

Business Rules! will automatically update the next and previous record pointers (held in the first eight bytes of each linked record) of the affected records when a linked list record is deleted. If a linked list's anchor record is deleted, the next record in the list will become the anchor record. Also, the value of KREC will be updated to return the value of this new anchor record, no matter where the file pointer is in the list.

DO Release 3.50
Business Rules! now supports the DO/LOOP structure, which can be used to replace GOTO statements for more structured programming. Notably, labels or line numbers are not required to exit the loop.

The DO and LOOP statements must always be used in conjunction with one another to specify the beginning and ending of the loop. The EXIT DO statement may be used to break out of the loop.

The syntax of the DO statement is as follows:

Default:

1. When no WHILE or UNTIL condition is specified, execute the loop until the LOOP statement's conditions or an EXIT DO indicate otherwise.

The WHILE keyword indicates that the loop should be executed only if the specified conditional expression evaluates to true. If the conditional expression evaluates to false, execution will skip to the first line following the LOOP statement.

The UNTIL keyword indicates that the loop should be executed only if the specified conditional expression evaluates to false. If the conditional expression evaluates to true, execution will skip to the first line following the LOOP statement.

The word DO on the DO statement is optional when WHILE or UNTIL is specified. Business Rules! will insert the word DO. CONFIG STYLE INDENT will cause lines between the DO and LOOP statements to be indented.

See also the "LOOP" and "EXIT DO" statements in this section for additional information.

EXIT DO Release 3.50

The EXIT DO statement may be used to break out of a DO/LOOP structure and continue execution with the first line following the LOOP statement.

Syntax:

EXIT DO is useful in loops where there is no condition specified either on the DO or on the LOOP statement. EXIT DO is an executable statement and is an exception to EXIT followed by error-cond line-ref instructions, which are not executable.

For more information about the DO/LOOP structure, see also the "DO" and "LOOP" statements in this section.

FORM Release 3.30

Parentheses may now be used to repeat sections of a FORM statement. The repeat factor may be either a number or a variable. Thus, the following is now valid:

FORM 3*(C 10,C 1,C 4)

If a variable is used for a repeat factor in a FORM statement and the value of the variable is less than 1, zero will be used by default (same as the System/23), to skip the specification. Previously 1 was used.

Note the following code fragment:

10 A=0
20 FORM A*C 5,C 10

The above will now be the same as FORM C 10. Previously it was the same as FORM C 5,C 10.

The GF (generic, floating point) format specification has been added for use by the FORM statement and by INPUT/PRINT FIELDS.  See "GF" in the Format Specifications section for more information.

GOTO Release 3.53

The GOTO statement may no longer be executed from the command line. Error 1011 (Illegal immediate statement) will occur if such usage is attempted.

GOSUB Release 3.53

The GOSUB statement may no longer be executed from the command line. Error 1011 (Illegal immediate statement) will occur if such usage is attempted.

Release 3.30

1. Control characters are no longer allowed as valid input for INPUT statements. See "Control characters" in the Keys section for more information.

Release 3.50

2. The WAIT= parameter and TIMEOUT error trap may now be used with INPUT/RINPUT statements to force releasing of records. This feature is useful for multi-user situations.

WAIT= specifies the number of seconds the system should wait for operator input before responding with a TIMEOUT error condition. Note that WAIT=0 instructs the system to wait for zero seconds, not to ignore the WAIT instruction. Also, -1 is a special WAIT value that instructs the system to wait forever, if necessary. Every time the operator presses any key, the clock is reset for WAIT seconds.

INPUT WAIT=10:X$ TIMEOUT 100
RINPUT WAIT=10:X$ TIMEOUT 100
LINPUT WAIT=10:X$ TIMEOUT 100
INPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
INPUT #11,FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
RINPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
INPUT SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100
RINPUT #11,SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100

The TIMEOUT error condition traps time-out errors ( error code 4145) and specifies the line number of an appropriate error-handling routine.

100 RELEASE #ITEM:
110 PRINT "OVER TIME LIMIT"
120 PRINT "Your hold on inventory items has expired, re-enter order."

Before releasing the record, you may want to go to a routine that warns with a message and a few beeps that the hold on records is about to be released, then gives the operator an opportunity to continue data entry. See the "KSTAT$" function in the manual for information on how to use the WAIT parameter with that function.

INPUT FIELDS

Release 3.30

1. MAT grouping is now allowed in all full screen processing statements. This feature allows you to indicate that input or output should alternate between all MAT variables which are specified within parentheses in the I/O list.

In the following code fragment, the A$ variable identifies the positions on the screen from which input values should be drawn. As usual, Business Rules! will assign the first input value to the first element of B$. However, because the B$ and C matrices are specified within parentheses, it will then assign the second input value to the first element of C. The third value will go to B$, the fourth to C, and so on until both matrices are fully assigned. The last input value will go to X$.

00020 INPUT FIELDS A$: (MAT B$,MAT C),X$

Without MAT grouping, the above line must be coded as follows in order to achieve the same results (this example assumes that B$ and C have each been dimensioned for five elements):

00020 INPUT FIELDS A$: B$(1),C(1),
                                              B$(2),C(2),
                                              B$(3),C(3),
                                              B$(4),C(4),
                                              B$(5),C(5),X$

MAT grouping is a lot easier to code, it executes faster, and most importantly it handles much larger arrays than are possible without using MAT grouping, as the resulting compiled line takes up less space in memory. The number of matrices that can be grouped together is 62, which in practical terms is no limit. All matrices in a group must have the same number of elements per matrix, or an error 0106 will result. Only MAT variables may be used in such groupings.

See error 0106 in ERROR CODES section of the manual for additional information.

Release 3.50

2. The WAIT= parameter and TIMEOUT error trap may now be used with INPUT/RINPUT statements to force releasing of records. This feature is useful for multi-user situations. WAIT= specifies the number of seconds the system should wait for operator input before responding with a TIMEOUT error condition.

Note that WAIT=0 instructs the system to wait for zero seconds, not to ignore the WAIT instruction. Also, -1 is a special WAIT value that instructs the system to wait forever, if necessary. Every time the operator presses any key, the clock is reset for WAIT seconds.

INPUT WAIT=10:X$ TIMEOUT 100
RINPUT WAIT=10:X$ TIMEOUT 100
LINPUT WAIT=10:X$ TIMEOUT 100
INPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
INPUT #11,FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
RINPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
INPUT SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100
RINPUT #11,SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100

The TIMEOUT error condition traps time-out errors ( error code 4145) and specifies the line number of an appropriate error-handling routine.

100 RELEASE #ITEM:
110 PRINT "OVER TIME LIMIT"
120 PRINT "Your hold on inventory items has expired, re-enter order."

Before releasing the record, you may want to go to a routine that warns with a message and a few beeps that the hold on records is about to be released, then gives the operator an opportunity to continue data entry. See the "KSTAT$" function in the manual for information on how to use the WAIT parameter with that function.

3. The ATTR parameter in FIELDS and SELECT statements now accepts MAT variables. This feature allows for a different "current" attribute for each input field. Thus if using INPUT SELECT to select many items from a list, the non-current and current attributes may be different for both selected and un-selected items. Note the following sample syntax:

INPUT FIELDS MAT F$, ATTR MAT FF$:MAT DATA$

MAT FF$ is compiled for attributes ONLY, and stops at the end of the array or the first error. If there are not enough attributes for each entry field, the first one will be used. For an example of this feature in action, enter and execute the following sample program:

00100 ! matattr ! example of ATTR MAT attrs specification
00110 PRINT NEWPAGE
00120 PRINT FIELDS "1,2,c 30,/RGBH:R": "[F6]-End selections"
00130 DIM ATTRS$(15),SPEC$(15),DATA$(15)*8
00140 FOR I=1 TO UDIM(ATTRS$) ! set up mats
00150   LET ATTRS$(I)="U/RGB:R"
00160   LET SPEC$(I)=STR$(I+3)&",10,c 8,N/RGB"
00170   READ DATA$(I) : LET SEL$=SEL$&" "
00180 NEXT I
00190 DATA One,Two,Three,Four,Five,Six,Seven,Eight
00192 DATA Nine,Ten,Eleven,Twelve,Thirteen,Fourteen,Fifteen
00200 RINPUT SELECT MAT SPEC$,ATTR MAT ATTRS$: MAT DATA$
00210 IF CMDKEY>0 THEN GOTO 250
00220 LET ATTRS$(CURFLD)="HU/RGBH:R" !:
           LET CURFLD(CURFLD) !:
           LET SPEC$(CURFLD)=SREP$(SPEC$(CURFLD),",N/RGB",",UHR/HRGB")  ! change attributes of selections
00230 LET SEL$(CURFLD:CURFLD)="x" ! could reverse logic of prev.line to unselect
00240 GOTO 200
00250 !
00260 FOR I=1 TO LEN(SEL$)
00270   IF SEL$(I:I)<>" " THEN PRINT DATA$(I);" ";
00280 NEXT I

4. Using an alpha character for field length in INPUT FIELDS or PRINT FIELDS will now produce an error. Previously the character as well as the attributes following it were beingignored. (This may affect your programs). Extraneous characters in attribute specifications will still be ignored.

Release 3.53

5. The FMT specification is now supported for validating and formatting of entered data. See "FMT" in the Format Specification section for complete information.

INPUT SELECT

Release 3.30

1. The cursor's field movement will respond to the arrow keys without regard to the order of the options. The down arrow will move to the field below the cursor's current position, the up arrow moves the cursor to the field above its current position, the left arrow searches to the left of the current field and continues up the screen and then from the end of the screen until it finds another field or itself. The right arrow works the same way, except right and down the screen. If there is no field in the same column as the cursor, the up or down arrow will stay at the current field.

2. The WAIT= parameter and TIMEOUT error trap may now be used with INPUT/RINPUT statements to force releasing of records. This feature is useful for multi-user situations. WAIT= specifies the number of seconds the system should wait for operator input before responding with a TIMEOUT error condition. Note that WAIT=0 instructs the system to wait for zero seconds, not to ignore the WAIT instruction. Also, -1 is a special WAIT value that instructs the system to wait forever, if necessary. Every time the operator presses any key, the clock is reset for WAIT seconds.

The TIMEOUT error condition traps time-out errors ( error code 4145) and specifies the line number of an appropriate error- handling routine.

100 RELEASE #ITEM:
110 PRINT "OVER TIME LIMIT"
120 PRINT "Your hold on inventory items has expired, re-enter order."

Before releasing the record, you may want to go to a routine that warns with a message and a few beeps that the hold on records is about to be released, then gives the operator an opportunity to continue data entry. See the "KSTAT$" function in the manual for information on how to use the WAIT parameter with that function.

3. The ATTR parameter in FIELDS and SELECT statements now accepts MAT variables. This feature allows for a different "current" attribute for each input field. Thus if using INPUT SELECT to select many items from a list, the non-current and current attributes may be different for both selected and un-selected items. Note the following sample syntax:

INPUT FIELDS MAT F$, ATTR MAT FF$:MAT DATA$

MAT FF$ is compiled for attributes ONLY, and stops at the end of the array or the first error. If there are not enough attributes for each entry field, the first one will be used. For an example of this feature in action, enter and execute the following sample program:

00100 ! matattr ! example of ATTR MAT attrs specification
00110 PRINT NEWPAGE
00120 PRINT FIELDS "1,2,c 30,/RGBH:R": "[F6]-End selections"
00130 DIM ATTRS$(15),SPEC$(15),DATA$(15)*8
00140 FOR I=1 TO UDIM(ATTRS$) ! set up mats
00150   LET ATTRS$(I)="U/RGB:R"
00160   LET SPEC$(I)=STR$(I+3)&",10,c 8,N/RGB"
00170   READ DATA$(I) : LET SEL$=SEL$&" "
00180 NEXT I
00190 DATA One,Two,Three,Four,Five,Six,Seven,Eight
00195 DATA Nine,Ten,Eleven,Twelve,Thirteen,Fourteen,Fifteen
00200 RINPUT SELECT MAT SPEC$,ATTR MAT ATTRS$: MAT DATA$
00210 IF CMDKEY>0 THEN GOTO 250
00220 LET ATTRS$(CURFLD)="HU/RGBH:R" !:
           LET CURFLD(CURFLD) !:
           LET SPEC$(CURFLD)=SREP$(SPEC$(CURFLD),",N/RGB",",UHR/HRGB") ! changeattributes of selections
00230 LET SEL$(CURFLD:CURFLD)="x" ! could reverse logic of prev.line to unselect
00240 GOTO 200
00250 !
00260 FOR I=1 TO LEN(SEL$)
00270   IF SEL$(I:I)<>" " THEN PRINT DATA$(I);" ";
00280 NEXT I

4. Using an alpha character for field length in INPUT FIELDS or PRINT FIELDS will now produce an error. Previously the character as well as the attributes following it were being ignored. (This may affect your programs). Extraneous characters in attribute specifications will still be ignored.
   
5. The space bar will now move the cursor from option to option.
   
6. INPUT SELECT and RINPUT SELECT will now hide the cursor if ATTR (floating attribute) is specified.

LET Release 3.50

Four numeric assignment operators (+=, -=, *= and /=) are now supported for the LET statement. These operators can be used when adding, subtracting, multiplying, or dividing a variable and assigning the result to the same variable. Thus, a statement previously coded as:

LET NUM_DAYS=NUM_DAYS+6

can now be coded as:

LET NUM_DAYS+= 6

Besides offering substantial savings in code size and execution time, this feature helps prevent the typing errors that can occur with the use of longer variable names. See your Supplemental Programs diskette or your initial Business Rules! 3.50 system for a copy of the program PLUSEQ.WB if you wish to automatically change existing programs to take advantage of this feature.

LIBRARY Release 3.70

Overview:
The LIBRARY statement is an executable statement that can accomplish one or more of the following:

1. Directly link one or more library function names to a named library.
2. Indicate that the named library should be loaded into memory only as needed to execute each function call, then immediately removed from memory.
3. Instruct Business Rules! to establish linkage according to pre-set search guidelines between each named function and an unnamed library that is currently either resident or present in memory.
4. Immediately load the specified library as a present library.
5. Clear the global variables of a library that has been loaded as resident after each function call to that library.

For an overview of information about the Business Rules! Library Facility, including definitions of such terms as linkage, resident, present and as-needed, see the Library Facility section of this chapter.

Syntax:

Defaults:

1. Search the main program, then currently loaded libraries (both resident and present) in last loaded/first searched order for each function.
2. Immediately load the specified library as a present library.

Parameters:
The meaning of the "RELEASE" parameter varies according to whether or not the following "file-ref" represents a library that is loaded resident. If the library is loaded resident, RELEASE indicates that its global variables are to be cleared after each function call to the library. If the library is not loaded resident, RELEASE indicates that the library is to be loaded and unloaded as needed to execute each function call. (In this event, global variables are also automatically cleared after each function call to the library.) The RELEASE parameter has been implemented in this way to allow case-by-case decisions about whether to load a library as resident or as-needed. Regardless of which method is used, the operation of the code will be identical.

If the RELEASE parameter is not specified and the specified library is not already loaded as resident, it will be treated as a present library. This means that once it is loaded, the library will remain active in memory until the main program ends or until all linkages to and from this library have been reassigned with subsequent LIBRARY statements. (When 0 linkages are active for a present library, Business Rules! automatically removes it from memory.)

"File-ref" represents the file name and path (if necessary) of a library program. It must be specified within parentheses and followed by a space and then a colon (:). A null string is processed as though the file-ref parameter were omitted. If the file-ref is followed by a list of one or more function names (first and second paths of diagram), linkage will be established between the specified file and the specified functions.

If no file-ref is specified (default path of diagram), the statement is said to be an unnamed LIBRARY statement. When an unnamed LIBRARY statement is used, Business Rules! attempts to establish linkage by searching first the main program and then each loaded library in last loaded/first searched order. It then establishes linkage between each named function and the first searched program that contains a DEF LIBRARY statement for that function. Note that a colon (:) is required, and there must be a space between the colon and the LIBRARY keyword.

"FNname" represents the name of each library function for which linkage is to be established. Multiple function names must be separated by commas (,). If no FNname parameter is included in the LIBRARY statement (bottom path of diagram), the specified file is immediately loaded into memory as a present library, but no linkages are established.

Use of the "IOERR" parameter instructs the system to execute the specified error-processing routine whenever an I/O error condition is trapped. "IOERR" must be followed by the "line-ref" parameter, which identifies the program line where the error-processing routine starts.

Examples:
The following "named" LIBRARY statement establishes linkage between the LINKS library and the library functions FNLINK, FNATTACH and FNSQUEEZE. If LINKS is in memory at the time that this statement is executed, Business Rules! will check to make sure that it contains the named functions.

01000 LIBRARY "LINKS" : FNLINK,FNATTACH,FNSQUEEZE

This LIBRARY statement indicates that MAINT should be loaded into memory as an "as-needed" library, meaning that it will be loaded as needed to execute each call to FNMAINT, then immediately removed from memory:

01100 LIBRARY RELEASE, "MAINT" : FNMAINT

The following "unnamed" LIBRARY statement causes Business Rules! to search first the main program, then each currently loaded present and resident library (in last loaded, first searched order) for the functions FNLOOKLONG and FNKEEPGOING. It establishes linkage between each named function and the currently loaded library in which the function was first found:

01200 LIBRARY : FNLOOKLONG,FNKEEPGOING

The differences between Fragments A and B in the code samples below are as follows:

1. Fragment A loads the DELI library at line 00110; Fragment B loads it at line 00130, and
   
2. Fragment A confirms that FNSALAMI exists in DELI at line 00120; Fragment B doesn't do this until the function is called on line 00130.

00100 ! FRAGMENT A
00110 LIBRARY "DELI" :
00120 LIBRARY "DELI" : FNSALAMI
00130 LET FNSALAMI
00100 ! FRAGMENT B
00120 LIBRARY "DELI" : FNSALAMI
00130 LET FNSALAMI

The differences between Fragments C and D in the code samples below are as follows:

1. Fragment C loads MAINT as a resident library at line 00210; Fragment D loads it as an as-needed library at line 00230, and
   
2. When the function at line 00230 is finished executing, Fragment C keeps the MAINT library in resident memory but clears the global variables; Fragment D clears MAINT from memory, causing its global variables to be cleared as well.

00200 ! FRAGMENT C
00210 EXECUTE "LOAD MAINT,RESIDENT"
00220 LIBRARY RELEASE,"MAINT" : FNMAINT
00230 LET FNMAINT
00200 ! FRAGMENT D
00220 LIBRARY RELEASE,"MAINT" : FNMAINT
00230 LET FNMAINT

Technical Considerations:

1. If a LIBRARY statement has already established linkage between a specific function and a library, subsequent LIBRARY statements may be used to reassign the linkage.
   
2. When 0 linkages are active for a present library, Business Rules! automatically removes that library from memory. When 0 linkages are active for a resident library, the library may be removed from memory with the CLEAR command. Therefore, if you desire to activate a replacement library during the execution of a program, your subsequently executed LIBRARY statement should include all functions named in the original LIBRARY statement. This will permit the original library to be removed from memory before the new library is loaded.

In the following example, the LIBRARY statement at line 01000 establishes linkage between the library LIB1 and the functions FNVERSION and FNRELEASE. The LIBRARY statement at line 09000 then reassigns linkage for FNVERSION and FNRELEASE to LIB2. If LIB1 is loaded as a present library (and no other linkages are active for it), Business Rules! automatically releases it after line 09000 is executed. If LIB1 is loaded as a resident library (and no other linkages are active for it), a CLEAR command may be successfully used to release it from memory after line 09000 is executed:

01000 LIBRARY "LIB1" : FNVERSION,FNRELEASE
09000 LIBRARY "LIB2" : FNVERSION,FNRELEASE

3. There is only one situation where a LIBRARY statement immediately loads a library: when LIBRARY is specified with a file-ref only (no RELEASE or FNname parameters are specified). In all other situations, the library will either already be loaded when the LIBRARY statement is executed, or Business Rules! will load the library at the time of the first function call to the library.
   
4. When the LIBRARY statement identifies a library that has not yet been loaded, Business Rules! does no checking at the time the LIBRARY statement is processed to assure that the listed functions exist within the library, or even that the specified library exists. This check instead occurs when the function is called.
   
5. When the LIBRARY statement identifies a library that has already been loaded, Business Rules! checks to make sure that the listed functions exist within the library.
   
6. Each program that calls library functions must name the library functions it calls on a LIBRARY statement. This applies even when the program doing the calling is a library program and even when the library program is calling one of its own library functions. For example, consider the following two code fragments. The first fragment illustrates a section of the main program which establishes linkage between the library LIB1 and the functions FNFORTUNE and FNAGE. The second fragment shows the definition of FNFORTUNE in LIB1. Because FNFORTUNE calls FNAGE, it names FNAGE on a LIBRARY statement before calling it.

00900 ! MAIN FRAGMENT
00910 LIBRARY "LIB1" : FNFORTUNE, FNAGE
07000 ! LIB1 FRAGMENT
07010 DEF LIBRARY FNFORTUNE
07020 LIBRARY "LIB1" : FNAGE
07030 LET FNAGE

07100 FNEND

7. A named LIBRARY statement is one that specifically identifies the library to which the named functions are to be linked. This is the most efficient and fool-proof method for assuring that the library function you wish to use gets executed.
   
8. An unnamed LIBRARY statement is one that names the desired library functions and leaves it to Business Rules! to determine which of the currently loaded libraries it should be linked to. This method of linkage is useful when your development methodology involves using multiple versions of the same function to control program options and features.
   
9. For additional useful information about the Business Rules! Library Facility, see the following in this chapter: the Library Facility section; "CLEAR", "LOAD" and "STATUS" in the Commands section, and "DEF" and "OPTION" in the Statements section.

1. The WAIT= parameter and TIMEOUT error trap may now be used with INPUT/RINPUT statements to force releasing of records. This feature is useful for multi-user situations.

WAIT= specifies the number of seconds the system should wait for operator input before responding with a TIMEOUT error condition. Note that WAIT=0 instructs the system to wait for zero seconds, not to ignore the WAIT instruction. Also, -1 is a special WAIT value that instructs the system to wait forever, if necessary. Every time the operator presses any key, the clock is reset for WAIT seconds.

INPUT WAIT=10:X$ TIMEOUT 100
RINPUT WAIT=10:X$ TIMEOUT 100
LINPUT WAIT=10:X$ TIMEOUT 100
INPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
INPUT #11,FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
RINPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
INPUT SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100
RINPUT #11,SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100

The TIMEOUT error condition traps time-out errors ( error code 4145) and specifies the line number of an appropriate error-handling routine.

100 RELEASE #ITEM:
110 PRINT "OVER TIME LIMIT"
120 PRINT "Your hold on inventory items has expired, re-enter order."

Before releasing the record, you may want to go to a routine that warns with a message and a few beeps that the hold on records is about to be released, then gives the operator an opportunity to continue data entry. See the "KSTAT$" function in the manual for information on how to use the WAIT parameter with that function.

2. You can input a string array using LINPUT when using a file for input. Each line in the file is input for each element of the array. The string must be long enough to input each line in the file to avoid string overflow. If there are not enough lines in the file to fill the array, an EOF error is given after whatever lines are available are input.

LOOP Release 3.50

Business Rules! now supports the DO/LOOP structure, which can be used to replace GOTO statements for more structured programming. Notably, labels or line numbers are not required to exit the loop.

The DO and LOOP statements must always be used in conjunction with one another to specify the beginning and ending of the loop. The EXIT DO statement may be used to break out of the loop.

The syntax of the LOOP statement is as follows:

Default:

1. When no WHILE or UNTIL condition is specified, continue executing the loop until the DO statement's conditions or an EXIT DO indicate otherwise.

The WHILE keyword indicates that execution should return to the previous DO statement only if the specified conditional expression evaluates to true. If the conditional expression evaluates to false, execution will skip to the first line following the LOOP statement.

The UNTIL keyword indicates that execution should return to the previous DO statement only if the specified conditional expression evaluates to false. If the conditional expression evaluates to true, execution will skip to the first line following the LOOP statement.

The LOOP statement must be the last statement in a line, and the LOOP keyword is always required. CONFIG STYLE INDENT will cause lines between the DO and LOOP statements to be indented.

See the "DO" and "EXIT DO" statements in this section for additional information about the DO/LOOP structure.

MAT Release 3.50

MAT subarray operator Arrays may now be subscripted with a starting and ending element number to process a portion of an array. This works much the same as Business Rules!'s substring feature, except it works with elements instead of characters.

MAT A(6:10)=B ! copies B(1)..B(5) into A(6)..A(10);
MAT B=A(6:10) ! B dimensioned for 5 elements.
MAT B(1:5)=A(6:10) ! Copy part of 1 array to part of another
READ MAT A(1:5) ! only read elements 1-5
PRINT FIELDS SF$:MAT A$(F:F+9) ! 10 elements starting at "F" are displayed

Multi-dimensional matrixes are not supported for subarray processing.

Invalid:  MAT A(2,2:5,5)

OPEN communications

Release 3.30

1. DOS versions of Business Rules! now use the value of the WAIT parameter as the maximum number of seconds to wait for a device to accept each output character. Once this maximum is reached, the system will generate an I/O error. Previously there was no timeout for DOS communications output.
   
2. When a file is opened for both SHR and INPUT, Business Rules! will no longer change the time and date of the file. As a result of this change, when a file is to be opened both for OUTIN and for INPUT, the OPEN for OUTIN must be executed first. Otherwise an error 0608 will result. This will affect current programs.

OPEN display

Release 3.30

1. The RETRY=int parameter is now supported in the syntax of the OPEN display statement. When at least one character has been output and the output device fails, int attempts are made again for the output. The default value for int is 5. This parameter can be adjusted for slow devices.
   
2. When a file is opened for both SHR and INPUT, Business Rules! will no longer change the time and date of the file. As a result of this change, when a file is to be opened both for OUTIN and for INPUT, the OPEN for OUTIN must be executed first. Otherwise an error 0608 will result. This will affect current programs.

Release 3.50

3. The OPEN display statement now supports a PRINTER= parameter. This parameter is used to specify the printer translation table (located in the wbconfig.sys file) that should be used. If the specified printer translation table is not found in the wbconfig.sys file, error 0609 will result. When no name is specified after the PRINTER= parameter, the default printer translation table will be used. For example:

OPEN #1:"NAME=filename,PRINTER=LASER",DISPLAY,OUTPUT
OPEN #1:"NAME=filename,PRINTER=",DISPLAY,OUTPUT ! use default

The string specified by this parameter overrides the NAME= string that is used in a PRINTER translation. If no PRINTER= clause is specified in the open string, the PRINTER translation that will be used is the NAME= string.

4. The NOCLOSE parameter in any OPEN statement will leave that file open when a program ends or chains to another program. The only way this file is closed is by explicitly closing the file, CLEAR ALL, or by exiting from Business Rules!.

OPEN #1:"NAME=TEST,NOCLOSE",INTERNAL,RELATIVE,INPUT

Release 3.53

5. On DOS and IBM Network versions, the CONFIG SPOOLCMD must now be specified, or opens to PRN: will return error 6298 (printer error) if the printer is not ready.
   
6. The OPEN display statement now allows the CONV= parameter, which can be used to avoid conversion errors on N, G and PIC output to display files. CONV= specifies the character to fill a numeric field with in situations where a conversion would normally occur. For example, a report could print asterisks (********) in a numeric field instead of stopping with an conversion error. The fill character starts from the second position in the field and continues to the last digit specifier. (If the field is only one character in length, the fill character is used for that position.) Also, when CONV= is used, PIC processing will first try removing the commas from

PRINT USING "FORM PIC(ZZZZZ)":12345,123456

output:
12345 ****

PRINT USING "FORM PIC(ZZ,ZZZB)":12345,123456

output:
12,345 123456

Release 3.70

7. The WAIT specification in the OPEN statement for all physical files will now also be used as the number of seconds to wait before re-attempting to open a file that another workstation has locked. Previously it affected the wait time on locked records only. Error code 4146 will be returned if the OPEN fails due to file locking.

1. When a file is opened for both SHR and INPUT, Business Rules! will no longer change the time and date of the file. As a result of this change, when a file is to be opened both for OUTIN and for INPUT, the OPEN for OUTIN must be executed first. Otherwise an error 0608 will result. This will affect current programs.

2. The NOCLOSE parameter in any OPEN statement will leave that file open when a program ends or chains to another program. The only way this file is closed is by explicitly closing the file, CLEAR ALL, or by exiting from Business Rules!.

3. The WAIT specification in the OPEN statement for all physical files will now also be used as the number of seconds to wait before re-attempting to open a file that another workstation has locked. Previously it affected the wait time on locked records only. Error code 4146 will be returned if the OPEN fails due to file locking.

OPEN internal

Release 3.30

1. When a file is opened for both SHR and INPUT, Business Rules! will no longer change the time and date of the file. As a result of this change, when a file is to be opened both for OUTIN and for INPUT, the OPEN for OUTIN must be executed first. Otherwise an error 0608 will result. This will affect current programs.

Release 3.50

2. The NOCLOSE parameter in any OPEN statement will leave that file open when a program ends or chains to another program. The only way this file is closed is by explicitly closing the file, CLEAR ALL, or by exiting from Business Rules!.

OPEN #1:"NAME=TEST,NOCLOSE",INTERNAL,RELATIVE,INPUT

Release 3.53

3. The OPEN internal statement now allows for the VERSION= parameter. If a VERSION= number (0 to 32000) is specified and a file is being newly created, that version number will be saved in the header portion of the data file. Key files are not affected. If the file exists, the version number specified will be compared with the version number in the file and an error 4125 will result if they are not the same. The default version number is 0, which also causes no checking to be performed. If the version number of an opened file is non-zero, it can be displayed by the STATUS FILES command. For more information and examples, see "VERSION" in the Functions section and "STATUS FILES" in the Commands section.

Release 3.61

4. OPEN internal now assumes a B-tree indexed file unless OPTION 5 is used in the wbconfig.sys file to set the universal default to ISAM or the ISAM parameter is used within the syntax of the OPEN statement to override the B-tree default on an individual basis. (If OPTION 5 is specified in wbconfig.sys, the OPEN statement's BTREE parameter can be used to override the ISAM default on an individual basis.)

OPEN internal now allows the BTREE or ISAM parameters, as follows:

OPEN "NAME=filename,kfname=indexname,kps=...,ISAM"...
OPEN "NAME=filename,kfname=indexname,kps=...,BTREE".. .

5. OPEN internal now accepts the LINKED keyword, which specifies that the file to be opened is linked. OPEN internal's existing KPS= and KLN= parameters may be optionally used with LINKED files to identify a key field. This key field can then be used by the READ statement's LINK= parameter to verify file integrity for each read. Error 0606 (Invalid element in OPEN) will result if the program attempts to use the first eight bytes of the record as the key field.

The following example creates the linked file LINKFILE, and identifies record positions 9 through 12 as the key field for verification:

10 OPEN#1:"NAME=LINKFILE,NEW,RECL=63,LINKED,
                       KPS=9/23,KLN=4/6",INTERNAL,OUTIN,REL

Release 3.70

6. The WAIT specification in the OPEN statement for all physical files will now also be used as the number of seconds to wait before re-attempting to open a file that another workstation has locked. Previously it affected the wait time on locked records only. Error code 4146 will be returned if the OPEN fails due to file locking.

OPEN window

Release 3.30

1. When a file is opened for both SHR and INPUT, Business Rules! will no longer change the time and date of the file. As a result of this change, when a file is to be opened both for OUTIN and for INPUT, the OPEN for OUTIN must be executed first. Otherwise an error 0608 will result. This will affect current programs.

Release 3.50

2. The OPEN window statement now allows for flexibility in the specification of window coordinates. Previously all four coordinates of the window had to be specified in terms of two exact row positions and two exact column positions. With release 3.50, only one exact row position and one exact column position must be specified. Business Rules! will automatically calculate the other row and/or column position according to the values of the ROWS= and COLS= parameters, which indicate the desired length or width of the window.

The ROWS= parameter may be used in place of either the SROW= or the EROW= parameter, but not both. Likewise, the  COLS= parameter may be used in place of either the SCOL= or the ECOL= parameter, but not both.

The following examples show some of the possibilities that are available using this syntax option. Each statement opens a 10 row by 10 column window in the upper left corner of the screen. (Note: ROWS= and COLS= parameters are shown in lowercase for emphasis; case makes no difference in actual syntax.)

10 OPEN#1:"rows=10,cols=10,EROW=10,ECOL=10",DISPLAY,OUTPUT
20 OPEN #1:"rows=10,SCOL=1,EROW=10,cols=10",DISPLAY,OUTPUT
30 OPEN #1:"rows=10,SCOL=1,EROW=10,ECOL=10",DISPLAY,OUTPUT
40 OPEN #1:"SROW=1,cols=10,rows=10,EROW=10",DISPLAY,OUTPUT
50 OPEN #1:"SROW=1,cols=10,EROW=10,ECOL=10",DISPLAY,OUTPUT
60 OPEN #1:"SROW=1,SCOL=1,rows=10,cols=10",DISPLAY,OUTPUT
70 OPEN #1:"SROW=1,SCOL=1,rows=10,ECOL=10",DISPLAY,OUTPUT
80 OPEN #1:"SROW=1,SCOL=1,EROW=10,cols=10",DISPLAY,OUTPUT

3. The OPEN window statement's BORDER parameter now accepts S (drop-shadow) as an attribute for the border. See "S Attribute" in the Wbconfig.sys Specification section for more information.
   
4. The NOCLOSE parameter in any OPEN statement will leave that file open when a program ends or chains to another program. The only way this file is closed is by explicitly closing the file, CLEAR ALL, or by exiting from Business Rules!.

OPEN #1:"NAME=TEST,NOCLOSE",INTERNAL,RELATIVE,INPUT

1. A user-defined collating sequence may now be accessed when OPTION COLLATE ALTERNATE is specified. See "COLLATE ALTERNATE" in the Wbconfig.sys Specification section for more information.

2. Overview of enhancement:
   The OPTION statement now accepts the RETAIN parameter. The option statement with the RETAIN parameter may be used in a library program to specify that when the library is loaded resident global variables should retain their values irrespective of the status of the main program.

Syntax:
The complete syntax of the OPTION statement is as follows:

Defaults:

1. BASE 1.
2. Use U.S. format for commas and decimals in numeric values.
3. When a library program is loaded resident, do not retain global variables after the main program ends.
4. Use the collating sequence listed in the wbconfig.sys file. If none is listed there, use COLLATE NATIVE.

Parameter:
"RETAIN" specifies that the current library program (which must be loaded resident in order for the OPTION RETAIN statement to have any effect) should retain its global variable values irrespective of main program status. The only way such globals are cleared when this statement is used, is by removing the resident aspect of their library or reloading the library with the LOAD RESIDENT command. OPTION RETAIN takes precedence over any situations that would otherwise clear library globals, such as when the main program ends. Note that an error will occur when a LIBRARY statement with a RELEASE parameter attempts to reference a library program that includes an OPTION RETAIN statement.

PRINT BORDER Release 3.50

The PRINT BORDER statement now accepts S (drop-shadow) as an attribute when the specified window was originally opened with the S attribute. Error 0868 results when use of the S attribute is attempted for a window originally opened without it. See "S Attribute" in the Wbconfig.sys Specification section for more information.

PRINT FIELDS

Release 3.30

1. MAT grouping is now allowed in all full screen processing statements. This feature allows you to indicate that input or output should alternate between all MAT variables which are specified within parentheses in the I/O list.

In the following code fragment, the A$ variable identifies the positions on the screen from which input values should be drawn. As usual, Business Rules! will assign the first input value to the first element of B$. However, because the B$ and C matrices are specified within parentheses, it will then assign the second input value to the first element of C. The third value will go to B$, the fourth to C, and so on until both matrices are fully assigned. The last input value will go to X$.

00020 INPUT FIELDS A$: (MAT B$,MAT C),X$

Without MAT grouping, the above line must be coded as follows in order to achieve the same results (this example assumes that B$ and C have each been dimensioned for five elements):

00020 INPUT FIELDS A$:B$(1),C(1),
                                             B$(2),C(2),
                                             B$(3),C(3),
                                             B$(4),C(4),
                                             B$(5),C(5),X$

MAT grouping is a lot easier to code, it executes faster, and most importantly it handles much larger arrays than are possible without using MAT grouping, as the resulting compiled line takes up less space in memory. The number of matrices that can be grouped together is 62, which in practical terms is no limit. All matrices in a group must have the same number of elements per matrix, or an error 0106 will result. Only MAT variables may be used in such groupings.

See error 0106 in the ERROR CODES section in your manual for additional information.

Release 3.50

2. Using an alpha character for field length in INPUT FIELDS or PRINT FIELDS will now produce an error. Previously the character as well as the attributes following it were being ignored. (This may affect your programs). Extraneous characters in attribute specifications will still be ignored.

Release 3.53

3. The FMT specification is now supported. However, because Business Rules! does no formatting or verifying of data that is output to the screen with FMT, FMT is equivalent to the C format spec on screen output. See "FMT" in the Format Specifications section for complete information.

PRINT with NEWPAGE Release 3.30

When output to a display file with PRINT, the NEWPAGE function no longer sends a carriage return. See "NEWPAGE" in the Functions section for more information.

READ FILE

Release 3.50

1. The positional parameters FIRST, LAST, PRIOR, NEXT, and SAME can now be used with the READ statement, as well as with RESTORE, DELETE and REWRITE. These have been added for System/36 compatibility. 

The parameters may be used with Business Rules! internal files which are opened for either RELATIVE or KEYED access, and they may be used with external files. The files must be opened either for INPUT or for OUTIN.

If positional parameters are used, DELETE and REWRITE need not follow a READ.

In the following sample syntax sentences, "pos-parm" represents the FIRST, LAST, PRIOR, NEXT or SAME keyword:

READ #file-num,USING line-ref,pos-parm: var-name error-cond line-ref
REWRITE #file-num,USING line-ref,pos-parm: var-name error-cond line-ref
DELETE #file-num,pos-parm: error-cond line-ref
RESTORE #file-num,pos-parm: error-cond line-ref

The FIRST keyword resets the file pointer to the first record in the file before execution of the I/O operation. If the file is empty, an EOF error is generated.

The LAST keyword positions the file pointer to the last record in the file before execution of the I/O operation. If the file is empty, an EOF error is generated.

The PRIOR, NEXT and SAME positional parameters operate according to the last record referenced in the file. The last referenced record is the one that has most recently been processed by a RESTORE with a parameter (positional, REC= or KEY=), a WRITE to a relative file, a READ, a REREAD, a REWRITE, or a DELETE.

If PRIOR, NEXT or SAME positioning is attempted when no records have been referenced or after a RESTORE with no parameters has been issued, Business Rules!  will respond as stated below. This status can be tested with the REC function, which will return a zero for the current record when no records have been referenced.

The PRIOR keyword positions the file pointer to the record previous to the last referenced record in the file. However, in a situation where a READ PRIOR, DELETE PRIOR or REWRITE PRIOR follows a RESTORE with a parameter, the file pointer is positioned to the same record that is referenced by the RESTORE. The only exception to this is when S/36-MODE is ON, in the above situation the file pointer will then position to the previous record if one exists or else it will generate an EOF error. If PRIOR is used when no records have been referenced, an EOF error is also generated.

The NEXT keyword positions the file pointer to the record following the last referenced record in the file. If no record has been referenced, the first record in the file is accessed. If the file is empty or the file pointer was already at the last record, an EOF error is generated. If a READ NEXT, DELETE NEXT, or REWRITE NEXT follows a RESTORE with a parameter, the same record is processed.

The SAME keyword positions the file pointer to the last referenced record in the file. If no records have been referenced, error 0715 (Illegal sequence) is generated. Note that the difference between READ SAME and REREAD is that READ SAME actually reads the file again, while REREAD only unpacks the data from the buffer.

The following sample code and output shows an example of positional parameters in use:

00130 OPEN #1: "name=test.dat,recl=15,replace,kfname=test.key,
                             kps=1,kln=3",INTERNAL,OUTIN,KEYED
00140 FORM C 3,N 3
00150 ! write 7 records with letters A through G as keys
00160 FOR I = 1 TO 7 !:
             WRITE #1,USING 140: CHR$(64+I),I !:
           NEXT I
00170 !
00180 PRINT "KEYED:" : GOSUB TESTREAD ! read keyed
00190 CLOSE #1:
00200 OPEN #1: "name=test.dat",INTERNAL,INPUT,RELATIVE
00210 PRINT !:
           PRINT "RELATIVELY:" !:
           GOSUB TESTREAD ! read relative using same logic
00220 END
00230 TESTREAD: !
00240 READ #1,USING 140,FIRST: A$ : PRINT "FIRST ";A$
00250 READ #1,USING 140,SAME: A$ : PRINT "SAME ";A$
00260 READ #1,USING 140,LAST: A$ : PRINT "LAST ";A$
00270 READ #1,USING 140,PRIOR: A$ : PRINT "PRIOR ";A$
00280 READ #1,USING 140,NEXT: A$ : PRINT "NEXT ";A$
00290 PRINT "DESCENDING KEY: "; ! read whole file by descending key
00300 RESTORE #1,LAST: !:
           FOR I=1 TO 7 !:
              READ #1,USING 140,PRIOR: A$ !:
              PRINT A$; !:
           NEXT I !:
           PRINT
00310 RETURN

run
KEYED:
FIRST A
SAME A
LAST G
PRIOR F
NEXT G
DESCENDING KEY: G F E D C B A

RELATIVELY:
FIRST A
SAME A
LAST G
PRIOR F
NEXT G
DESCENDING KEY: G F E D C B A

2. The READ statement's KEYONLY parameter allows you to read both the key and the record number in a keyed file without reading the corresponding record in the master file. This feature was implemented to return the key if the master file record is locked and is being read by key. It can also be used to obtain keys sequentially, without the overhead of reading the master file.

The KEYONLY parameter is valid only for files opened INPUT KEYED or OUTIN KEYED. It may be used with positional parameters to specify the key that is to be read. If no positional parameter is specified, the next key will be read. FORM statements corresponding to the key length and B 4 for the record number should be used. If the record length of the master file is not at least four bytes more than the key length, the record number is not returned.

Syntax:

READ #file-num,USING line-ref,[pos-parm,]KEYONLY: var-name error-cond line-ref

While Business Rules! reads only the key file when the KEYONLY parameter is used, it does move the file pointer in the master file to the position of the record just read.  Note that it is very important to keep the key file updated if this feature is to be used. Otherwise, READ with the KEYONLY parameter could return an incorrect record in a situation where a master file record is deleted or rewritten after a READ with a REC= parameter.

A REREAD, DELETE, or REWRITE following a READ with the KEYONLY parameter will return an error.

Release 3.61
The READ file statement now accepts the LINK=string parameter. It can be used only on LINKED files that have been opened using the KPS= and KLN= parameters. When READ with LINK= is executed, Business Rules! will compare the data in the key area specified by the OPEN statement to the LINK= string. If they do not match, error code 4282 will result.

Error 0718 (Key length conflict) will result if you specify LINK= in a READ statement but the linked file has not been opened using the KPS= and KLN= parameters.

The practical way to access records in a linked list is to position the file pointer to the anchor point of the desired linked list with a RESTORE REC= (the REC= number should be stored in the master file and updated whenever the list is accessed). From this position, the program should perform sequential READs until the desired record is found. Note that any attempt to read beyond the last record in the list will result in an error 4270 (End of file). The same error will occur on any attempt to READ PRIOR from the anchor record of a list.

1. The positional parameters FIRST, LAST, PRIOR, NEXT, and SAME can now be used with the RESTORE statement, as well as with READ, DELETE and REWRITE. See the "READ" statement discussion for details.

2. In linked files, the RESTORE file statement plays two important roles. First, it can be used with the REC= parameter to reposition the file pointer to any specified record number. The number of the anchor record of a desired link list would typically be stored in the associated master record.  If REC= specifies an anchor record KREC is set accordingly. Otherwise KREC is set to zero.
   
   The second role of RESTORE is that it can be used without parameters (or REC=0) to create a new anchor point for a linked  list that you wish to add or insert. The current position of the file pointer makes no difference when RESTORE is used in this manner.

REWRITE Release 3.50

The positional parameters FIRST, LAST, PRIOR, NEXT, and SAME can now be used with the REWRITE statement, as well as with READ, RESTORE and  DELETE. See the "READ" statement discussion for details.

RINPUT Release 3.50

The WAIT= parameter and TIMEOUT error trap may now be used with INPUT/RINPUT statements to force releasing of records. This feature is useful for multi-user situations.

WAIT= specifies the number of seconds the system should wait for operator input before responding with a TIMEOUT error condition. Note that WAIT=0 instructs the system to wait for zero seconds, not to ignore the WAIT instruction. Also, -1 is a special WAIT value that instructs the system to wait forever, if necessary. Every time the operator presses any key, the clock is reset for WAIT seconds.

INPUT WAIT=10:X$ TIMEOUT 100
RINPUT WAIT=10:X$ TIMEOUT 100
LINPUT WAIT=10:X$ TIMEOUT 100
INPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
INPUT #11,FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
RINPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
INPUT SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100
RINPUT #11,SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100

The TIMEOUT error condition traps time-out errors ( error code 4145) and specifies the line number of an appropriate error-handling routine.

100 RELEASE #ITEM:
110 PRINT "OVER TIME LIMIT"
120 PRINT "Your hold on inventory items has expired, re-enter order."

Before releasing the record, you may want to go to a routine that warns with a message and a few beeps that the hold on records is about to be released, then gives the operator an opportunity to continue data entry. See the "KSTAT$" function in the manual for information on how to use the WAIT parameter with that function.

Release 3.30

1. MAT grouping is now allowed in all full screen processing statements. This feature allows you to indicate that input or output should alternate between all MAT variables which are specified within parentheses in the I/O list.

In the following code fragment, the A$ variable identifies the positions on the screen from which input values should be drawn. As usual, Business Rules! will assign the first input value to the first element of B$. However, because the B$ and C matrices are specified within parentheses, it will then assign the second input value to the first element of C. The third value will go to B$, the fourth to C, and so on until both matrices are fully assigned. The last input value will go to X$.

00020 INPUT FIELDS A$: (MAT B$,MAT C),X$

Without MAT grouping, the above line must be coded as follows in order to achieve the same results (this example assumes that B$ and C have each been dimensioned for five elements):

00020 INPUT FIELDS A$: B$(1),C(1),
                                              B$(2),C(2),
                                              B$(3),C(3),
                                              B$(4),C(4),
                                              B$(5),C(5),X$

MAT grouping is a lot easier to code, it executes faster, and most importantly it handles much larger arrays than are possible without using MAT grouping, as the resulting compiled line takes up less space in memory. The number of matrices that can be grouped together is 62, which in practical terms is no limit. All matrices in a group must have the same number of elements per matrix, or an error 0106 will result. Only MAT variables may be used in such groupings.

See error 0106 in the ERROR CODES section of your manual for additional information.

Release 3.50

2. The WAIT= parameter and TIMEOUT error trap may now be used with INPUT/RINPUT statements to force releasing of records. This feature is useful for multi-user situations.

WAIT= specifies the number of seconds the system should wait for operator input before responding with a TIMEOUT error condition. Note that WAIT=0 instructs the system to wait for zero seconds, not to ignore the WAIT instruction. Also, -1 is a special WAIT value that instructs the system to wait forever, if necessary. Every time the operator presses any key, the clock is reset for WAIT seconds.

INPUT WAIT=10:X$ TIMEOUT 100
RINPUT WAIT=10:X$ TIMEOUT 100
LINPUT WAIT=10:X$ TIMEOUT 100
INPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
INPUT #11,FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
RINPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
INPUT SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100
RINPUT #11,SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100

The TIMEOUT error condition traps time-out errors ( error code 4145) and specifies the line number of an appropriate error-handling routine.

100 RELEASE #ITEM:
110 PRINT "OVER TIME LIMIT"
120 PRINT "Your hold on inventory items has expired, re-enter order."

Before releasing the record, you may want to go to a routine that warns with a message and a few beeps that the hold on records is about to be released, then gives the operator an opportunity to continue data entry. See the "KSTAT$" function in the manual for information on how to use the WAIT parameter with that function.

3. The ATTR parameter in FIELDS and SELECT statements now accepts MAT variables. This feature allows for a different "current" attribute for each input field. Thus if using INPUT SELECT to select many items from a list, the non-current and current attributes may be different for both selected and un-selected items. Note the following sample syntax:

INPUT FIELDS MAT F$, ATTR MAT FF$:MAT DATA$

MAT FF$ is compiled for attributes ONLY, and stops at the end of the array or the first error. If there are not enough attributes for each entry field, the first one will be used. For an example of this feature in action, enter and execute the following sample program:

00100 ! matattr ! example of ATTR MAT attrs specification
00110 PRINT NEWPAGE
00120 PRINT FIELDS "1,2,c 30,/RGBH:R": "[F6]-End selections"
00130 DIM ATTRS$(15),SPEC$(15),DATA$(15)*8
00140 FOR I=1 TO UDIM(ATTRS$) ! set up mats
00150 LET ATTRS$(I)="U/RGB:R"
00160 LET SPEC$(I)=STR$(I+3)&",10,c 8,N/RGB"
00170 READ DATA$(I) : LET SEL$=SEL$&" "
00180 NEXT I
00190 DATA One,Two,Three,Four,Five,Six,Seven,Eight,Nine,Ten
00192 DATA Eleven,Twelve,Thirteen,Fourteen,Fifteen
00200 RINPUT SELECT MAT SPEC$,ATTR MAT ATTRS$: MAT DATA$
00210 IF CMDKEY>0 THEN GOTO 250
00220 LET ATTRS$(CURFLD)="HU/RGBH:R" !:
           LET CURFLD(CURFLD) !:
           LETSPEC$(CURFLD)=SREP$(SPEC$(CURFLD),",N/RGB",",UHR/HRGB") ! change attributes of selections
00230 LET SEL$(CURFLD:CURFLD)="x" ! could reverse logic of prev.line to unselect
00240 GOTO 200
00250 !
00260 FOR I=1 TO LEN(SEL$)
00270 IF SEL$(I:I)<>" " THEN PRINT DATA$(I);" ";
00280 NEXT I

4. Using an alpha character for field length in INPUT FIELDS or PRINT FIELDS will now produce an error. Previously the character as well as the attributes following it were being ignored. (This may affect your programs). Extraneous characters in attribute specifications will still be ignored.

Release 3.53

5. The FMT specification is now supported for better formatting of entered data. On output to the screen with RINPUT FIELDS, FMT is equivalent to the C format spec (no formatting or verifying of data is done). See "FMT" in the Format Specifications section for complete information.

1. The cursor's field movement will respond to the arrow keys without regard to the order of the options. The down arrow will move to the field below the cursor's current position, the up arrow moves the cursor to the field above its current position, the left arrow searches to the left of the current field and continues up the screen and then from the end of the screen until it finds another field or itself. The right arrow works the same way, except right and down the screen. If there is no field in the same column as the cursor, the up or down arrow will stay at the current field.

2. The WAIT= parameter and TIMEOUT error trap may now be used with INPUT/RINPUT statements to force releasing of records. This feature is useful for multi-user situations.

WAIT= specifies the number of seconds the system should wait for operator input before responding with a TIMEOUT error condition. Note that WAIT=0 instructs the system to wait for zero seconds, not to ignore the WAIT instruction. Also, -1 is a special WAIT value that instructs the system to wait forever, if necessary. Every time the operator presses any key, the clock is reset for WAIT seconds.

INPUT WAIT=10:X$ TIMEOUT 100
RINPUT WAIT=10:X$ TIMEOUT 100
LINPUT WAIT=10:X$ TIMEOUT 100
INPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
INPUT #11,FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
RINPUT FIELDS "10,10,C 10",WAIT=10:X$ TIMEOUT 100
INPUT SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100
RINPUT #11,SELECT "10,10,C 10",WAIT=10:X$ TIMEOUT 100

The TIMEOUT error condition traps time-out errors ( error code 4145) and specifies the line number of an appropriate error-handling routine.

100 RELEASE #ITEM:
110 PRINT "OVER TIME LIMIT"
120 PRINT "Your hold on inventory items hasexpired, re-enter order."

Before releasing the record, you may want to go to a routine that warns with a message and a few beeps that the hold on records is about to be released, then gives the operator an opportunity to continue data entry. See the "KSTAT$" function in the manual for information on how to use the WAIT parameter with that function.

3. The ATTR parameter in FIELDS and SELECT statements now accepts MAT variables. This feature allows for a different "current" attribute for each input field. Thus if using INPUT SELECT to select many items from a list, the non-current and current attributes may be different for both selected and un-selected items. Note the following sample syntax:

MAT FF$ is compiled for attributes ONLY, and stops at the end of the array or the first error. If there are not enough attributes for each entry field, the first one will be used. For an  example of this feature in action, enter and execute the following sample program:

00100 ! matattr ! example of ATTR MAT attrs specification
00110 PRINT NEWPAGE
00120 PRINT FIELDS "1,2,c 30,/RGBH:R": "[F6]-End selections"
00130 DIM ATTRS$(15),SPEC$(15),DATA$(15)*8
00140 FOR I=1 TO UDIM(ATTRS$) ! set up mats
00150 LET ATTRS$(I)="U/RGB:R"
00160 LET SPEC$(I)=STR$(I+3)&",10,c 8,N/RGB"
00170 READ DATA$(I) : LET SEL$=SEL$&" "
00180 NEXT I
00190 DATA One,Two,Three,Four,Five,Six,Seven,Eight,Nine,Ten
00192 DATA Eleven,Twelve,Thirteen,Fourteen,Fifteen
00200 RINPUT SELECT MAT SPEC$,ATTR MAT ATTRS$: MAT DATA$
00210 IF CMDKEY>0 THEN GOTO 250
00220 LET ATTRS$(CURFLD)="HU/RGBH:R" !:
           LET CURFLD(CURFLD) !:
           LET SPEC$(CURFLD)=SREP$(SPEC$(CURFLD),",N/RGB",",UHR/HRGB") ! change attributes of selections
00230 LET SEL$(CURFLD:CURFLD)="x" ! could reverse logic of prev. line to unselect
00240 GOTO 200
00250 !
00260 FOR I=1 TO LEN(SEL$)
00270   IF SEL$(I:I)<>" " THEN PRINT DATA$(I);" ";
00280 NEXT I

4. Using an alpha character for field length in INPUT FIELDS or PRINT FIELDS will now produce an error. Previously the character as well as the attributes following it were being ignored. (This may affect your programs). Extraneous characters in attribute specifications will still be ignored.
   
5. The space bar will now move the cursor from option to option.
   
6. INPUT SELECT and RINPUT SELECT will now hide the cursor if ATTR (floating attribute) is specified.

WRITE Release 3.61

The WRITE statement may be used to add or insert a record into an existing linked list. (A linked list is not considered to be "existing" unless an anchor point has been established for it with a RESTORE statement.) For example, the RESTORE statement in the following code fragment establishes a new anchor point for a new linked list. The WRITE statement is then used to write the anchor record.

1000 RESTORE #1:
2000 WRITE #1, USING "FORM X 8,C 18":"NEW LINKED LIST"

Keep in mind that the first eight bytes of a linked record are always reserved for the next and previous record pointers. Business Rules! will not produce an error if a program attempts to write to these positions. This is a potential danger in that your program could potentially overwrite this crucial information. However, it is also an advantage in that you are allowed to write to these fields and potentially modify, combine or correct existing lists.

With linked files, it is possible to insert a new record between two existing records in the file. However, it is important to note that the new record will still use a record number that is assigned sequentially based on all records in the file. Consider, for example, a linked list file that has had 1000 records written to it. If a program were to insert a new record between existing records with record numbers of 9 and 10 respectively, the new record would still be assigned a record number of 1001. The resulting order of these records would therefore be 9, 1001, 10. This is the reason that it is important to make sure that the record number of a linked list's anchor record always be updated to the master file.

To insert a record into the linked list, it is necessary to first position the file pointer to the desired insertion point. Typically, a program would issue a RESTORE REC={anchor} statement to get to the anchor point of the desired list, then read sequentially to get to the desired insertion point. However, using RESTORE REC= to position into the middle of a chain is permissible. Such an insertion will occur ahead of the record pointed at by the restore operation. At the end of each read or write operation the "write" file position is advanced to just beyond the last record processed.

A RESTORE REC={anchor} followed directly by a WRITE statement will insert a new record at the beginning of the linked list. Thus the old anchor record will become a linked record and the newly inserted record will become the new anchor record. Also, KREC will be updated to return the record number of the new anchor record (see the KREC function description).

Business Rules! will automatically update the next and previous record pointers (held in the first eight bytes of each linked record) of the affected records when a linked list record is added.