BR Wiki - User contributions [en]

Screen Operations

2026-04-13T04:22:15Z

Gordon.dye:

[[Business Rules!]] advanced '''Screen Input/Output''' capabilities include many abilities:
* Print to and input from any position on the screen (full screen processing)
* Designation of one or more portions of the screen as its own mini-screen (windowing)
* Change the screen's display features through the use of screen attributes

==Full Screen Processing==

Full screen processing allows data entry [[controls]] on any position on the screen, specified by [[Row]] and [[Column]]. This contrasts with sequential screen processing, which allows prompted data display and entry with [[PRINT]], [[INPUT]], [[LINPUT]] and [[RINPUT]] statements, but only allows access to the bottom line of the screen. (Lines in regular screen processing then scroll up until they scroll off the top of the screen.) With full screen processing, any position on the screen may be addressed directly.

;Besides allowing access to any position on the screen, full screen processing provides several additional advantages:
# Screens can be attractively designed, making programs appear professional.
# Less code is required. One screen that fully utilizes Windows control attributes and displays ten prompts and ten input fields can be programmed in as few as two statements.
# The operation of the input screen can be controlled. Control attributes may be used to specify starting cursor positions, automatic entry of data, field protection and more.

===Graphical Console===

A separate command console handles the operator commands without interfering with the graphical console. Print newpage goes to the command console if at the command prompt, and to both in a program. [[Print]] anything else will only go to the [[command console]].

The [[GUI console]] can be opened to other than 80 columns by 24 rows:

An OPEN window statement may specify a parent window number.

Two fonts are supported simultaneously, one for background and captions and one font for input fields.

;Always [[Print Newpage]] Initially When Full Screen Processing

====Multiple Field Processing====

The full screen processing statements allow you to input and output multiple fields with a single statement. This can be accomplished in two main ways: with repetitions of individual parameters directly within the full screen processing statement; or with the use of array parameters which reference a string variable, coded elsewhere in the program, that includes all the information required for the various specifications.

In the following example, six fields are processed by each of two full screen-processing statements. In each case, all information required to process the multiple fields is included in the actual statement. In line 140, the field definitions and variable names are specified for six prompts. In line 150, the current values are output and the changed values (as updated by the operator) are input; this line also includes field help information for two of the six fields.

00120 DIM COMP$*25, STREET$*35, ADDR$*35, NAME$*20
00130 PRINT NEWPAGE
00140 PRINT FIELDS "6,11,c 20; 8,11,c 20; 10,11,c 20!:12,11,c 20; 14,11,c 20; 16,11,c 20" : PRID$, PRCOMP$,PRSTREET$, PRADDR$, PRNAME$, PRPHONE$
00150 INPUT FIELDS "6,32,c 4,ra; 8,32,c 25,ra; 10,32,c 35,ra;12,32,c 35,ra; 14,32,c 20,ra; 16,32,c 12,ra",attr "R",help"XX2A<;Type in the street address.\nIf there is an apartment or suite number, \n type # and the number;2A<;Type in the full city name. \n Use the two-letter state code\n and the 9-digit zip code;": ID$, COMP$, STREET$, ADDR$, NAME$, PHONE$

One alternate way to code the above would be to place the field specifications and the field help window specifications each into their own array. The following code utilizes this technique but it operates exactly the same as the previous example. Line 220 prints the six prompts. Line 230 outputs the current values, accepts the updated values of the specified variables, and provides field help information on two of the six fields.

00110 DIM PROMPT$(6)*20, FLDDEF$(6)*16, DATADEF$(6)*15,FIELDHELP$*200
00120 DIM COMP$*25, STREET$*35, ADDR$*35, NAME$*20
00130 ! **** Operator Prompts For Prompt$ Array
00140 DATA ID number,Company Name,Street address,City/State/ Zip, Contact, Phone
00150 ! **** Field Definitions For Prompts (FLDDEF$)
00160 DATA "6,11,c 20","8,11,c 20","10,11,c 20","12,11,c 20","14,11,c 20","16,11,c 20"
00170 ! **** Field Definitions For Data Entry (DATADEF$)
00180 DATA "6,32,c 4,ra","8,32,c 25,ra","10,32,c 35,ra","12,32,c 35,ra","14,32,c 20,ra","16,32,c 12,ra"
00190 READ MAT PROMPT$, MAT FLDDEF$, MAT DATADEF$
00200 LET FIELDHELP$="XX2A<;Type in the street address.\nIf there is an apartment or suite number,\ntype # and the number;2A<; Type in the full city name.\nUse the two-letter state code \n and the 9-digit zip code;"
00210 PRINT NEWPAGE
00220 PRINT FIELDS MAT FLDDEF$: MAT PROMPT$
00230 RINPUT FIELDS MAT DATADEF$,ATTR "R", HELP FIELDHELP$: ID$, COMP$, STREET$, ADDR$, NAME$, PHONE$

There are a few important items to be aware of when specifying multiple fields in full screen processing statements.
# When a string array is specified for field definitions (as with FLDDEF$ in line 220 above), extra elements in the string array will be ignored. Thus, if FLDDEF$ contained seven field definitions instead of six, the seventh would be ignored.
# The order of definitions in an array determines the order of processing. The first element of the array corresponds to the first item to be processed, the second element of the array corresponds to the second item to be processed, and so on. The order of items in the field definition does not affect your accessibility to the screen; you may define fields from the bottom of the screen to the top or from the top to the bottom or in any other way you prefer.
# It is important to remember that fields should be referenced in a consistent order throughout the full screen processing statement. The order that fields are referenced in the field definition array should be the same order that they are referenced with field help and variable names specifications.
# String and numeric fields may be intermixed in any order as long as the field definitions match the corresponding variable type. For instance, in the following example, the first field definition identifies a string field that starts at row 3, column 5 and is 20 characters long. This field definition corresponds to the first variable (NAME$) in the I/O list. Likewise, the second field definition identifies a three-digit number which corresponds to the numeric AGE variable.

1000 INPUT FIELDS "3,5,C 20; 7,5,N 3" : NAME$, AGE

==Windowing==

One of Business Rules most powerful screen I/O capabilities is the ability to separate the screen into several mini screens, or I/O windows. These windows can do all the same things (including scroll) that the regular full screen can do. In addition, an I/O window may have a border and a caption in the top line of the border.

===Open Display (Screen)===

00410 OPEN #0: "Srow=nn, Scol=nn, Caption=APPLICATION NAME", DISPLAY, OUTPUT
-or-
00420 OPEN #0:"Srow=nn, Scol=nn, Caption=APPLICATION NAME, Buttonrows=nn",DISPLAY, OUTPUT

00420 Open #0: opens the main window, A number other than Zero opens a child window if "PARENT=XX" is included in the open string and XX refers to an existing open window number.

Opens a Windows window. Optionally sets the number of button rows (0-3). (Button rows are additional rows at the bottom of the screen that Business Rules can use for optional button placement.)

Display file OPEN file reference strings can contain COPIES=nn. The nn value will replace the new [COPIES] argument in SPOOLCMD.

===Windows vs Field Help Windows===

Although they share many similarities, Business Rules I/O windows and field help windows are specified in very different ways and they are used for very different purposes.

The primary difference is that Business Rules treats an I/O window as its own input/output file. Information may be sent to and received from it with statements such as PRINT, INPUT, LINPUT, and RINPUT.

In addition, information may be sent to and received from a window (as if it were the regular screen) by the full screen processing statements.

In contrast, input from and output to field help windows are not allowed. Field help windows and the text, which appears within them, are specified by the full screen processing statements; they are designed to help the end-user determine what to do for a particular field.

The following chart should help to clarify other similarities and differences between I/O windows and field help windows.

[[Image:NEWC0050.jpg]]

===Border===
Requires [[4.16]]+

WINDOW BORDERS

BORDER= any valid border spec produces a single line border.

BORDER= NONE produces no border, same as not specifying a BORDER parameter at all.

===Borders (Legacy)===
Only supported in Business Rules! versions prior to 4

One of the greatest similarities between I/O windows and field help windows is in the types of borders that are available for each. For I/O windows, borders are specified with the [[OPEN window]] and [[PRINT BORDER]] statements. For field help windows, they are specified with the [[FieldHelp]] specification.

Each of these three specifications uses syntax, which is nearly identical, where the border type is concerned. Each has a "BORDER" keyword (in the case of OPEN window, its "BORDER=") followed by one of six options for specifying the border: "B" (blank), "D" (double-line), "H" (sHadow), "S" (single-line), "corners", and "8 chars".

The first four border options are predesigned. The following illustrations show examples of each. (Keep in mind that the attributes specified with a border provide hundreds of opportunities for variation.)

[[Image:HELP0134.jpg]]

The last two border options allow you to custom-design your own borders. With the "corners" parameter, you can specify just the top left and bottom right characters (and let Business Rules fill in the rest). Or with the "8 chars" parameter you can specify eight characters that identify the corner and middle characters for every side of the border. The following illustration shows the sequence in which the eight characters must be specified:

1|2|3

8||4

7|6|5

The following example shows the use of the "8 chars" parameter with graphic drawing characters which may be toggled on for the 0-9 and period (.) keys by pressing Ctrl-\. This example creates the same border that is created by the S border type. It also includes the "r" attribute to reverse the border.

[[Image:HELP0135.jpg]]

The next sample code shows some of the options that are available with borders for windows. A good way to see both windows and field help windows in action would be to type this code in and use the RUN STEP command to execute it.

00005 PRINT NEWPAGE
00007 DIM FIELDHELP$*50, NULL$*50
00009 EXECUTE "config fieldhelp border=H"
00010 OPEN #1:"srow=4,scol=10,erow=8,ecol=37,border=S,caption =>S (Single-line border)",DISPLAY,OUTIN
00020 OPEN #2: "srow=4,scol=45,erow=8,ecol=72,border=d",DISPLAY,OUTIN
00030 PRINT #2, FIELDS "3,4,cc 22": "D (Double-line border)"
00040 input fields "12,15,c 50,r",help "1B; This is a field help window \n using an H (sHaded) border. \n \n Type in any CONFIG FIELDHELP \n specification such as the following: \n CONFIG FIELDHELP BORDER=BR;": FIELDHELP$
00045 PRINT FIELDS "12,15,C 50,N": NULL$
00050 EXECUTE FIELDHELP$
00090 INPUT FIELDS "18,35,c 18",help "1A; This window uses the border you specified. \n If you typed in the suggested border, \n it is B (blank) using the R (reverse) attribute.\n \n Now watch the upper left window while pressing<CR> \n to see the effects of PRINT BORDER.;": CR$
00100 PRINT #1, BORDER "*-*|*-*|": "custom-designed border"
00105 CLOSE #1,DROP:
00106 CLOSE #2,DROP:

In the above example, line 9 uses an [[EXECUTE]] statement to set the border type for all field help windows. Line 10 opens an I/O window with a single-line border and a caption in the top border that is right justified and says "S (Single-line border)".

Line 20 opens an I/O window with a double-line border. Line 30 then centers the string "D (Double-line border)" within the window. NOTE that the row and column specified in this statement assume that the top left corner of the window is row 1, column 1.

Line 40 specifies a field that accepts input on line 12 of the regular screen. It includes a field help window with text that describes its border as a shaded border (this border type for field help windows was specified back in line 9). This window also tells the user to type in a CONFIG FIELDHELP specification that identifies a new border type for field help windows.

Line 45 prints a null string over the area where the reversed input field for line 40 appeared, thus cleaning up the screen.

Line 50 executes the string typed in for line 40 to change the border type for all field help windows.

Line 90 specifies an input field that accepts input on line 18 of the regular screen. It includes a field help window that utilizes the new field help border type executed in line 50. It then instructs the user to watch the upper left window to see the effects of a PRINT BORDER statement.

Line 100 uses PRINT BORDER to change the border in window #1. The specified border uses the "8 chars" parameter, which is available in all the Business Rules instructions that specify border types (OPEN window, PRINT BORDER, and FIELDHELP).

Lines 105 and 106 close and drop the contents of the two open windows. Although the terminology may seem a little confusing at first, the act of closing a window causes the window's border to disappear and the information that was hidden by the appearance of the window to be restored. Thus, if lines 105 and 106 simply closed (without dropping) windows #1 and #2, the borders would disappear and a blank screen would be restored.

However, the act of closing and dropping a window file leaves the current contents of the window and its border intact at the same time that it drops the information that was hidden by the appearance of the window.

===Using I/O Windows to Save the Screen (Prior to 4.0)===

Beginning with 4.17 the [[TABS]] feature is used to display multiple windows and switch between them. See TABS later in this chapter. Saving a portion of the screen is not necessary after 4.0 because the graphic window that is opened on top of an existing window does not destroy the information on the layer below. The underlying information automatically becomes visible when the top window is closed. In versions prior to 4.0 there were not separate layers, consequently the replaced information would need to be saved in a separate screen file and restored (closed) when the overlaying information was no longer needed.

Saving all or part of the screen is very easy with I/O windows. All it requires is opening a borderless window using row and column parameters that encompass all the information to be saved. The following example saves an entire screen without making any changes to the appearance of the screen:

00670 OPEN #1:"SROW=1,SCOL=1,EROW=24,ECOL=80:,DISPLAY,OUTIN

It is useful to note that an OPEN window statement's row and column parameters identify the inside portion of a window. If a border is specified for a window, it is always placed one position outside the specified row and column.

Once an entire screen has been saved with a window, the existing screen may be altered any number of times without affecting what was saved from behind the window. Restoring the saved screen (including all attributes) is accomplished with a CLOSE statement as follows:

00750 CLOSE #1:

The capability of saving a screen becomes very useful when you wish to switch between overlapping windows. The following example demonstrates such a use:

00010 print NEWPAGE
00020 open #1: "srow=5,scol=5,erow=15,ecol=50,border=dn",display,outin
00030 print #1,fields "1,2,c 30": "Business Rules window 1"
00040 print #1,fields "10,2,c 30": "F1 to go to window 2"
00050 input #1,fields "4,4,c 10,u": X$
00060 if CMDKEY<>1 then goto 180
00070 open #101: "srow=4,scol=4,erow=16,ecol=51",display,outin
00080 if FILE(2)<>-1 then goto 130
00090 open #2: "srow=8,scol=20,erow=18,ecol=61,border=dn",display,outin
00100 print #2: NEWPAGE
00110 print #2,fields "1,2,c 30": "Business Rules window 2"
00111 print #2,fields "9,2,c 30": "F1 to go to window 1"
00120 goto 140
00130 close #102:
00140 input #2,fields "4,4,c 10,u": X$
00150 if CMDKEY<>1 then goto 180
00160 open #102:"srow=7,scol=19,erow=19,ecol=62",display,outin
00170 close #101: : goto 50
00180 stop

Essentially, the above program allows the user to switch between two windows by pressing the F1 key (lines 50 and 140). If the user presses F1 from window #1, the program saves window #1 by opening a borderless window (#101) that encompasses the data area of the window. It then opens window #2 (if window #2 already exists, window #102 is restored). If the user then presses F1 to go back to window #1, the contents of window #2 are saved in window #102. Window #101 is then restored (over the top of window #2) with the CLOSE statement. The same sequence of saving and restoring windows can continue indefinitely.

The above sample works well when running on [[CONFIG GUI OFF]] mode. This was the only available mode in version prior to 4.0. With the introduction of []CONFIG GUI ON]], "Using I/O Windows to Save the Screen", is no longer appropriate.

In [[CONFIG GUI OFF]] mode, opening a new window will preserve any information displayed at the time the window was created. Essentially, the information "behind the window", will "bleed through" the newly opened window. You may change any information on the screen that has been protected by this window, and when you close the window, the original text will be restored.

In the above sample, there is the illusion of multiple layers, but in reality, each window is only preserving a "screen shot" of the information, and not maintaining each of the layers. In other words, your 80 x 24 visible screen looks correct, but no other information is displayed. Information may be printed to any of the virtual layers, and it will be visible to the user, and when you close the window, the original text will be displayed as originally captured.

As an example, you can update a window that covers part of the screen, and use Print #0, to update the "Visible Area" in front of the window. Later when you close the window, the original information will be restored.

Following the above example application, in GUI OFF mode:

Line 10 erases the screen
Lines 20-50 Open Window #1, (5,5 to 15,50) and display some information.

When the user presses "F1":
Line 70 "Protects Window #1, (4,4 to 16,51), by opening window #101. Notice this new window is large enough to cover the line draw.
* Note: Window #1 is still open, and could be used to display information, but regardless of how the screen is updated, the entire original information will be restored when window #101 is closed.

Line 90-120 Open Window #2, (8,20 to 18,61) and display some more information
* Note: Window #2 covers up some of both windows #1 & #101. Again, Window #2 protects the contents of these two windows. And regardless of how the screen is updated (Handles #1,#101 or #2), the original information protected by window #2 will be restored when Window #2 is closed.

Again the users presses "F1":
Line 160 "Protects Window #2, (7,19 to 19,62), by opening window #102, Notice this new window is large enough to cover the line draw.
* Note: Windows #1,#101 and #2 are still open, and could be used to display information, but regardless of how the screen is updated, the entire original information will be restored when window #102 is closed.

The next line performs some "Fancy Magic".
Line 170 closes Window #101, (4,4 to 16,51) This causes the original text protected by Window #101 to be "restored". The effect of closing this window is that the original text created by Window #1, and then protected by Window #101, is now restored.

As you continue pressing F1, windows #101 & #102 take turns protecting and the restoring the two windows. The effect of this programing is the user sees what appears to be two complete layers. In other words, there is the illusion that the contents of both windows are actually still on the screen, and that pressing "F1" is switching layers.

In [[CONFIG GUI ON]] mode, opening a new window actually create a new layer or container without affecting the information behind it. The new window is now transparent, so the effect is very similar to a [[Print Newpage]] command. This new window may or may not have a border. In this mode, you no longer have a single 80 x 24 layer, rather each window has it's own private space. Information must be printed to the correct layer.

As an example, you can open a window that covers part of the screen, and use Print #0, to update the "Hidden Area" behind the window. Later when you close the window, the updated information will be displayed.

Examining the same code again, but using the GUI ON mode:

Line 10 erases the screen
Lines 20-50 Open Window #1, (5,5 to 15,50) and display some information.

When the user presses "F1":
Line 70 "Completely covers Window #1, (4,4 to 16,51), by opening window #101.
* Note: Window #1 is still open, and intact, but is no longer visible because window #101 is actually a new layer and contains no information Windows are not transparent in GUI ON mode. Window #1, remains unaffected as long as nothing is printed directly to Window #1. You could if desired, update Window #1 directly, but the changes would not be immediately apparent.

Line 90-120 Open Window #2, (8,20 to 18,61) and display some more information
* Note: Window #2 creates a new layer that covers up some of both windows #1 & #101. Because Window #101 is hiding Window #1, Window #2, appears to "Pop-Up", with Window #1 "Disappearing".

Again the users presses "F1":
Line 160 "Completely covers Window #2, (7,19 to 19,62), by opening window #102. Now the screen appears to be blank.
* Note: At this point, Window #1, is covered by Window #101, and Window #102 partially covers Window #1 & #101. Window #102 is the "Top Layer".

Line 170 closes Window #101, (4,4 to 16,51). This causes a rather strange effect as compared to the GUI OFF version. Window #1, is now partially visible because it is not covered by Window #101. However, Windows #2 & #102 are still partially covering Window #1. The effect is that Window #1 appears "Broken".

As you continue pressing F1, windows #101 & #102 take turns partially hiding the two windows. In GUI ON mode, this sample application looks terrible!

Make the following few changes to the sample program.

00070 ! OPEN #101: "srow=4,scol=4,erow=16,ecol=51",DISPLAY,OUTIN
00130 ! CLOSE #102:
00160 ! OPEN #102: "srow=7,scol=19,erow=19,ecol=62",DISPLAY,OUTIN
00170 ! CLOSE #101: !:
GOTO 50

These small changes create a new behavior that is more appealing. Now, pressing "F1" will simply move focus between the two windows. Notice that Window #2, always covers Window #1, but the user can still enter data as the focus changes.

A few more changes create the following example:

00010 PRINT NEWPAGE
00020 OPEN #1: "srow=5,scol=5,erow=15,ecol=50,Tab=Window 1",DISPLAY,OUTIN
00030 PRINT #1,FIELDS "1,2,c 30": "Business Rules window 1"
00040 PRINT #1,FIELDS "10,2,c 30": "F1 to go to window 2"
00050 INPUT #1,FIELDS "4,4,c 10,u": X$
00060 IF FKEY=93 OR FKEY=99 THEN GOTO 180
00080 IF FILE(2)<>-1 THEN GOTO 140
00090 OPEN #2: "srow=5,scol=5,erow=15,ecol=50,TAB=Window 2",DISPLAY,OUTIN
00100 PRINT #2: NEWPAGE
00110 PRINT #2,FIELDS "1,2,c 30": "Business Rules window 2"
00111 PRINT #2,FIELDS "9,2,c 30": "F1 to go to window 1"
00120 GOTO 140
00140 INPUT #2,FIELDS "4,4,c 10,u": X$
00150 IF FKEY=93 OR FKEY=99 THEN GOTO 180
00170 GOTO 50
00180 STOP

Run the program, and press "F1" as instructed. Notice that the tabs in fact are separate layers that preserve the text you type. As long as you are in GUI Mode, feel free to use the mouse to navigate the tabs.
This modified version will only exit when you press Escape, Alt-F4 or click on the "X" to close the window.

==Syntax of Statements==

;Each of the full screen processing statements has basically the same syntactical form, which can be divided into the following six portions:
:1.) Statement name and I/O location.
:2.) Field definition.
:3.) Attribute for current field (not applicable for PRINT FIELDS).
:4.) Field help specifications (not applicable for PRINT FIELDS).
:5.) I/O list.
:6.) Error condition list.

Each of the above portions are identified in the following syntax diagram for full screen processing statements. This diagram will be used for reference in describing the syntax of four of the five of the full screen processing statements. (See the Statements chapter for a separate description of the PRINT FIELDS statement.) Since the following syntax diagram is rather complex, each portion will be described separately in the parameter descriptions that follow.

[[Image:HELP0131.jpg]]

;Defaults:
:1.) Display to and input from the screen.
:2.) Do not alter attribute when field is current.
:3.) Do not display field help text.
:4.) Interrupt the program if an error occurs and "ON error" is not active.

===Statement Name I/O Location===

The "Statement name, I/O location" portion of the syntax for full screen processing statements identifies the statement being used and the file number of the window which is to be used for input or output.

;Parameters:
The primary keyword ("INPUT", or "RINPUT") of the statement being used must be specified first.

"Wind-num" references a window file that has already been opened by an OPEN window statement. When this parameter is used, Business Rules input from and output to the window as if it were a separate screen: the first row and column of the window will be considered row 1 and column 1. When "wind-num" is not specified, file #0 (the full screen) is assumed.

The secondary keyword ("FIELDS" or "SELECT") of the statement being used must be specified next.

===Field Definitions===

;Purpose:
The "Field definition" portion of the full screen processing syntax identifies the following for each field: row number; column number; format type; length of the data to be input; and the monochrome, color and control attributes which are to be used for the field.

;Comments and Examples:
The following statement identifies a field that starts at row 6, column 3. The field is numeric and has a total length of 7 characters, one of which is a decimal point and two of which are decimal digits. When the statement is executed on a monochrome monitor, the field will appear as reversed and highlighted. When the statement is executed on a color screen, the background of the field will be red. The name of the variable to which input will be assigned is AMOUNT.

00750 INPUT #7, FIELDS {\b "6,3,N 7.2,HRE/:R"}: AMOUNT

;Insertable syntax ("field-spec" parameter):
[[Image:HELP0132.jpg]]

;Defaults:
:1.) Fraction length = 0.
:2.) Maximum DIM length.
:3.) Use current attributes.

;Parameters:
The above syntax may be inserted where the "field- spec" parameter appears in the main diagram for full screen processing statements. If the "string-expr" or "MAT string-array" parameters are used to specify the field definition, each must include the same elements that are identified in the "field-spec" parameter.

The "row" parameter is a required integer value that indicates the row number on the screen or in the window where the data is to be entered.

The "column" parameter is a required integer value that indicates the starting column number on the screen where data is to be entered.

The next set of parameters specifies the format type of the data to be entered. There are three possible routes.

In the top route, "num form-spec" represents a numeric format specification. G, GL, GU, GZ, L, N, and NZ are all valid in this position; the specification must be followed by a space. The "field-length" parameter, which is an integer value that identifies the length (including decimal point and decimal positions) of the field, comes next. If the field contains decimal positions, "fraction" should identify how many there are; this parameter must be separated from the field length by a period (no spaces).

In the middle route, "string form-spec" represents a string format specification. C, CC, CR, CL, CU, G, GL, GU, GZ, V, VL and VU are all valid in this position. If "field length" is used, it must be separated from the format spec by a space.

In the bottom route, the "PIC" or "FMT" specification allows you to specify a picture of the field to be input. See the File I/O chapter for a list of the characters that may be used in the "(pic-spec)" portion of this parameter.

See the File I/O chapter and APPENDIX F Format Specification for additional information about all the format specifications listed in this section.

The "attributes" parameter represents an insertable syntax that identifies the monochrome, color and control attributes that are to be used for the field. See the Definitions chapter for the insertable syntax and for additional information about this parameter.

Additionally fonts can be controlled at the field level by assigning them to attribute substitution letters as in:

:CONFIG ATTRIBUTE [J]RH,font=ariel,slant,max \line This specifies reverse highlight ariel italics maximum size.

===Attribute for Current Field===

;Purpose:
The "Attribute for current field" portion of the full screen processing syntax identifies the attribute that should be used for the field that the cursor is on.

;Parameters:
The "ATTR" keyword identifies that a separate set of attributes should be used for the current input field. It must be followed by either the "attributes" parameter or the "string-expr" parameter. "Attributes" represents an insertable syntax that identifies the monochrome, color and control attributes that are to be used for the field. See the Definitions chapter for the insertable syntax and additional information.

If used, the value of "string-expr" must include the same elements as are required in the "attributes" parameter.

;Hot text

Hot text may be displayed as either text or buttons. To make it display as a button, the trailing attribute specification should be a B followed by the fkey value to be returned when the button is clicked. e.g. "20,5,CC 12,,B1244" displayed as a button with fkey value 1244. Beginning with 4.16 the default behavior for a Hot Text field is a button. The Button may be suppressed by using an "H" instead of the "B" or no letter.

Any FIELDS text may now generate a keyboard scancode when double clicked, similar to the way BUTTONS and the Combo Box graphic do. Even linedraw characters can be "hot".

When a picture is specified as an input field, all non-navigation keys are ignored.

;Additionally fonts can be controlled at the field level by assigning them to attribute substitution letters as in:

;The Shaded Sunken Appearance:

Normal Windows behavior is to grey out any data entry fields that are inactive. Consequently, this is how labels appear when they are sunken. This defeats the ability to use a sunken approach to hilight screen headings. For example if you specify SCREEN U 0173 and then specify U as a leading attribute in a PRINT FIELDS specification, the field will be displayed sunken but grey.

You can now override the normal Windows behavior with regard to greying out sunken labels by specifying S as a leading attribute. The S (sunken- formerly shaded) field attribute calls for a white sunken field irrespective of whether the field is open for input.

;Fields Color Attributes

In an input or print fields statement the attributes after the slash can only contain valid color attributes such as HRGB or #RRBBGG. In the past the "N" attribute was accepted in this location. Beginning with 4.17i any non-color attribute in the color section will generate an error.

;Additional Date() Formats are supported:

[NEWCELL(icells2l.spc)]

Also, a new FIELDS format is supported

row,col,DATE(dd/mm/yy)

The values are displayed as dates but are stored internally as day of century. The mask may be any valid DATE() mask.

===Field Help Specifications===

{{:Field Help}}

===I/O List===

;Purpose:
The "I/O list" portion of the syntax for full screen processing statements identifies the information that is to be input or output by the statement.

;Comments and Examples:
With [[INPUT FIELDS]] and [[INPUT SELECT]], the I/O list identifies the variables to which the input is to be assigned. With [[RINPUT FIELDS]] and [[RINPUT SELECT]], the current values of the I/O list are output, the output values are updated by the operator, and the updated values are re-input to the specified variables.

;Parameters:
A colon (:) must separate the I/O list from any previous parameters in the full screen processing statement. At least one "var-name" or "MAT array-name" must be specified. These two parameters represent the list of variables to be assigned values from the entered data. multiple variables must be separated by commas

===Error-Cond List===

;Purpose:
The "Error-cond list" portion of the full screen processing syntax identifies the types of errors that should be trapped and where execution should be transferred to when such errors are trapped.

;Parameters:
The "error-cond" portion of the parameter identifies the error to be trapped, and the "line-ref" portion identifies the line to which execution should be transferred when such an error is trapped.

;Technical Considerations:
1.) Relevant error Conditions are: CONV, Error, Exit, Help, IOERR, and SOFLOW.

===Console Characteristics===

The name of the directory with examples for this section is: EXAMPLES\CONSOLE

A separate command console handles the operator commands without interfering with the graphical console. PRINT NEWPAGE outputs to the command console from the command prompt, and to both consoles in a program. Regular PRINT statements and PRINT USING statements output only to the command console. PRINT FIELDS and PRINT BORDER output only to the graphical console.

The name of this example is: CONSOLES.BR

00100 PRINT NEWPAGE ! output to both consoles
00200 PRINT "ABC" ! output to command console
00300 PRINT using "form C 4,C 2,N 2" : "WXYZ"," ",24! output to command console
00400 PRINT FIELDS "15,4,C 15": "million dollars"! output to graphical console
00500 PRINT #0, BORDER "Billion dollars":! output to graphical console

;Output:
[[Image:NEWC0009.jpg]]

The consoles can be opened to other than 80 columns by 25 rows:

OPEN #0: "Srow=5,Scol=5,Rows=30,Cols=100", display, outin ! specifies position on screen and size in chars

An OPEN window statement may specify a parent window number. In the following example, window #1 is opened as a child of window #0. Srow= and Scol= reference window #0.

The name of this example is: CHILDWIN.BR

00100 OPEN #1: "SROW=2,SCOL=2,EROW=5,ECOL=20,border=S,caption=MyWindow,Parent=0",display, outin

;Output:
[[Image:NEWC0010.jpg]]

File numbers 300-999 are now supported in addition to those below 200.

When a user defined Windows menu is displayed, the Preferences menu is suppressed. When the user-defined menu is cleared, Preferences is restored.

===Datahilite===

The default under Windows is to reverse each field as it is entered, and to position the cursor at the end of the data.This type of processing can be turned off, by specifying DATAHILITE OFF in the BRconfig.SYS file.

;3D Fields applies to pre 4.0 versions:

The 3D FIELDS parameter UNDR ON ignores all other attributes for underlined fields. Traditionally, BR has used either the N (normal) attribute or R (reverse) attribute and ORed the other attributes specified (H, B, and U). Now it works the same way, unless UNDR ON is specified and U is present, in which case it uses the U value exclusively. This provides greater control over the color scheme with 3D FIELDS active. You can use H for other purposes without affecting UH processing.

{\b CONFIG DATAHILITE WIN ON} indicates that the user's Windows specifications for selected text should apply to highlited text.

{\b CONFIG DATAHILITE WIN OFF} can be used to turn this feature off.

;Two new parameters were added to the {\b DATAHILITE} configuration statement:

XX Uses color attribute XX (as specified in a SCREEN statement) for the "selected" text. 
[X] Use the color specification associated with [X] in the ATTRIBUTE configuration statement.

The 3D FIELDS parameter UNDR ON ignores all other attributes for underlined fields. Traditionally, BR has used either the N (normal) attribute or R (reverse) attribute and ORed the other attributes specified (H, B, and U). Now it works the same way, unless UNDR ON is specified and U is present, in which case it uses the U value exclusively. This provides greater control over the color scheme with 3D FIELDS active. You can use H for other purposes without affecting UH processing.

FIELDS3D has been changed to 3D FIELDS.

When 3D fields are enabled, the screen requires more vertical space than it otherwise would. Therefore, the BR window takes on a rectangular appearance, and doesn't look as good in full screen mode as it does as a window.

To activate this feature, specify 3D FIELDS ON in your BRconfig.SYS file and also specify SCREEN U 0170 only. (Or specify SCREEN U 0170,N 38 to add some flair.)

You can also use the CONFIG command to activate this feature, but if so, you must OPEN #0: "SROW=1,SCOL=1", DISPLAY, OUTIN after executing the CONFIG command.

Specifying 3D FIELDS in BRconfig.SYS is not sufficient to activate it. You must also either precede a standard field attribute with 01 (e.g. U 0170) or specify S as a leading field attribute in your FIELDS specification.

e.g. INPUT FIELDS "10,10,C 10,S": X$ The preferred way for legacy code to activate 3D FIELDS is to use the SCREEN statement.

Ctrl-Z will act as undo when DATAHILITE is on.

===Window on a field===

The ability to enter and process more text than a window field can display at one time is included. This is a very powerful feature that lays the groundwork for support of proportional fonts. You will, for example, be able to enter and maintain fifty characters of data in a twenty character field on any platform.

;The syntax for enabling this capability is:

00100 INPUT FIELDS "row,col,20/C 50,N/W:W": name$

Which enables up to 50 characters to be entered into a 20 character window field.

;This syntax was changed in the July release of BR 4.17. It used to be:

00100 INPUT FIELDS "row,col,C 20/50,N/W:W"

where 20 was the width of the "window" and 50 was the allowed width of the data entry field. 4.17 changed this so that it would be compatable with more format statements (and easier to understand).

This new syntax also works for

00100 INPUT FIELDS "row,col,20/PIC(##D##D##),N/W:W"

and for

00100 INPUT FIELDS "row,col,date(M3 d, cy),N/W:W"

;Window on a field processing

The syntax for window on a field has been changed to accommodate more options. The displayed length of the field is the first parameter and precedes the field size.

01200 RINPUT FIELDS "10,20,40/C 100,N/W:W":TEXT$

Displays and allows input to a 100 character variable TEXT$ in a field that only uses 40 characters of screen space.

To accommodate extended field capacities with 'display under mask' field types, BR now uses the following syntax:

row,col,displayed-length/field-spec 
e.g. 5,10,7/N 10.2 
- 10 digits with decimal point displayed in 7 char field 
or 7,10,11/PIC(#,###.##) 
- 7 digits with punctuation displayed in 11 char field

The main use for this feature is to shorten the displayed length when displaying proportional fonts as in 9,10,20/C 25.

OPTION 45 allows the old method of extended field specification in addition to the new method. If the older format is encountered without Option 45, then error 861 is reported.

;Text Box

A text box with wrapping text can be displayed in BR if the field is opened in a window. An input fields statement that exceeds the width of the window will wrap within the window and allow data entry in wrapping format.

00100 OPEN #10:"SROW=10,SCOL=10,ROWS=5,COLS=20",DISPLAY,OUTIN
00200 RINPUT #10,FIELDS "1,1,100/C 2000,N/W:W":TEXT$

Will wrap an input fields data entry field within a window that is 5 rows by 20 columns. This window will wrap and scroll to allow entry of a 2000 character string.

==Graphical Controls==

'''Graphical Controls''' are also known as [[Widgets]].

RADIO Buttons and CHECK Boxes will work with PRINT, INPUT, and RINPUT operations. A COMBO box may be processed with separate PRINT and INPUT statements. A COMBO box may also be processed with RINPUT after it has been populated with a PRINT statement. However, GRID and LIST require separate PRINT and INPUT statements and do not allow RINPUT.

===Combo Boxes===

{{:Combo Boxes}}

===Check Boxes===

{{:Check Boxes}}

===Radio Buttons===
{{:Radio Buttons}}

===MsgBox System Function===
See [[Internal Functions]]

===Combo Box Character===

The combo box character is supported like it is by the old console (Q as a leading attribute plus specification of an fkey value).

===Fonts And No Graphical Control Overlap===

Labels (strings) displayed are analyzed for spacing.. If more than one blank is found or line draw or underline characters are encountered, a new control delineated. When such individual controls (label segments) are delineated the last non-whitespace character of each subfield is check for a colon. If it is a colon the text is right justified within the subfield.

IF A CHR$(5) CHARACTER IS ENCOUNTERED IT IS REPLACED BY A BLANK AND A CONTROL BOUNDARY IS DELINEATED. Delineating a new control implies continuing output at the position where it would be if the window were using fixed fonts. This can be useful when setting up a multi-column INPUT SELECT line. This is because INPUT SELECT does not align columns with proportional fonts the way PRINT FIELDS does. Ultimately it will be preferable to recode your lookups or zooms to use LISTview.

One of the disappointments in moving to a GUI presentation is that text selection via DATAHILITE overrides the ATTR value. ATTR still applies to the 'current' field (where the cursor is) once the data is deselected. But the color of selected text is necessarily determined by the operating environment. If you want to override the color of the current field immediately upon entry, then you will have to turn DATAHILITE off so the text will not be selected upon entry.

===New Fonts and No Graphical Control Overlap===

All window displays consist of true Windows/MAC graphical controls and *proportional fonts* are supported along with non-proportional fonts. Proportional fonts are not rendered fixed size. Positioning of controls and sizing of controls on the window are managed by simulating fixed character positions.

Hot text may be displayed as either text or buttons. The default is to display it as a button. To override this default the trailing attribute specification should be an H followed by the fkey value to be returned when the button is clicked.

e.g.
"20,5,CC 12,,B1244" displayed as a button with fkey value 1244
"20,5,CC 12,,H1244" displayed NOT as a button but returns fkey value 1244

The cursor changes to a hand pointer only for hot text and pictures. It does not do so for buttons because it is self evident that they are hot.

Labels (captions) displayed are analyzed for spacing.. If more than one blank is found or line draw or underline characters are encountered, a new control is delineated. When such individual controls (label segments) are delineated the last non-whitespace character of each subfield is check for a colon. If it is a colon, the text is right justified within the SUBfield. In other words, the colon right aligns the data WHERE IT WOULD BE IF YOU WERE USING FIXED WIDTH FONTS.

IF A CHR$(5) CHARACTER IS ENCOUNTERED IT IS REPLACED BY A BLANK AND A CONTROL BOUNDARY IS DELINEATED. Delineating a new control implies continuing output at the position where it would be if the window were using fixed fonts.

One of the disappointments in moving to a GUI presentation is that text selection via DATAHILITE overrides the ATTR value. ATTR still applies to the 'current' field (where the cursor is) once the data is deselected. But the color of selected text is necessarily determined by the operating environment. If you want to override the color of the current field immediately upon entry, then you will have to turn DATAHILITE off so the text will not be selected upon entry.

The new GUI mode does NOT permit bleed through the way the old console does. That is, anything written to an underlying window is not seen until the overlaying window is removed. However, a capability called FORCE VISIBILITY (described in a separate section) overcomes this limitation for programs designed for the old BR console.

If a field is written to a window that already has an overlapping field, then the field which it overlaps (the original field on the screen) is automatically deleted. There are a couple of exceptions to this:

:1.) LABELs printed to a window using a proportional font can sometimes extend beyond the area that they would occupy as a fixed width font. When this happens, BR extends the control (text space) to the length of the proportional data. If a label is subsequently displayed in this extended area, it is positioned *under* the previous label extension. If a non-label is printed in this extended area, it is positioned *over* the label extension.

:2.) If a control is displayed over the top of a LABEL's fixed character space, the original label is stenciled (or truncated) by the new control using fixed width font logic. Each resulting segment is handled independently as if it were a separate field.

===Grid and List===
{{:Grid and List}}

===Tabs===

{{:Tabs}}

==Font Control and Color Specification==

===Attribute Substitution Name Extensions===

Field Attribute [xxx] identifiers may now be up to 12 characters long.

Fonts can be specified at the field level by assigning them to attribute substitution names as in:

CONFIG ATTRIBUTE [hilite_text] font=ariel:slant:max
or -
CONFIG ATTRIBUTE [hilite_text] /#rrggbb:#rrggbb, font=ariel:slant:max

This specifies that [hilite_text] denotes foreground and background colors specified as #rrggbb with ariel, italics, and maximum size font.

===Screen and Attribute Statements Working Together===

SCREEN statements can now use [config-attribute] references. So the preferred (more readable) method for specifying screen attributes is to first define each attribute in full words and then reference them in SCREEN statements. This means that the ATTRIBUTES and SCREEN statements can be used to progressively build upon one another:

:e.g. ATTRIBUTES [lite_blue] /#112233:#556677 (This sets lite_blue foreground and background in terms of HTML color specifications.)

ATTRIBUTES [yellow] /#442255:#887799
SCREEN N [lite_blue], U [yellow]

- or better yet -
ATTRIBUTES [normal] /W:W ! windows foreground and background
SCREEN N [normal]

ATTRIBUTES [XX] UH, font=ariel:slant:max
- or -
ATTRIBUTES [XX] UH/RGB:W, font=ariel:slant:max

On Unix terminals the above statement would be interpreted as:

ATTRIBUTES [XX] UH/RGB:
because W and font= are ignored by Unix terminal support.

Now that I have defined [XX] and other attributes I can specify:
SCREEN N [lite_blue], U [yellow], R [XX]

The /xxx:yyy embedded syntax in FIELDS statements still overrides color for the corresponding fields, irrespective of SCREEN settings. However, now a W may be specified in lieu of R, G, B and H, denoting use the current Windows colors. 
e.g. /RG:W - yellow foreground on Windows background color

Colors may now be specified as /#rrggbb:#rrggbb where rr is the red gradient, gg is the green and bb is the blue gradient. Or they may be specified as /W:W which denotes Windows foreground and background.

The *background* color attribute T denotes Transparent and applies ONLY TO LABELS (PRINT FIELDS and INPUT SELECT). This is useful for printing text over various backgrounds without showing the Windows grey around the letters.

Examples:

00080 Execute "CONFIG ATTRIBUTE [mickey_mouse] /#rrggbb:T, font=ariel:slant:max"

00090 Execute "CONFIG ATTRIBUTE [hilite_text] /#rrggbb:#rrggbb, font=ariel:slant:max"
00100 PRINT FIELDS "12,22,25/C 20,[hilite_text],520": "My Text"

This example displays up to 25 proportional characters in a 20 fixed character space in specific colors with ariel italics, maximum size, and a hot key (fkey) value of 520.

===Font Characteristics===

Multiple fonts are now supported under Windows. The default is still SYSTEMPC. Any installed non-proportional font is permitted that is named in the following BRCONFIG.SYS statement:

FONT {fontname} ...

Some of the fonts provided by Microsoft are:

Lucida Console 
Minitel 
Terminal (NT only) 
some Courier fonts

Version 3.9+ supports the command STATUS FONTS. This will report all currently installed Windows fonts that are acceptable in a FONT statement. Also fonts can be changed dynamically via the CONFIG command.

FONT= 
FONT.TEXT= 
FONT.LABELS= 
FONT.BUTTONS=

The default font is the user's Windows default font. Separate fonts may be invoked for Labels, Buttons, and Text (data entry fields):

00100 OPEN #0: "Srow=5,Scol=5,Rows=25,Cols=80,FONT=Arial", Display, Outin
:|(specifies a base font)
00200 OPEN #0: "Rows=30,Cols=100,FONT.LABELS=Terminal,FONT.TEXT=Arial,FONT.BUTTONS=Lucida Console", Display, Outin

You can also specify the following font qualifiers:

:1.) Family: decor / roman / script / swiss / modern (fixed)(this may be useful in addition to the font name for systems that don't have the specified font)
:2.) Boldness: light / bold
:3.) Style: ital / slant
:4.) Underline: under
:5.) Size: small / medium / large / max - Size is based entirely on font height.

Font Size Adjustment- adjusts the size of displayed text down to accommodate the horizontal space allocated for the text:
:1.) Width: Determine the average caps + digits character width. Then reduce the font size until the number of characters times this average fits the BR field capacity.
:2.) Width+: Determine the average letter size considering both upper and lower case letters. Then apply the width limitation.
:3.) Width-: Make the font small enough to accommodate a string of capital W's.
:4.) NoWidth: Clear the Width adjustment setting.

e.g.
00100 OPEN #0: "Rows=30,Cols=100,FONT.LABELS=Terminal:bold:slant,FONT.TEXT=Arial,FONT.BUTTONS=Lucida Console",Display,Outin

The former FONTSIZE=99x99 parameter is only supported when GUI is OFF.

Note that the maximum length of configuration statements has been increased to 800 bytes.

Also any open window statement will inherit the attributes of the parent window, except that any new font specification (labels / text / buttons) will begin with the system defaults for that category.

===Hot Text===

Any FIELDS text may now generate a keyboard scancode when double clicked, similar to the way Buttons and the Combo Box graphic do.

Hot field fkey values may now be in the ranges:
* 0-99 
* 1000-9999 
A special hot-key value of 10000 denotes the Enter key, and generates a zero fkey value.

Linedraw can also be marked as HOT.

===HTML Color Parameters===

;RRGGBB, W, and T Color Specifications

Colors may now be specified as /#rrggbb:#rrggbb where rr is the red gradient, gg is the green and bb is the blue gradient. Or they may be specified as /W:W which denotes Windows foreground and background.

The *background* color attribute T denotes Transparent and applies ONLY TO LABELS (PRINT FIELDS and INPUT SELECT). This is useful for printing text over various backgrounds without showing the Windows grey around the letters.

;Examples:

00100 EXECUTE "CONFIG ATTRIBUTE [hilite_text]/#442255:T font=arial:slant:max"
00200 OPEN #0: "caption=mikhail, Picture=Matrix.ico:NORESIZE",display,outin
00300 PRINT FIELDS "12,40,C 20/25,[hilite_text],80": "Text is twenty chars"

;Output:
[[Image:NEWC0015.jpg]]

This example displays up to 25 proportional characters in a 20 fixed character space in specific colors with arial italics, maximum size, and a hot key (FKEY) value of 80. 
IMPORTANT: Spaces are not allowed between the attribute substitution name [hilite_text] and the attribute combination /#442255:T. However, spaces are allowed between the attribute substitution name and the font specification. Also, do not put a comma after the attribute combination /#442255:T.

===Command Console Colors===

The SCREEN C xx specification determines the foreground and background colors of the command console.

===Windows Color and Font Settings===

;The current Windows color and font settings may be retrieved:
[NEWCELL(icells2l.spc)]

;For a complete list of possible values and current settings type:

STATUS ENV

==Graphical Interface==

{{:Graphic User Interface}}

==Menu Support==

{{:Menu}}

==Keyboard Responses==

[[Image:NEWC0044.jpg]]

GRID Navigation Mode: ----------------------------------------------- 
[[Image:NEWC0046.jpg]]

GRID Edit Mode: ----------------------------------------------------- 
[[Image:NEWC0047.jpg]]

===Conditional On Datahilite===

[[Image:NEWC0048.jpg]]

===Insert Behavior===

Insert defaults to being on if datahilite is on and off if datahilite is off. It can be configured separately.

===FKEY Value:===
: 90 Page up
: 91 Page down
: 99 Escape key
: 100 Right click (Help)
: 102 Up arrow
: 103 Down Arrow
: 104 Right Arrow (in Grid)
: 105 Up Field
: 106 Down Field
: 107 Field Overflow
: 109 Right Arrow
: 112 Home Key
: 113 End Key
: 114 Field Plus (Numeric Pad)
: 115 Field Minus (Numeric Pad)
: 116 Right Arrow field exit via right arrow positions to first char of next field similar to down arrow

:
==Display Buttons==

{{:Display Buttons}}

==Mouse Response==

(only effective during INPUT operation)

FKEY has two new values 200 and 201 that may occur on a field with an X attribute. This may affect your programs. These values are returned when the mouse is used to exit a field.

Mouse Buttons can be remapped with a brconfig.sys keyboard statement.

{| border="1" cellpadding="2"
| '''|| Single Left Click '''|| Double Left Click
|-
|Without X '''||Move Cursor '''||Move and Enter
|-
|With X '''||Exit Field with 201 Fkey Value '''|| Exit Field with 202 Fkey Value
|-
|}
 
These exits imply that the cursor will resume at the field that is clicked upon.

{| border="1" cellpadding="2"
| '''||Single Right Click '''|| Double Right Click
|-
| '''||Exit the field with Fkey Value of 100 (same as help key)'''||Move to new location and Exit the 100 Fkey Value
|-
|}

==Windows Clipboard Support==

Windows Clipboard Support (Cut, Copy, and Paste)

Windows Cut and Paste

Mark a string using [[Shift+Arrow]] keys, then 
[[Ctrl+X]] to cut the string to the Windows clipboard, 
[[Ctrl+C]] to copy the string to the Windows clipboard, 
[[Ctrl+V]] to paste the string from the Windows clipboard 
([[Ctrl+A]] replaces Ctrl+C for breaking into a program.)

The above are all standard Windows keystrokes for cut & paste. Cut and Paste may be used within BR and between BR and other applications.

If a field is highlighted, paste will only paste to that field. Otherwise, BR pastes one line per field, starting with the current field and to all subsequent fields, until the last field, or last line, whichever comes first.

{{Future|A future release will support the mouse for marking text.}}

==WBTerm Compiler==

Business Rules require a [[wbterm.out]] file which is produced by the wbterm compiler release 5.1 or greater. This is due to significant changes made to the way Business Rules can access scancodes from a terminal's keyboard. All old wbterm.in files should recompile successfully, but we urge you to edit any existing wbterm.in files to use the new syntax which is available. Since older versions of the wbterm.out file will not operate on this release, your wbterm.in file must be recompiled using this release 5.1 wbterm compiler.

The old method of showing scancodes in the wbterm.in file was to specify up to two significant hex digits followed by a value indicating the number of extra characters to throw away. While this method is still supported, it is not adequate for some machines such as the IBM RT, where some significant digits were being thrown away. This method allows you to specify up to 20 significant digits.

For example, on an AIX console, the F1 key returns the following values: 1B 5B 30 30 31 71. With the old method, this scancode would be specified in the wbterm.in file as F1=5B30,3;.

With this method, the string returned by this key is specified as F1=1B5B30303171;. This method also supports special characters such as \033 for escape, thus the F1 string could also be coded as F1="\033[001q". Note that the escape value ("1B" in the first example and "\033" in the second) is included in this method string, whereas it was not with the old method.

Support for remapping alphanumeric keys has also been added. For example, if you wish to remap a particular keystroke for a wbterm.in keyword, you may use the following format: F10="+";. This example would, of course, disable the use of the + key to type the "+" character, but this syntax can be useful for inserting the actual ASCII text that a key is returning.

{\b Color=5 Spec in WBTerm}

COLOR=5 has been added to the Unix/Xenix wbterm.in file (release 1.4 or greater) to support color consoles, particularly Interactive 386/ix and AIX consoles.

To learn how this specification works, you must first understand that when COLOR=5 is specified, Business Rules will send color information to the operating system in the following escape sequence format: esc[0;3c;4c(;h)(;b)m. In this sequence, 3c represents the foreground color, 4c represents the background color, and "(;h)" and "(;b)" are optional parameters for highlight and blink. Business Rules determines the values for c, h and b by referring to the COLOR=5 spec.

The format of the COLOR=5 specification is as follows:

COLOR=5, "cccccccchb";

The 10 positions in the above quoted string correspond to the 10 display attributes in the following IBM PC color table:

0 - black 
1 - blue 
2 - green 
3 - cyan (blue+green) 
4 - red 
5 - magenta (red+blue) 
6 - brown (red+green) 
7 - white (red+blue+green) 
8 - highlight 
9 - blink

To create the COLOR=5 specification for any terminal, you must order the first eight digits according to the way in which their colors appear in the terminal's color table (this information should be available in the terminal documentation). The last two digits identify the escape character that must be sent for highlight and blink, respectively. The following specification, for instance, indicates that black (0) is the first color in the AT386 color table, red (4) is the second, green (2) is the third, and so on. The last two characters in the string identify that 1 is the code to use for highlight, and 5 is the code to use for blink.

COLOR=5, "0426153715"; ! actual AT386 entry

To display a red foreground on a black background, Business Rules would refer to the above COLOR=5 spec and note that red (4) is in the 1 position of the 10-digit string, while black (0) is in the 0 position of the 10-digit string. Therefore, it would send an escape sequence of esc[0;31;40m to the operating system. (It uses a value of 1 for the foreground c and a value of 0 for the background c values in the esc[0;3c;4c(;h)(;b)m character sequence.)

Likewise, to display a magenta foreground on a blue background with blink, Business Rules would see that magenta (5) is in the 6 position, blue (1) is in the 5 position, and that the value of the blink position is 5 in the COLOR=5 string. Therefore, it would send an escape sequence of esc[0;35;45;5m.

Some additional examples of escape sequences that Business Rules would send based on the above COLOR=5 spec for the AT386 are as follows:

esc[0;31;40;5m - red on black with blink 
esc[0;35;40m - red+blue on black 
esc[0;30;48;1m - black on white with highlight

==Setting Display attributes with PRINT HEX$==

In addition to using full screen processing, there are two ways to set the display attributes on a screen: with the PRINT HEX$("1Bxx") method and with the PRINT HEX$("Ex") method. In all cases, a PRINT [[NEWPAGE]] statement clears the screen and sets all character attributes to normal. Some display combinations may not be supported on all machines.

===Print HEX$("1Bxx")===

;Visual attributes of the display screen can be changed by executing the following statement:

PRINT HEX$("1Bxx")

In this example, xx represents the machine-dependent hexadecimal representation of the display attribute. This method is not portable between equipment types. Once such a statement is executed, Business Rules uses the specified attribute for all screen output until a new PRINT HEX$("1Bxx") statement (or a PRINT NEWPAGE) is executed. 
The bit configuration for xx on the IBM PC is as follows:

[[Image:HELP0136.jpg]]

===Print Hex$("Ex")===

PRINT HEX$("Ex") 
Another method of setting visual attributes of the display screen is to execute the statement PRINT HEX$("Ex"), where x is:

{|border=1
|0||normal screen
|-
|1||underline
|-
|2||blink 
|-
|3||invisible
|-
|4||highlight
|-
|5||highlight underline
|-
|6||highlight blink
|-
|7||highlight blink underline
|-
|8||reverse
|-
|9||reverse underline
|-
|A||reverse blink
|-
|B||reverse blink underline
|-
|C||reverse highlight
|-
|D||reverse highlight underline
|-
|E||reverse highlight blink
|-
|F||reverse highlight blink underline
|}

Once the PRINT HEX$("Ex") statement is executed, Business Rules uses the specified attribute for all screen output until a new PRINT HEX$("Ex") statement (or a PRINT NEWPAGE) is encountered. 
This method is not fully portable between equipment types -especially A to F.

===Icon===
SETENV("ICON","myicon.ico") sets the icon for the window and the taskbar to the icon specified by the second parameter (e.g. myicon).

===Graphical Console===

A new keyword, FONTS, has been added to the STATUS command that lists installed fonts that are suitable for use with BR.

The OPEN #0: string can contain the keyword MAXIMIZE or NOMAXIMIZE which will override the user's INI settings. If not specified, the "Save Font Size And Position" settings will govern.

{\b COMBO BOX GRAPHIC AND HOT TEXT}

PRINT FIELDS "row, col, C 10, Q,X02": "Box Caption" will place a graphic combo box down arrow graphic to the right of the field. When the field is double clicked, a HEX 02 keyboard character is generated. The X02 could also be a four digit hex value (X5044) or a function key number (14).

==KEYBOARD CHANGES==

The significance of certain keyboard characters has been revised:
* = changed 
^ = with control key pressed

^A - break ( this was ^C ) 
^B - page up (back) 
^C - copy to clipboard 
^D - delete 
^E - end field 
^F - page down (forward) 
^G - backtab 
^H - backspace 
^I - tab 
^J - next field 
^K - prior field 
^L - right arrow 
^M - enter 
^N - left arrow 
^O - field minus 
^P - print screen 
^Q - toggle insert mode 
^R - up field (rise) 
^S - toggle hold mode (stop) 
* ^T - down field ( this once was ^V ) 
^U - field plus 
^V - paste clipboard content 
^W - home 
^X - cut to clipboard 
* ^Y - was REPAINT SCREEN in Unix - now HELP (back where it was) 
unchanged in Windows - still HELP 
^Z - restore field 
^[ - escape 
^\ - toggle translation of numerics to linedraw characters 
* ^- - REPAINT SCREEN ( this once was ^X ) 
use the minus key on the top row of the keyboard 
along with the control key

INPUT SELECT now displays lines like PRINT FIELDS.

==Label Alignment==

[[Image:NEWC0001.jpg]]

Labels (captions) displayed are analyzed for spacing. If more than one blank is found or line draw or underline characters are encountered (denoting a text field), a new control is delineated, which means that the label is split in two or more pieces.

When such individual controls (label segments) are delineated the last non-whitespace character of each subfield is checked for a colon. If it is a colon the text is right justified within the subfield. In other words, the colon right aligns the data where it would be if fixed width fonts were used.

The name of this example is: DELINEAT.BR

00100 PRINT FIELDS "1,1,C 10" : "one two" ! treated as a single label (one space in between)
00200 PRINT FIELDS "2,1,C 10" : "one two" ! treated as two separate labels (three spaces)
00300 PRINT FIELDS "3,1,C 10" : "one: two" ! treated as two separate labels (two spaces)!:! label "one" will be right justified in a 4 position subfield
00400 PRINT FIELDS "4,1,C 10" : "one two:" ! treated as two separate labels (three spaces)!:! label "two" will be right justified

;Output:

[[Image:NEWC0002.jpg]]

In the output of line 200 in the above example, "two" is left aligned where it would be if a fixed font were used.

Proportional font characters have varying widths.

In the following example, when a proportional font is used, the word "row" looks longer than the word "big" and the word "bit", but the words "column", "object", and "locate" will still line up with each other when printed to the graphical console. This is because positioning and sizing of controls on the window are managed by simulating fixed character positions.

The name of this example is: PROPFONT.BR

00100 PRINT FIELDS "1,1,C 30": "Row Column"
00200 PRINT FIELDS "2,1,C 30": "Big Object"
00300 PRINT FIELDS "3,1,C 30": "Bit Locate"

;Output:

[[Image:NEWC0003.jpg]]

If proportional fonts are turned off by executing CONFIG GUI OFF, then each letter will be exactly the same height and width as all other letters. The above example will then produce the following output:

[[Image:NEWC0004.jpg]]

If a CHR$(5) character is encountered with proportional fonts on, it is replaced by a blank and a control boundary is delineated. Delineating a new control implies continuing output at the position where it would be if the window were using fixed fonts. In other words, using CHR$(5) simulates fixed character positions and makes label "iiii" and label "wwww" have the same width.

The name of this example is: CHR5.BR

00100 PRINT FIELDS "1,1,C 10": "iiii wwww"
00200 PRINT FIELDS "2,1,C 10": "iiii"&CHR$(5)&"wwww"

;Output:
[[Image:NEWC0005.jpg]]

One of the disappointments in moving to a GUI presentation is that text selection via DATAHILITE overrides the ATTR value. ATTR still applies to the current field (where the cursor is) once the data is deselected. But the color of selected text is necessarily determined by the operating environment. If you want to override the color of the current field immediately upon entry, then you will have to turn DATAHILITE OFF, so the text will not be selected upon entry. So, if the ATTR specification is to be honored, then the new GUI should be run with DATAHILITE OFF.

The new GUI mode does not permit bleed through the way the old console does. That is, anything written to an underlying window is not seen until the overlaying window is removed. However, a capability called FORCE VISIBILITY (described in a separate section) overcomes this limitation for programs designed for the old BR console.

If a text field is written to a window that already has an overlapping text field, then the text field, which it overlaps (the original text field on the screen) is automatically deleted.

The name of this example is: OVERLAP.BR

00100 PRINT FIELDS "1,1,C 5,,B20": "ooooo" ! this button will be automatically deleted
00200 PRINT FIELDS "1,5,C 2,,B40": "xx" ! this button overlaps the first one and causes the first field to be deleted

;Output:
[[Image:NEWC0006.jpg]]

There are a couple of exceptions to this:

:1.) Labels printed to a window using a proportional font can sometimes extend beyond the area that they would occupy as a fixed width font. When this happens, BR extends the control (text space) to the necessary length. If another label is subsequently displayed in this extended area, then it is positioned under the previous label extension. If a non-label is printed in this extended area, it is positioned over the label extension.

The name of this example is: OVERLAP2.BR

00100 PRINT FIELDS "1,1,C 8" : "SSSSSSSS" ! label
00200 PRINT FIELDS "1,9,C 4": "oooo" ! this label is positioned under the previous label
00300 PRINT
FIELDS "2,1,C 8" : "SSSSSSSS" ! label
00400 PRINT FIELDS "2,9,C 4,,B5": "oooo" ! this button is positioned over the previous label

;Output:
[[Image:NEWC0007.jpg]]

:2.) If a control is displayed over the top of a label's fixed character space, the original label is truncated by the new control using fixed width font logic. Each resulting segment is handled independently, as if it were a separate field.

The name of this example is: OVERLAP3.BR

00100 PRINT FIELDS "1,1,C 8": "abcdefgh" ! this label is 8 character long
00200 INPUT FIELDS "1,1,C 4": VAR$ ! this control is over the top of the previous label's fixed character space and causes the label to be separated into two pieces

;Output:
[[Image:NEWC0008.jpg]]

==New Features-==

===Inactive Fields===
Normal windows behavior is to dim inactive fields. This can be overridden with the [inactive] attribute, which refers to inactive graphical controls. The attribute names are not case sensitive.

e.g. CONFIG ATTRIBUTE [inactive]/#112233:#445566

===Menu improvements===
The way menus are displayed has been improved with respect to speed and appearance. The R (retain) menu flag is now honored.

===Hot Controls - Focus===
Any control with an FKEY associated with it via the PRINT FIELDS statement will remain hot at all times, irrespective of whether it is participating in an INPUT FIELDS operation.

[NEWCELL(icells3l.spc)]
===Paste behavior and Navigation Keys===
;Paste behavior
{| border="1" cellpadding="2"
|Action'''||Old'''||New'''||
|-
|Ctrl-V'''||paste goes into multiple fields at line endings'''||the current field gets the data it can take'''||
|-
|left/right arrows '''||cause a field exit at beginning and end of field '''||arrow keys stop at end of field'''||
|-
|up/down arrows'''||prior/next field'''||the same as left and right'''||
|-
|}
;Navigation Keys
{| border="1" cellpadding="2"
|Action'''||Old'''||New'''||
|-
|up/down'''||up/down cell'''||up/down cell'''||
|-
|left/right'''||left/right cell'''||left/right cell'''||
|-
|Home/End in GRID'''||get focus '''||set cursor'''||
|-
|left/right'''||cause a field exit at '''||'''||arrow keys stop at end of field'''||
|-
|}
===Data entry in a Grid===

==INTERNAL PROCESSING CHANGES==
===WSID 0 No longer allowed===

WSID 0 is no longer allowed. The priority of WSID assignment is:
:1.) Command line WSID requests take precedence over brconfig.sys WSID statements.
:2.) Of the brconfig.sys WSID statements, the last one specified is used.

==NEW AND EXTENDED FEATURES==

The I field attribute represents invisible. Under Windows it is now treated as a password field. Most typically it is displayed as a string of asterisks (e.g. *****).

Long filenames may now be up to 512 characters in length.

===Clipboard Access===

{{:Clipboard}}

==New Status Commands==
[NEWCELL(icells1l.spc)]

===STATUS and Partial Filename===

BR now supports partial filenames on the STATUS FILES and STATUS LOCKS commands:
[NEWCELL(icells1l.spc)]

==BUG FIXES==
The text portion of Combo Boxes can now be used as ordinary FIELDS as in:

01010 INPUT FIELDS "5,10, C 12; 7,10,COMBO 15; 9,10,C 8": MAT DATA$

Formerly, the statement had to read:

01010 INPUT FIELDS "5,10, C 12; 7,10,COMBO 15; 9,10,C 8": DATA$(1),DATA$(2),DATA$(3)

DIM statements were not being reinitialized prior to Save and Replace operations. This caused arrays to be corrupted when they were redimensioned in a library routine prior to replacing a program. This was an ancient bug.

[[Category:Basics]]

Rewrite

2026-02-23T03:01:38Z

Gordon.dye:

The '''ReWrite''' (REW) [[statement]] updates an existing record in an internal or external file.

===Comments and Examples===
Before ReWrite can be used, an [[internal]] or [[external]] file must already be [[open]]ed and assigned a [[file number]]. ReWrite can be used with internal files opened for either [[SEQUENTIAL]],[[RELATIVE]] or [[KEYED]] processing. ReWrite can be used with external files opened for SEQUENTIAL or RELATIVE processing. ReWrite operates only when files are opened [[OUTIN]]. ReWrite must follow a successful [[READ]] or [[REREAD]] when used with a SEQUENTIAL file, when used without a [[REC=]] clause or [[POS=]] clause for RELATIVE files, and when used without a [[KEY]] clause for KEYED files. In each of these three cases, the record updated will be the last record read.

The following example is an excerpt from a program which rewrites the changed values of a [[GRID]]. REWRITE functions like WRITE, except the record already exists:

00300 RECFORM: form C 30,C 30,C 30,C 15,C 2,C 7,C 1,N 1,N 1,N 1
...
00880 for Index=1 to Udim(Mat Firstname$)
00890 let Thesubscriptnumber=Subscr(Index)
00900 let Therecordnumber=Recordnum(Thesubscriptnumber)
00910 rewrite #1, using RECFORM, rec=Therecordnumber: Firstname$(Index), Lastname$(Index), Address$(Index), City$(Index), State$(Index), Zipcodes$(Index), Shipmethod$(Index), Item1(Index), Item2(Index), Item3(Index)
00920 next Index
...

===Syntax===
REWRITE #<[[file number]]> [, [[USING]] {<[[string expression]]>|<[[line ref]]>}] {[, [[Pos Parameter|POS]]=<[[numeric expression]]>]|[, [[REC=]]<[[numeric expression]]>]|[, [[KEY]]=<[[string expression]]>]} [, {[[RESERVE]]|[[RELEASE]]}] : [{[[Mat]] <[[array name]]>|<data item>}][,...] [<[[error condition]]> <[[line ref]]>][,...]
[[Image:Rewrite.png|900px]]

===Defaults===
# Unformatted.
# Write over the last record read.
# Rewrite the current record and unlock all locked records for this file.
# Interrupt the program if an error occurs and "ON error" is not active.

===Parameters===
"File-num" is an integer or numeric expression; it matches a REWRITE statement to a file of the same number that has already been identified in an OPEN statement.

The "USING" keyword is part of a clause that specifies either the "line-ref" of a [[FORM]] statement or a "string-expr" containing a FORM statement.

The "POS = num-expr" clause is used only with external files opened for RELATIVE processing; its purpose is to position to a specified byte before rewriting. After the numeric expression is evaluated and rounded to an integer, the system reads a complete record beginning at the specified byte number.

The "REC = num-expr" parameter is used with internal files opened for RELATIVE or KEYED processing, or with external files opened for RELATIVE access; its purpose is to specify a record by record number. After the numeric expression (usually a simple numeric variable or constant) is evaluated and rounded to an integer, the system reads and then rewrites that record number.

The "KEY = string-expr" clause is used with files opened for KEYED processing; its purpose is to specify a record by the value of its key field. After the string expression is evaluated, the system reads and then rewrites the first record that matches the key field. For complete information about the KEY clause, see the Index Facility chapter.

The "RESERVE" and "RELEASE" parameters specify record locking rules for multi-user systems. "RESERVE" instructs the system to preserve all previous record locks. "RELEASE" releases all record locks on this file as soon as the REWRITE is complete.

The "MAT array-name" and "data-item" parameters represent a list of items to be written to the old record. If more than one is specified, they must be separated by commas.

REWRITE allows error processing with the optional "error-cond line-ref" parameter. See [[Error Conditions]] for more information.

===Technical Considerations===
# Relevant error conditions are: [[CONV]], [[ERROR]], [[EXIT]], [[IOERR]], [[LOCKED]], [[NOKEY]], [[NOREC]], and [[SOFLOW]].
# On multi-user systems, the record being rewritten must be locked or an error [[0062]] (record not locked) will result.
# If a "string-expr" is used with a USING clause, it must begin with "FORM ". This technique executes relatively slowly because the string is compiled on each execution of the REWRITE statement.
# Omitting the USING clause allows unformatted file I/O. See [[File I/O]] for more information.
# Unspecified positions in the record (e.g., skipped over by POS n or X n) remain unchanged.
# With RELATIVE processing, the REWRITE is not affected by the previous I/O statement when a REC= clause or POS= clause is used. An implied READ REC= is performed before the REWRITE.
# In a file opened for KEYED processing, it is possible to rewrite records by record number without disturbing the key position in the file. Using the record number for access is much faster than using a key. One caution is that you should not use REWRITE REC= if you have changed one or more key fields in a record. Since REWRITE REC= has no effect on the key files, a changed key field would prevent the key file from matching the master file.
# With KEYED processing, the REWRITE is not affected by the previous I/O statement when a KEY clause is used. An implied READ KEY= is performed before the REWRITE.
# "KEY=" is the only form allowed when REWRITE is used with a KEY clause. "KEY>=", "SEARCH=", and "SEARCH>=" matches are not allowed because their results (partial and "next greater" matches) are unpredictable.
# No error results when a REWRITE statement tries to change the key field. The fields used for other keys can also be changed when multiple index files are being maintained, and the index files will be updated automatically. For more information about multiple index files, see the Index Facility chapter.
# When OPTION INVP is in effect, the normal output of commas and periods is interchanged in PIC, N, NZ, G and GZ format specifications to produce European-style numbers. See the [[OPTION]] statement for details.
# When REWRITING REC=, or just REWRITE after a READ REC=, to a file with indexes open, the indexes will be maintained. Previously REC= processing ignored indexes on a rewrite. A consequence of this is the undetectability of multiple opens input noshr. However, this poses no jeopardy to data. Any open requesting write permissions will not be allowed while the file is opened input noshr, and no input noshr will be allowed while the file is opened for writing, but two opens input noshr MAY be allowed on the same file at the same time. In other words in this case sharing is not blocked.

<noinclude>
[[Category:Statements]]
[[Category:File Processing Statements]]
</noinclude>

Opening a Print File

2026-02-21T19:59:06Z

Gordon.dye:

A print file or printer direction is a DISPLAY FILE (see [[:Category:File Operations]]). The default length for a record of a display file is 132 characters, this can be changed in the open statement to be as large as 32,000. A record written to a display file by default is right trimmed and followed by a line ending sequence that is dependent upon the operating system. For example, a Windows system will append a carriage return and a line feed. The right trim of a display file record can be overridden by setting an option (see [[Option (Config)|OPTION]]) only if the EOL code is changed to NONE.

Opening a display file with the number 255: uses the default BR printer configuration unless other parameters are specified in the open string.

00100 open #255:"name=PRN:WORD/\\\server1\\HP4,recl=32000,eol=NONE", display,output

The above line will open a printer that utilizes the BR SPOOLCMD functionality IF SPOOLCMD has been specified in the BRCONFIG.SYS file. The string "WORD" will be passed to the spoolcommand function in the position of the PRINTQUEUE parameter, no end of line characters will be added at the end of each line, all lines will be trimmed of any space characters between the last non-space and the end of the line, no line will be wrapped unless it exceeds 32,000 characters (Note that because the EOL is set to NONE there will never be any effective line wrapping.)

:1.) Opening a display file with {\b Name=WIN:/nn} does the same thing as PRN:/nn except the use of SPOOLCMD is suppressed only for that file and the print job is directed to the Windows print driver for the named printer.

:2.) Opening a display file with {\b Name=DIRECT:/nn} does the same thing as PRN:/nn except the use of SPOOLCMD is suppressed only for that file and the print job is directed to port specified by the Windows print driver for the named printer without having the output processed by the print driver.

3.) Opening a display file with {\b Name=PREVIEW:/nn} does the same thing as WIN:/nn except the print output is displayed as a preview after being processed by the printer driver, but before being sent to the named printer. See [[NWP]] only print codes for acceptable escape sequences for WIN and PREVIEW (NWP) mode.

If EOL is not set to NONE and it is desired that the print file, or display file, NOT be right trimmed then the file should not be opened as a display file, but rather as an EXTERNAL file (see [[:Category:File Operations]]). If using an external file and EOL should be Carriage Return and Line Feed then the record length of the external file should be set a two characters longer than the desired record length and the last two positions of each line should be written with these characters (CHR$(13)&CHR$(10)).

<noinclude>
[[Category:Printing]]
</noinclude>

Field Specs

2026-02-19T05:54:47Z

Gordon.dye:

The following syntax may be inserted where the "field- spec" parameter appears in the main diagram for full screen processing statements, including [[INPUT FIELDS]], [[INPUT SELECT]], [[RINPUT FIELDS]], [[RINPUT SELECT]].

===Syntax===
<row>, <column>, {<[[numeric form spec]]>|<[[string form spec]]>|<[[PIC]](<pic spec>}[<field length>] [.<fraction length>] [, <[[attributes]]>] [;...]

[[file:Fieldspec.png|800px]]

===Defaults===
:1) Fraction length = 0.
:2) Maximum DIM length.
:3) Use current attributes.

===Parameters===
If the "string-expr" or "MAT string-array" parameters are used to specify the Field Spec definition, each must include the same elements identified below:

The "row" parameter is a required integer value that indicates the row number on the screen or in the window where the data is to be entered.

The "column" parameter is a required integer value that indicates the starting column number on the screen where data is to be entered.

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

The next set of parameters specifies the format type of the data to be entered. There are three possible routes.
In the top route, "num form-spec" represents a numeric format specification. G, GL, GU, GZ, L, N, and NZ are all valid in this position; the specification must be followed by a space. The "field-length" parameter, which is an integer value that identifies the length (including decimal point and decimal positions) of the field, comes next. If the field contains decimal positions, "fraction" should identify how many there are; this parameter must be separated from the field length by a period (no spaces).

In the middle route, "string form-spec" represents a string format specification. C, CC, CR, CL, CU, G, GL, GU, GZ, V, VL and VU are all valid in this position. If "field length" is used, it must be separated from the format spec by a space. As of 4.3 #G can be used to process numeric data from a string.

In the bottom route, the "PIC" specification allows you to specify a picture of the field to be input. See [[PIC]] for a list of the characters that may be used in the "(pic-spec)" portion of this parameter. [[FMT]] can also be used in this place.

A special string format specification called [[Picture|PICTURE]] ''rows/cols'' is also valid where string field specifications are permitted.

In the place of PIC, #[[PIC]], #[[FMT]] or [[Text]] could be used. #PIC and #FMT allow numeric data from a string to be used, while Text forms a text box for input (as of 4.3).

See [[Field specifications]] and [[Format specifications]] for additional information about all the format specifications listed in this section.

The "attributes" parameter represents an insertable syntax that identifies the appearance and control attributes that are to be used for the field. See [[Attribute (Screen)]] for details. Additionally, fonts can be controlled at the field level by assigning them to attribute substitution letters as in:

CONFIG ATTRIBUTE [J],font=ariel:slant:max

This specifies ariel italics maximum size.

<noinclude>
[[Category:Definitions]]
[[Category:All Parameters]]
[[Category:Field Specifications]]
</noinclude>

Days

2026-02-18T17:16:53Z

Gordon.dye:

DAYS (<date>[,<format$>])

'''DAYS''' [[internal function]] returns the absolute, sequential value which is assigned to dates beginning January 1, 1900.

BaseYear is used to determine the century for a date if the format specification used does not specify a century. See [[BaseYear]] in the [[BRConfig.sys]] specifications section for complete information.

===Comments and Examples===
The Days function returns the specified date as a sequential value in relation to a base date of January 1, 1900. As an example of using this parameter for date arithmetic, line 300 would print "PAST DUE" if the date of an invoice '''IDATE''' is over 30 days from the current date.

00030 IF Days(DATE)>Days(IDATE)+30 THEN PRINT "Past Due"

The DAYS function can now be used to store and perform date arithmetic on dates beginning with year 1700. Negative numbers are used to denote such dates.

Notice that the number of days in a month, leap year, etc. do not have to be coded in your program because they are built into this function.

If the numeric date parameter is invalid, the Days function will return zero. Therefore, the Days function can also be used to check the validity of dates entered from the keyboard. For example,

00010 LET DATE$("*y/m/d") ! be sure default format is year/month/day
00020 LET M$="14" ! month is invalid
00030 LET D$="31"
00040 LET Y$="88"
00050 LET D=VAL(Y$&M$&D$) ! D = 881431
00060 PRINT Days(D) ! invalid date = 0
00070 LET M$="12" ! month is valid
00080 LET D=VAL(Y$&M$&D$) ! D = 881231
00090 PRINT Days(D) ! valid date = 32507
00095 LET DATE$("*m/d/y") ! change default format to month/day/year
00096 PRINT Days(D) ! invalid date = 0 (does not fit format)

The value of D in line 96 is invalid because line 95 changes the default format for dates (note the * at the start of the date string). The optional second parameter of the Days function can be used to temporarily change the date format. Line 97 will print a nonzero value because the date is valid in the format specified in the optional string parameter.

00097 PRINT Days(D,"y/m/d") ! valid date = 32507
00098 PRINT Days(D) ! invalid date = 0 (does not fit format specified in line 95)

Line 98 returns zero because the format in line 97 only applies to that one function call. Since there is no asterisk in the date string, line 97 does not change the default date format, whereas line 95 does.

===Parameters===
The "date" parameter is a numeric expression that represents the date for which the number of days should be calculated. If "date" is not valid according to the current default format, Days will return 0.

The optional "format$" parameter is a string expression which identifies the format of the value to be returned. When the first character of the string expression includes an asterisk (*), it identifies the default format which should be used by the Date, Date$ and Days parameters until the workstation exits Business Rules or until the format is changed again. Format changes affect the current workstation only.

The format$ parameter may include separating characters and any of the following date specifications: D (day), M (month), Y (year) or C (century). The total number of separating characters and date specifications may not exceed 6. Consecutive repetitions (DDD, YY, etc.) of the date specifications count as just one specification, but consecutive repetitions of separating characters do not use this rule. See the Date$ function for additional information about format$.

===Handling Input===
(4.2+) BR does not require that the entered value conform to the specified mask to avoid the entry of incorrect dates using unforeseen valid expressions. If a date format mask omits month, day, year and/or century, BR assumes the first day of the current month for the respective omitted mask components. Values must conform to masks with the following exceptions:

* Any valid format for month or day is accepted on input where the mask requests the respective month or day.
* Any valid separator will be accepted where any separator is specified by the mask.

Otherwise, BR requires that the entered value conform to the specified mask to
avoid the entry of incorrect dates using unforeseen valid expressions.

Examples:
days("Tuesday 23 January, 2007",'day dd month, ccyy') -> 39104
days("January, 2007",'day dd month, ccyy') -> 39082 (day 1 assumed)
days("Tuesday 23 Jan; 07",'day dd m3, yy') -> 39104 (note mm yy separator)
days("Tuesday 23 Jan/ 07",'day dd m3, yy') -> 39104
days("Tuesday 23 Jan; 07",'day dd m3, yy') -> 39104
days("Tuesday 23 Jan- 07",'day dd m3, yy') -> 39104
days("23 Jan;",'dd m3,') -> 40200 (current year and century)

BR allows a null mask, but the omission of a mask does not denote a null mask. It denotes whatever the system default mask is currently set to, which could be the system default.

*As of 4.3, numeric variables can now represent time of day in the fractional space (to the right of the decimal point) to include the following:
H#.## or H denotes hours (with fractions).
M#.### or M#.# denotes minutes.
S#.####, S or S# denotes seconds.
M, to the right of H always denotes minutes, so H:M:S is sufficient.
Either AM or PM, to the right of H denotes AM / PM output.
The absence of AM and PM denote military hours (0 – 23).
The maximum significant digits that can be represented in a numeric variable are 15. So if century, year, month and day are stored as a 5 digit day of century, then internally up to ten digits to the right of the decimal are available for time of day.

Examples:
DAYS("7/13/15 03:10:57 AM","M/D/Y H:M:S AM") -> 42197.1326042
DAYS("03:10:57 AM","H:M:S AM") -> 42185.1326042
DAYS("7/13/15 03.1825","M/D/Y H#.####") -> 42197.1326042
Notes:
* When using H:M:S, the time Component must be HH:MM:SS, so for example 3:10:57 PM will not work properly
* When providing a time without a date, the function will return the days value for the 1st day of THIS month. In the Above examples, the date was 7/13/15
* When using H#.#### the Hours must be 2 Digits "03" not "3", and the # of decimals must at least match the mask provided.

===Saving Dates===
When storing date/time combinations in a data file, you should allow for all of the significant digits that your date mask supports on each side of the decimal point. A “BH 4.4” form supports nine significant digits, which is suitable for day of century plus a four digit fraction. To exceed that you can use either PD 6.6, PD 7.6, PD 8.6 or D 8 (double floating point) to store these values. Note that BR rounds internally at six digits by default.

===Related Functions===

See also [[Date$]] and [[Date]] for other date processing functions.

<noinclude>
[[Category:Internal Functions]]
</noinclude>

Insert (config)

2025-09-15T04:39:45Z

Gordon.dye:

The '''Insert''' [[BRConfig.sys]] specification:

When the cursor enters a field the ''overtype/insert'' setting can be controlled by the INSERT statement. The syntax of this statement is:

CONFIG INSERT ON | OFF [MIN_LENGTH <0-99>]|[NON_PERSISTENT]|[SESSION_PERSISTENT]|[PERSISTENT]

====INSERT Configuration Statement Parameters====
INSERT ON | OFF - sets mode to Insert or Overtype 
INSERT MIN_LENGTH 10 - regulates separate long and short insert settings. MIN_LENGTH denotes that INSERT should be ON if the field capacity equals or exceeds the specified numeric value. 
INSERT [ON|OFF] NON_PERSISTENT - resets to specified setting upon field exit 
INSERT [ON|OFF] SESSION_PERSISTENT - resets at the beginning of each BR invocation 
INSERT [ON|OFF] PERSISTENT - user setting persists across BR invocations 

The default mode is ON PERSISTENT. 
HOWEVER the default setting action is overridden by the [[DataHilite]] configuration statement action. Datahilite causes the content of a field to be hilighted and if the user just starts typing it clears the field before displaying the typed value.

This statement can also be set using the [[Config]] command, or from within the program using the [[execute]] statement.

<noinclude>
[[Category:Config]]
</noinclude>

Delete (command)

2024-11-19T16:51:45Z

Gordon.dye: /* Parameters */

The '''Del (DE)''' [[command]] deletes one or more lines from the program currently loaded in memory.

==Comments and Examples==
At least one line number must follow the DEL command. The system will delete the specified line or, if two line numbers are indicated, it will delete both lines and all lines in between.

The following example deletes lines 30-70:

DEL 30 70

==Syntax==
DEL <first line number> [<last line number>] [SOURCE]
[[Image:Del.png]]

==Defaults==
:1) Delete only the specified line.

==Parameters==
DEL requires the '''1st line number''' parameter, which is either the single line number you wish to delete, or the first line number of a range of lines you wish to delete.

To delete a range of lines you must also use the '''last line number''' parameter. This is the number of the last line you wish to delete.

The following parameter is useful for enforcing security:

SOURCE allows you to delete source code without deleting the object (executable) code. This lets you hide sections of your program for security purposes. However, once this is done the program cannot be reloaded from source because the source is misssing. So always keep a separate copy of the full original source.

==Technical Considerations==

To open up all the storage space that deleted lines take up, save the file in source and reload it. This allows you to reclaim approximately 100 bytes of object code for every seven deleted lines.

<noinclude>
[[Category:Commands]]
[[Category:Editing Commands]]
</noinclude>

Delete (command)

2024-11-19T16:39:43Z

Gordon.dye: /* Syntax */

The '''Del (DE)''' [[command]] deletes one or more lines from the program currently loaded in memory.

==Comments and Examples==
At least one line number must follow the DEL command. The system will delete the specified line or, if two line numbers are indicated, it will delete both lines and all lines in between.

The following example deletes lines 30-70:

DEL 30 70

==Syntax==
DEL <first line number> [<last line number>] [SOURCE]
[[Image:Del.png]]

==Defaults==
:1) Delete only the specified line.

==Parameters==
DEL requires the '''1st line number''' parameter, which is either the single line number you wish to delete, or the first line number of a range of lines you wish to delete.

To delete a range of lines you must also use the '''last line number''' parameter. This is the number of the last line you wish to delete.

==Technical Considerations==

To open up all the storage space that deleted lines take up, save the file in source and reload it. This allows you to reclaim approximately 100 bytes of object code for every seven deleted lines.

<noinclude>
[[Category:Commands]]
[[Category:Editing Commands]]
</noinclude>

Do

2024-10-06T11:29:21Z

Gordon.dye:

See also [[DO LOOP]] and [[Exit Do]].

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.

===Syntax===
DO [{WHILE|UNTIL} <[[conditional expression]]>]
[[Image:Do.png]]

===Defaults===
# When no WHILE or UNTIL condition is specified, execute.
# Loop until the corresponding LOOP statement's conditions are met, or an EXIT DO statement is encountered.

===Parameters===
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.

CONFIG STYLE INDENT will cause lines between the DO and LOOP statements to be indented.

===Note===
I you need to execute a group of stements once irrespective of the loop terminating condition, don't specify a condition on the DO statement and instead place it on the LOOP statement.

===Example===
This do loop waits for [[Check Box]]es to be selected before the operator pushes a "Done" [[Print Fields Buttons|Button]]. (The button sets the Fkey to 99, thereby exiting the loop.

00350 do
00360 input fields "22,14,CHECK 8,,10;23,14,CHECK 8,,11;24,14,CHECK 8,,12": Box$(1),Box$(2),Box$(3)
00370 print fields "24,1,N 2": Fkey
00380 loop While Fkey~=99

<noinclude>
[[Category:Statements]]
[[Category:Loop Statements]]
</noinclude>

Do

2024-10-06T11:22:01Z

Gordon.dye: /* Parameters */

See also [[DO LOOP]] and [[Exit Do]].

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.

===Syntax===
DO [{WHILE|UNTIL} <[[conditional expression]]>]
[[Image:Do.png]]

===Defaults===
# When no WHILE or UNTIL condition is specified, execute.
# Loop until the corresponding LOOP statement's conditions are met, or an EXIT DO statement is encountered.

===Parameters===
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.

CONFIG STYLE INDENT will cause lines between the DO and LOOP statements to be indented.

===Example===
This do loop waits for [[Check Box]]es to be selected before the operator pushes a "Done" [[Print Fields Buttons|Button]]. (The button sets the Fkey to 99, thereby exiting the loop.

00350 do
00360 input fields "22,14,CHECK 8,,10;23,14,CHECK 8,,11;24,14,CHECK 8,,12": Box$(1),Box$(2),Box$(3)
00370 print fields "24,1,N 2": Fkey
00380 loop While Fkey~=99

<noinclude>
[[Category:Statements]]
[[Category:Loop Statements]]
</noinclude>

Do

2024-10-06T11:14:42Z

Gordon.dye: /* Defaults */

See also [[DO LOOP]] and [[Exit Do]].

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.

===Syntax===
DO [{WHILE|UNTIL} <[[conditional expression]]>]
[[Image:Do.png]]

===Defaults===
# When no WHILE or UNTIL condition is specified, execute.
# Loop until the corresponding LOOP statement's conditions are met, or an EXIT DO statement is encountered.

===Parameters===
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.

===Example===
This do loop waits for [[Check Box]]es to be selected before the operator pushes a "Done" [[Print Fields Buttons|Button]]. (The button sets the Fkey to 99, thereby exiting the loop.

00350 do
00360 input fields "22,14,CHECK 8,,10;23,14,CHECK 8,,11;24,14,CHECK 8,,12": Box$(1),Box$(2),Box$(3)
00370 print fields "24,1,N 2": Fkey
00380 loop While Fkey~=99

<noinclude>
[[Category:Statements]]
[[Category:Loop Statements]]
</noinclude>

Copy

2024-09-28T17:29:30Z

Gordon.dye: /* Parameters */

The '''Copy (COP)''' [[command]] copies one or more files in numerous ways:
# From one directory to another on the same or different disks.
# From one place on a directory to another place on the same directory. In this case you must give the resultant copy a different name.
# From a file to a printer.
# The -S option has been added to allow copying of a file which is currently open. The file to be copied must be opened for sharing ([[Shr]] or [[ShrI]]). If it is opened [[NoShr]], a file sharing violation error [[4148]] will occur when Copy with -S is attempted.

==Comments and Examples==

When using the copy command, you may specify a drive letter or number, and a path. You may also use [[wildcard characters]] '''?''' and '''*''' in place of alphanumeric characters in file names. Redirection symbols '''>''' and '''>>''' redirect screen output to a printer, a file, or another device.

The following command copies the file SAMPLE from the default directory of a disk in drive A to the default directory of a disk in drive B. The file name remains the same:

COPY A:SAMPLE B:

The next command copies the file SAMPLE from the subdirectory \TEST1 on a disk in drive A to the subdirectory \TEST2 on the same disk. If TEST2 does not exist as a subdirectory, Business Rules names the file TEST2 and places it in the default directory on the default drive:

COPY A:\TEST1\SAMPLE A:\TEST2

The following command copies SAMPLE from one place in the subdirectory \TEST1 on a disk in drive A to another place in the same subdirectory. The copied file is renamed SAMPLE1:

COPY A:\TEST1\SAMPLE A:\TEST1\SAMPLE1

The next command copies the file SAMPLE from the default directory of a disk in drive B to a printer attached to the first parallel port:

COPY B:SAMPLE PRN:

The same file can be copied to the printer at the first serial port with the following command:

COPY B:SAMPLE AUX:

The next command copies all files with names starting with SAMPLE, a period and any extension from a disk in drive A to a disk in drive B. The '''D''' in the command causes deleted records to be removed from any of the SAMPLE files which are internal files. The '''C''' in the command causes Business Rules! to prompt for a diskette change if the disk in drive B fills up before the copying process is completed.

COPY A:SAMPLE.* B: -DC

The following example copies the internal file SAMPLE from a disk in drive A to a disk in drive B, setting the record length of the new file at 128:

COPY A:SAMPLE B: -128

As of 4.2, COPY supports copying a print file unaltered to a printer:
COPY PRT\EDITLIST.255 DIRECT:/HP4

==Syntax==
COPY <from file> {[AUX:]|[PRN:]|[<to file>]} {[>[>]<output file>]|[PRINT]} [<[[copy option|-option]]>][-...]

[[Image:Copy.png]]

==Defaults==
# Copy the file, using the current file name, into the current directory on the current drive.
# Display a log of all performed actions in the [[command console]].

==Parameters==

Copy requires the '''from file''' parameter, which provides the information necessary for identifying the file or files you wish to copy.

After the '''from file''', you may specify the optional parameter '''to file''', which is the name (and path, if required) of the file you are creating.

'''PRN:''' allows you to copy the file indicated in the '''from file''' to the printer attached to the first parallel port on DOS systems. This string must be translated with the [[SUBSTITUTE]] specification in [[BRConfig.sys]] to specify the appropriate output device on [[Linux]] systems.

'''AUX:''' copies the '''from file''' file to the printer attached to the first [[serial port]]. This string must be translated with the SUBSTITUTE specification for Business Rules! Linux versions.

In place of the '''PRN:''' or '''AUX:''' parameters, you may also specify COM1:, COM2:, LPT1:, LPT2:, etc. to indicate the port to which your printer is attached (see the drive discussion in the Definitions chapter for more information). These device references will operate properly only on Business Rules DOS versions. They may be mapped to new references with the BRConfig.sys file's SUBSTITUTE specification.

The redirection symbol in the '''>file-ref''' parameter saves messages that normally appear on the screen to the specified file. The '''PRINT''' parameter sends these same messages to the printer rather than to the screen or a file.

'''Option''' may be one or more of several optional parameters. Such option(s) can follow the copy command when separated from the rest of the command with a dash:

{|
|-valign="top"
|width="10%"|'''-A'''||tells the system to copy only files that have the archive bit on. The system turns the archive bits in the original files off when the copying process is complete. This option applies to Business Rules! [[DOS]] versions only.
|-valign="top"
|width="10%"|'''-C'''||prompts for a diskette change if the disk is full.
|-valign="top"
|width="10%"|'''-D'''||omits deleted records from the copy, but responds only when used with internal files. It is important to rebuild all related index files after using this option.
|-valign="top"
|width="10%"|'''-N'''||prevents the screen from showing a log of performed actions.
|-valign="top"
|width="10%"|'''-P'''||causes scrolling to pause after a full screen of information has been displayed. (Press <CR> for next screen.)
|-valign="top"
|width="10%"|'''-S'''||option has been added to allow copying of a file which is currently open. The file to be copied must be opened for sharing (SHR or SHRI) if it is opened NOSHR, error [[4148]] (file sharing violation) will occur when COPY with the -S is attempted.
|-valign="top"
|width="10%"|'''-V'''||requires the operator to Verify each action before Business Rules! performs it.
|-valign="top"
|width="10%"|'''-#'''||represents output file record length. Internal file record lengths are shortened or expanded (with blanks) to match the number you indicate.
|-valign="top"
|}

==Technical Considerations==
Prior to version [[3.0]] the -S switch meant preserve space. That syntax is no longer supported. -s now refers to file sharing as noted above.

COPY to a printer :DEVICE was being rejected. COPY to a PRN: or WIN: device is still illegal. (Use TYPE with redirection for PRN: and WIN:)

While the [Source] Directory is very flexible supporting *, *.* & *.*.* to include "All Files", the [Destination] Directory is less flexibe.

Examples:

Copy Source\* Destination
* This sample will copy all files to Destination - This is the preferred syntax for copy

Copy Source\* Destination\*
* This sample will copy all files to Destination but will Remove any Extension so "Sample.wb" will become "Sample"

Copy Source\* Destination\*.*
* This sample will copy all files to Destination but complex files like "Sample.wb.brs" will become "Sample.wb"

Copy Source\* Destination\*.*.*
* This sample will copy all files to Destination complex files like "Sample.wb.brs" will become "Sample.wb.brs" - Files with more "." would also be truncated.

==Client Server==

COPY filename @:filename (@ indicates Client system)

Copies filename TO client current directory

(Or specify @:pathname relative to client current directory.)

COPY @:filename filename

Copies filename FROM client current directory.

If you are trying to use [[absolute paths]] on the [[client]], specify @::

This is really most useful with [[OPEN:]] and [[SAVE:]] file selection browsers.

Use caution when using absolute paths on the client because [[permissions]] and [[file systems]] can be different from one computer to another.

Normally BR will use the [[startup directory]] to copy things and you can change this in the shortcut if needed.

<noinclude>
[[Category:Commands]]
[[Category:File Management Commands]]
</noinclude>

Copy

2024-09-28T17:27:50Z

Gordon.dye: /* Comments and Examples */

The '''Copy (COP)''' [[command]] copies one or more files in numerous ways:
# From one directory to another on the same or different disks.
# From one place on a directory to another place on the same directory. In this case you must give the resultant copy a different name.
# From a file to a printer.
# The -S option has been added to allow copying of a file which is currently open. The file to be copied must be opened for sharing ([[Shr]] or [[ShrI]]). If it is opened [[NoShr]], a file sharing violation error [[4148]] will occur when Copy with -S is attempted.

==Comments and Examples==

When using the copy command, you may specify a drive letter or number, and a path. You may also use [[wildcard characters]] '''?''' and '''*''' in place of alphanumeric characters in file names. Redirection symbols '''>''' and '''>>''' redirect screen output to a printer, a file, or another device.

The following command copies the file SAMPLE from the default directory of a disk in drive A to the default directory of a disk in drive B. The file name remains the same:

COPY A:SAMPLE B:

The next command copies the file SAMPLE from the subdirectory \TEST1 on a disk in drive A to the subdirectory \TEST2 on the same disk. If TEST2 does not exist as a subdirectory, Business Rules names the file TEST2 and places it in the default directory on the default drive:

COPY A:\TEST1\SAMPLE A:\TEST2

The following command copies SAMPLE from one place in the subdirectory \TEST1 on a disk in drive A to another place in the same subdirectory. The copied file is renamed SAMPLE1:

COPY A:\TEST1\SAMPLE A:\TEST1\SAMPLE1

The next command copies the file SAMPLE from the default directory of a disk in drive B to a printer attached to the first parallel port:

COPY B:SAMPLE PRN:

The same file can be copied to the printer at the first serial port with the following command:

COPY B:SAMPLE AUX:

The next command copies all files with names starting with SAMPLE, a period and any extension from a disk in drive A to a disk in drive B. The '''D''' in the command causes deleted records to be removed from any of the SAMPLE files which are internal files. The '''C''' in the command causes Business Rules! to prompt for a diskette change if the disk in drive B fills up before the copying process is completed.

COPY A:SAMPLE.* B: -DC

The following example copies the internal file SAMPLE from a disk in drive A to a disk in drive B, setting the record length of the new file at 128:

COPY A:SAMPLE B: -128

As of 4.2, COPY supports copying a print file unaltered to a printer:
COPY PRT\EDITLIST.255 DIRECT:/HP4

==Syntax==
COPY <from file> {[AUX:]|[PRN:]|[<to file>]} {[>[>]<output file>]|[PRINT]} [<[[copy option|-option]]>][-...]

[[Image:Copy.png]]

==Defaults==
# Copy the file, using the current file name, into the current directory on the current drive.
# Display a log of all performed actions in the [[command console]].

==Parameters==

Copy requires the '''from file''' parameter, which provides the information necessary for identifying the file or files you wish to copy.

After the '''from file''', you may specify the optional parameter '''to file''', which is the name (and path, if required) of the file you are creating.

'''PRN:''' allows you to copy the file indicated in the '''from file''' to the printer attached to the first parallel port on DOS systems. This string must be translated with the [[SUBSTITUTE]] specification in [[BRConfig.sys]] to specify the appropriate output device on [[Linux]] systems.

'''AUX:''' copies the '''from file''' file to the printer attached to the first [[serial port]]. This string must be translated with the SUBSTITUTE specification for Business Rules! Linux versions.

In place of the '''PRN:''' or '''AUX:''' parameters, you may also specify COM1:, COM2:, LPT1:, LPT2:, etc. to indicate the port to which your printer is attached (see the drive discussion in the Definitions chapter for more information). These device references will operate properly only on Business Rules DOS versions. They may be mapped to new references with the BRConfig.sys file's SUBSTITUTE specification.

The redirection symbol in the '''>file-ref''' parameter saves messages that normally appear on the screen to the specified file. The '''PRINT''' parameter sends these same messages to the printer rather than to the screen or a file.

'''Option''' may be one or more of several optional parameters. Such option(s) can follow the copy command when separated from the rest of the command with a dash:

{|
|-valign="top"
|width="10%"|'''-A'''||tells the system to copy only files that have the archive bit on. The system turns the archive bits in the original files off when the copying process is complete. This option applies to Business Rules! [[DOS]] versions only.
|-valign="top"
|width="10%"|'''-C'''||prompts for a diskette change if the disk is full.
|-valign="top"
|width="10%"|'''-D'''||omits deleted records from the copy, but responds only when used with internal files. It is important to rebuild all related index files after using this option.
|-valign="top"
|width="10%"|'''-N'''||prevents the screen from showing a log of performed actions.
|-valign="top"
|width="10%"|'''-P'''||causes scrolling to pause after a full screen of information has been displayed. (Press <CR> for next screen.)
|-valign="top"
|width="10%"|'''-S'''||option has been added to allow copying of a file which is currently open. The file to be copied must be opened for sharing (SHR or SHRI) if it is opened NOSHR, error [[4148]] (file sharing violation) will occur when COPY with the -S is attempted.
|-valign="top"
|width="10%"|'''-V'''||requires the operator to Verify each action before Business Rules! performs it.
|-valign="top"
|width="10%"|'''-#'''||represents output file record length. Internal file record lengths are shortened or expanded (with blanks) to match the number you indicate (version [[2.04]]+). When specified with other options, the record length must always be last.
|-valign="top"
|}

==Technical Considerations==
Prior to version [[3.0]] the -S switch meant preserve space. That syntax is no longer supported. -s now refers to file sharing as noted above.

COPY to a printer :DEVICE was being rejected. COPY to a PRN: or WIN: device is still illegal. (Use TYPE with redirection for PRN: and WIN:)

While the [Source] Directory is very flexible supporting *, *.* & *.*.* to include "All Files", the [Destination] Directory is less flexibe.

Examples:

Copy Source\* Destination
* This sample will copy all files to Destination - This is the preferred syntax for copy

Copy Source\* Destination\*
* This sample will copy all files to Destination but will Remove any Extension so "Sample.wb" will become "Sample"

Copy Source\* Destination\*.*
* This sample will copy all files to Destination but complex files like "Sample.wb.brs" will become "Sample.wb"

Copy Source\* Destination\*.*.*
* This sample will copy all files to Destination complex files like "Sample.wb.brs" will become "Sample.wb.brs" - Files with more "." would also be truncated.

==Client Server==

COPY filename @:filename (@ indicates Client system)

Copies filename TO client current directory

(Or specify @:pathname relative to client current directory.)

COPY @:filename filename

Copies filename FROM client current directory.

If you are trying to use [[absolute paths]] on the [[client]], specify @::

This is really most useful with [[OPEN:]] and [[SAVE:]] file selection browsers.

Use caution when using absolute paths on the client because [[permissions]] and [[file systems]] can be different from one computer to another.

Normally BR will use the [[startup directory]] to copy things and you can change this in the shortcut if needed.

<noinclude>
[[Category:Commands]]
[[Category:File Management Commands]]
</noinclude>

FileIO Library

2024-09-19T03:22:29Z

Gordon.dye: /* File Layouts */

The '''FileIO''' Library began as a project to find a way to reduce the effort associated with making changes to data file layouts. Thanks to the Fileio library, when I have to make a change to a data file layout for my customers today, I can complete the task in under 1 minute, and not a single program needs to be changed in order to continue working with the new file layout. In fact, I don’t even have to update my customer’s data files, as the FileIO library takes care of this for me as well.

The trick is to define each of your file layouts in an ASCII text file layout file that is described below. The FileIO Library will parse through your file layouts, and it will instruct your programs how to access the file data after it has been read. It will also automatically detect when you make changes to the file layout, and it will update your customer’s data files on the fly to make sure they have the latest version. Finally, it contains a DataCrawler that you can use to examine the contents of any of your BR data files in a raw format.

For more information about the FileIO Library visit the [http://www.sageax.com/products/fileio-library/ Sage AX Website]

To download the latest copy of FileIO, click [http://www.sageax.com/downloads/FileIO.zip here.]

== Method of Operation ==
The file IO library parses a formatted text file layout and uses this information to structure the opening and the reading of a file “object”. The word object here is used to refer to all the data in a given record layout in one of your files. This library is easy to use, and provided you follow some simple standards, it will simplify your life immensely.

Your programs will need to define one array for all [[Form|BR data file form statements]] and add a snippet of code (given below) to the program for interfacing with with the library. For each file you will need to define a couple of arrays and use the library to open them. From that point on access to data is simple and direct.

=== File Object Arrays ===

First, in your program you must create two arrays to store the file information. If we are dealing with the Color File these would be MAT COLOR$ and MAT COLOR. One will store all the string information about a color, and the other will store the related numeric data. Our working example will involve two files: a Color File and a Color Category File. You should dimension these as follows:

01030 DIM color$(1)*1000,color(1)
01040 DIM colorcat$(1)*1000,colorcat(1)

We're dimensioning the string array elements to 1000 bytes each. This is the length of one field in the color file. The array element length needs to be at least as big as the largest string field in the data file.

However, it is recommended to make sure the length is long enough to handle any field you might eventually add to the file at any point in the future. BR supports multi-line textboxes, so I sometimes add long memo fields to my data files that might be 400 or 800 or even 1000 characters long, therefore 1000 is the length I use now in all my new development.

But anything will work as long as its long enough to handle the largest data field in your file.

=== Forms Array ===

Your programs will need a string variable array to store the form statements associated with reading files. This form statements array will be dynamically generated or expanded whenever the a file is opened. It will say:

01020 DIM form$(1)*255

This form statement will be compiled by the FileIO open statement. BR limits all compiloed form statements to 255 bytes, so 255 is sufficient to hold the compiled Forms$ statements.

=== Library Linkage ===

You will also need the library statement:

02020 library "fileio.br": fnopenfile, fnreaddescription$

=== fnOpen Function ===

Now, add the following snippet of code to interface with the library. Note that this snippet can be copied in exactly as provided and no customization of it is needed.

Because BR libraries do not share global variables with the programs they are called from, we will need to execute a procedure file whenever we open a file - to set the names of all of our variables. Add the following snippet of code into your program. It will create an FnOpen function that calls the library and runs the proc file. The $$$ at the end of the procfile name tells the procfile to self-destruct after execution. Since this procfile is used simply to return variable information back from the library to the main program, we don’t need it sitting around collecting dust.

99010 OPEN: ! ***** Function To Call Library Openfile And Proc Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
99030 dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
99050 if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
99060 fnend

Or, for those with [[Lexi]]: (same but without line numbers)
OPEN: ! ***** Function To Call Library Openfile And Proc Subs
def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
fnend

=== Using FileIO in Your Programs ===
Now you are ready to process files. 
'''''You simply open the files by saying:'''''

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

'''''read each file as follows:'''''

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
'''''and access the data:'''''

30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name)

=== How it Works ===
The above statements tell the File Library to look in the filelay folder to find the file layout for the Color File, and read it to find out what the Color File looks like. Then it OPENs the Color File, and sets MAT COLOR$ and MAT COLOR to the correct number of elements to hold an entire color record. Finally, it will define several variables that we can use as pointers (subscripts) into these arrays to access the data read into the 2 arrays, and it will assign the file handle to a variable called "colorfile".

The second open statement above will do the same thing to the color category file, except the parameter value "1" tells the function to open readonly. The array subscripts assignment procedure file (passed back from Fileio) will be executed, thereby assigning values to the subscript names in the calling program. So, if I had a file layout such as the following:

color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

Then the functions would do the same thing as the following individual lines of code (assuming the next available file handle was 5):

DIM FORM$(5)*255
DIM COLOR$(9)*1023, COLOR(1)
OPEN #5: “Name=color.dat, kfname=color.key”,internal,outin,keyed
LET FORM$(5)=”form C 6,V 30,V 6,C 6”
LET FORM$(5)=CFORM$(FORM$(5))
LET COLORFILE=5
CO_CODE=1
CO_NAME=2
CO_CATEGORY=3
CO_HTML=4

The data is used by referencing the file array, with the subscript name, so the color’s description becomes color$(co_Name).

In the old days, if we wanted to change the file layout of our file, all of the programs that used that file would have to be changed one at a time to use the new file layout. Also, if the order of the fields changed, then all the programs would have to also be changed to use the new fields.

But now, using this function, we can change the file layout all we want. If we later want to insert a field into the file layout before color name, I won’t have to look at this program again; this program will just work fine, because the library maps the subscripts to the actual fields.

Also, the code is easier to read and maintain.

=== Example ===
The whole thing looks like this:

01025 ! Dimension the Arrays
01030 DIM color$(1)*1023,color(1)
01040 DIM colorcat$(1)*1023,colorcat(1)
01050 DIM form$(1)*255
02000 !
02020 library "fileio.br": fnopenfile, fnreaddescription$
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$) ! Open the file
05000 !
30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore ! Read the file
30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name) ! Use the data by referincing it in the file arrays
80000 !
90000 ! Every program using fileio needs the following code
99010 OPEN: ! ***** Function To Call Library Openfile And Generate Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths)
99030 dim _FileIOSubs$(1)*800
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$)
99050 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
99060 fnend

=== File Layouts ===
Now lets inspect the anatomy of a properly formatted file layout. These should be placed in a subdirectory called filelay.
In this example, a farm management system uses a price file to manage seasonal prices:

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...
<hr>
price.dat, PR_, 1

The first line contains the name of the Farm Record, a unique string to prefix all of your subscript pointers, and the file version number. The subscript prefix is to ensure that the program knows the difference between the Farm File’s Farm Code, and the Route File’s Route Code. (One will be RT_CODE and the other is FM_CODE). These are separated by a comma. Spacing does not matter, so adjust your spacing so that it looks nice.

The Version number is used to determine when the data has changed, and an update needs to be made to your data file. Your file layouts should all start at version 0, and each time you want to make a change, you may increment this value by 1.

Each time you open a file with the FILEIO library, it reads the file version number of the file on disk (using the BR version() function), and then it compares it to the version number in your file layout. If your file layout has a higher version number then your existing data file, then the library opens the backup of the file layout for the version of the data file that exists on disk. It makes a backup copy of the existing data file, and creates a new file with the proper version number. Then it reads your records one at a time, and copies all the data from the old file into the new file one field at a time. If a field is dropped from the file layout, that data gets lost. If fields are rearranged, the data is copied and saved in the new file in the new positions. If a new field is added, it starts out blank (or 0).

If you look in the filelay folder, you will notice a version folder. This contains several files ending with a number. For example you may see a color.0, and a color.1 file.

If you run the fnopen function and it can not find your data file (usually because this is a new file and it hasn’t been created yet), ''the library will automatically create your file,'' based on the information you give in the first part of the file layout.

Also, whenever you make changes to your file layout, the function library will automatically update the data files on disk for you. It does this by renaming the old file, creating a new one with the new version number, and then copying the data from the old one to the new one a record at a time.

Any time it creates a file, or updates the file on disk, it creates a backup of the file ''layout''. The first time you run a program that tries to read your new data file, it will create the data file for you and make a backup of the layout, and if the number in your file layout is 0, then it will create, for example, a filelay\version\price.0 file, a backup of your file layout that the library uses to figure out what has changed the next time you try to update the file.

If you wish to make any changes to this data file, first you increment the version number, (in this case make the 0 into a 1). Then change the file layout all you want. You may rearrange fields, add new fields, add or remove keys, or change the record length.

The only step necessary for having your data files updated is to increment the version number every time you make a change to the file layout.

You may make any changes you like to the file layouts, but do not change the names of your existing subscripts. If you change the subscript name, not only will all the programs that reference that subscript be broken, but additionally, the routine will not understand that you are changing the name. It will think you are dropping the old field and adding a new field and any data stored in this location will be lost when the file is updated.

price.key, FARM

The second line contains the name of the first key, and a definition telling what the key is based on. These are separated by a comma. The key definition is made up of each of the subscript names in this file that form the keyfields for the file. When the library is called to open a file, if the file does not exist, or if it needs to be updated, a new one will be created. The function will read these subscript names that form your key definitions, and it will calculate the proper key position (KPS=) and length (KLN=) values. Then the create routine will use this information with the Index command to create the new key files.

price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127

Notice that the third key is based on three different fields. These are separated by a “/”. It is important that you use a “/” to separate your keys when you are building a key out of more then one field, because the function uses this “/” to help it make the proper BR syntax for defining complex key fields.

Also, note the "-U" at the end of the fieldname in the 4th key. This indicates that the "Description" part of that key is case insensitive. This translates to using the "U" on part of your key spec in Business Rules.

The file can have as many keys as you want. The function will keep parsing key file names until it reaches the next part of the layout. It opens any OutIn files with all keys so that any changes you may make to the data stored on disk will be properly reflected in all the key files.

The optional RECL= Parameter is read and used whenever a new file is created or an old one is updated. If it is not specified, the record length is calculated from the fields in the layout.

===================================================

The next line in the file is skipped by the parsing routine, and its purpose is to make the file layouts more readable to a programmer.

 
FARM$, Farm Code (or blank), C 4

Following the file and key structure, the fields are defined. There are three parameters on each field definition line, and you make one line for each field in your file layout. The first parameter is the subscript name that you will use in your program to refer to this data element. Place a $ at the end of the subscript name for all string elements. Don’t place anything at the end of the subscript name for numeric elements. Note that each of these names will be prefixed by the second parameter of the very first line of this layout.

The second parameter is the description. This description is for the benefit of the programmer, so when the programmer is reading the file layouts, (s)he can tell which field does what. The spaces are ignored, so you may include as many spaces as you wish to make the layout look good. It does seem like good general guidelines would be to limit your layout lines to 255 characters and your descriptions to 80.

The description is also used by the built in DataCrawler, a program that reads any of your data files and displays the entire contents in raw form in a listview. The Descriptions become the headings for each column in the listview.

Those descriptions are also used for the default captions for your fields if you use ScreenIO, a library for building GUI programs that itself builds off of fileio.

The third parameter is the form statement, which is pretty straightforward. Any items with a form statement of type “X” will be ignored, except that the length will still be used to calculate the position on disk of all remaining fields in the record. The library will take X fields into consideration when building the form statement, but not at any other time.

The fourth parameter is optionally a [[#Support for Dates|Disk Date Format]]. You can specify DATE(Julian) if you're storing your dates in Julian format on disk. Or you can specify DATE(cymd) or DATE(ymd) or DATE(mdy) or any other valid date spec here, and FileIO will treat this field like a date.

Your programs will still have to unpack it for you, fileio can't do that because fileio doesn't read the file for you.

However, the data crawler, the automatic updates, and screenIO, are all compatible with these dates specified in your file layout.

If the fourth parameter is anything other then DATE(format), then its treated as a comment and ignored.

The fifth and all later columns, if any, are treated as comments and ignored.

! default cost is normally zero
Comment line text must begin with an exclamation point, but it may be indented. Comment lines may appear anywhere (vertically) and are ignored. 
Blank lines are ignored as well.

#eof#
additional comments...
After the last field definition, an ''optional'' #eof# line may be specified, in which case any lines after that will be ignored.

 
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...

And that’s all there is to it.

=== Support for Dates ===
As of V2.48, file layouts support dates in any storage formats on disk. Whether you store your dates in Julian or in YMD or MDY or any other format, specify so in the 4th column of your file layouts, using the FileIO Date Keyword. ex: DATE(Julian) or DATE(YMD) or any other valid BR Date Format.

[[File:Dates0.png]]

When this is specified, it enables the FileIO data exploration tool (Data Crawler) to display the dates in human readable format. This works for both Viewing, and for Editing.

The new Date functionality also supports the File Layout Upgrade facility, allowing you to change the format of your dates on disk and FileIO will handle it automatically, upgrading the field to use the new date format for you.

It works also for Exporting your data files to CSV, and is supported automatically in the FileIO functions that do those exports. It converts the dates on export to a standard format (Default: m/d/cy) that you can specify in your FileIO.Ini File.

And it extends ScreenIO's date features to all date fields, no matter what format they're stored in. (Previously, ScreenIO's advanced date features only worked for dates stored in Julian on disk.)

This update adds two new ini file options:
CODE: SELECT ALL
DateFormatExport$='m/d/cy' ! Format of Dates when Exporting to CSV
DateFormatDisplay$='m/d/cy' ! Format of Dates when displaying in Data Crawler

You can use these to specify your preferred Date format for Viewing/Editing, and your preferred Date format for Exporting.

Remember, you can see the full list of FileIO ini file options, by looking in the source code at the top of FileIO.

There is a new optional parameter for all layout reading functions, mat NDateSpec$ and mat SDateSpec$ which correspond with the other arrays, to let you know which fields are date fields, so that you can develop routines in your programs to automatically pack and unpack the dates.

Important Note: Using FileIO, the reading of the data file is still done directly in your programs. So this does not change how your existing programs work. It does not unpack the dates for you in your programs. You still have to do all that.

For this reason, upgrading to the new Date processing will not break any of your current code.

=== Debugging Tips ===

When you're making new layouts, a missing comma can cause FileIO to parse the layout wrong and give you errors. Here are a couple tips to help ensure your layouts are error free before using them in your programs.

*Use the Data Crawler to test your layout. The data crawler is the simplest way to test your new layout without writing any code. It opens it and accesses the file in a very simple and straight forward manor to help identify any errors in the layout that you might have.

*If you have trouble with the form statement, you can't see whats in it because FileIO uses CForm$ to compile your form statement to make your programs run faster. But here's a way to tell what the original form statement was that FileIO generated when it put the strings first and numbers last in your program: Open the file in the Data Crawler. When you get an error, type "Print FormStatement$" to see the original form statement.

This works even if your file is working fine. Any time the file is opened with the data crawler, you can press CTRL-A and then type PRINT FormStatement$ and it will print out the uncompiled form statement for the file.

== Utilities ==

Now that you have your file layouts defined, you have access to several powerful utilities right out of the box using Fileio. Additionally, several more utilities are available as [[#FileIO_Add-on_Packages|Add-Ons]], including our most popular development tool [[Screenio|ScreenIO]]. You can read more about them in their section below.

But for now, lets take a look at some of the wonderful free utilities that come built into Fileio.

Some of these utilities are accessible from your code via library functions, but the primary way you access any of them is by simply loading the FileIO Library and running it directly.

=== DataCrawler ===
The data crawler is the original utility of FileIO. This utility shows you first a list of all data files allowing you to select one.

Select a data file and press enter, and FileIO will then display a listview containing all the data in the data file. This list is sized based on the size of your main BR window (window 0) automatically to take up the full size available to it, so if you want to see more, try [[Open Window|opening window 0]] larger before running FileIO.

At the top of the window is a filter box, and you can type anything you want in there and click "Refresh" and it will reread the data file, shortening the list to show only those records that match (case insensitive) what you have typed.

If you have ScreenIO installed, then FileIO's data crawler will take advantage of the included Animation Engine in ScreenIO to animate a loading window while the listview is displaying. If you don't have ScreenIO then FileIO will simply load the listview.

If you don't want to wait for the entire file to load, press ESC to stop the load process.

If the file is empty, FileIO will display a message box letting you know.

This tool is very useful for sorting out data errors. It will allow you to look inside any data file you have a layout for and directly view the data there.

At the bottom of the Data Crawler are several buttons. There's a Jump button that repositions the file by a key you specify and then loads the list with the data from that key on down to the end of the file.

There is a "Columns" button which you can use to decide which columns should show up on the listview. Fewer columns means faster loading so sometimes for large files I press ESC immediately when the file first starts loading to cancel the load. Then I click "Columns" and check only the columns I want to see. Finally I press the "Refresh" button to trigger it to read the file again and this time it loads much faster then before.

Next you'll find an Export button which starts the process for exporting a file to CSV. You can read more on that in the next section. And next to that is a Quit button.

In this example, we loaded the file "Read Only" so it put everything in a listview. But there are times when its useful to fix data errors this way too, especially during development. So if you want to directly edit your data file, on the first page select the file you want to edit and instead of pressing "Enter" or clicking "View", this time press "F5". F5 is the secret Edit button that loads a data file into a grid instead.

You can use the grid to change records, delete them or add them, and in addition to the buttons listed above, it also has an "Import" button for importing a CSV file into this data file.

Any changes you make to the data file are not saved until you click the "Save" button (which also only appears when you're in Edit mode).

In the 01/2015 release of FileIO, each records rec # is displayed in the listview, to aid in debugging bad data problems.

==== Debugging Tip ====
Any time you're viewing a file layout in the Data Crawler, you can see the Uncompiled Form Statement by pressing CTRL-A to get to an ATTN prompt, and then entering the command:

print FormStatement$

and it will print out the original form statement.

==== Another Debugging Tip ====

The FileIO Datacrawler ignores records that it cannot read. This is to allow for data files that have multiple record layouts in one data file. You make a custom layout for each record type and the data crawler shows just the records that match that type in the file.

However that becomes a problem when you're making a layout to work with an existing data file. Error 726 indicates that something minor in the file layout doesn't match the data on the disk, but these errors are ignored so you might see either an empty data file, or a data file with some records missing. If that happens, you need to see the missing records in order to figure out what is wrong with your layout. '''''It's very important that you don't try to use a file layout that isn't quite working right. Make sure your layout works and can read every record of a file that it should read before using it.'''''

To see the records that could not be read in a file, run the data crawler on the layout, then press CTRL-A to get an ATTN prompt. From there, enter the command

print mat BadRead$

and it will print all the records that were ignored because the file layout didn't match them. It prints out the raw data from the file.

==== Function Access to use Data Crawler in your programs ====
You can use the data crawler in your own programs by using one of the following functions:
* [[#fnDataCrawler|fnDataCrawler]] - Open a Listview showing the data file
* [[#fnDataEdit|fnDataEdit]] - Display the data in an editable grid
* [[#fnShowData|fnShowData]] - This function does the same thing as the above two, but with many many more options allowing you to customize exactly what appears and exactly what they're allowed to change.

Note: its not recommended to allow your customers to use the data crawler to access your data files directly. There's no way to specify validations or do anything complicated, so unless you're careful, there are lots of ways your customers could use this tool to do damage to your data files. It is a programmer tool only.

If you do decide to use it for your end users, be careful how you implement it.

=== Import/Export to CSV ===

You can use FileIO to export your data files to CSV or import from CSV into your data file. To do this, you want to run the data crawler and select the file layout you're looking for. Then, view it (or press F5 to edit if you want to import something). Click on the Export button and it will ask you to select a file. Once that is selected it will ask a couple other simple questions, and when you've specified the options to your satisfaction, click the Export! button. A new CSV file will be created.

Import is even more simple. To import, you must be in Edit mode (press F5 to select the file instead of the enter key) and then simply select the Import button. It will ask you again to choose the file, and then it will ask you if it should update all files by Record Number (if record number is recorded in the CSV file) or by Key (if the file has keys) or to just Add all information to the file. Select what you want and press Import and the CSV file is added to the BR data file.

==== Function Access to Import/Export from your programs ====

You can use the following functions to call the Import and Export functionality from your code.

*[[#fnCSVImport|fnCSVImport]]
*[[#fnCSVExport|fnCSVExport]]

These functions are intended to give you the ability to use our functionality to write your own import and export routines for your customers, because its not a good idea to let your customers run the Data Crawler.

=== Generate Layout Wizard ===

There is also a Generate Layout Wizard utility in FileIO. This utility is there to help you build your file layouts. It is designed to work with a certain style of BR programming that was common in the 80s and 90s. So if your software is written in a style that opens the file directly, and reads/writes the data to a long series of individual variables, the Generate Layout Wizard is for you.

To use it, start by running FileIO. Then, don't select a layout - instead, click on the "Generate Layout" button.

You'll see a screen with a bunch of large text boxes, a small grid, and some buttons.

The first thing you want to do is select the "Browse" button and then select a .wb or .br file that contains a program that reads or writes Most of the File.

When you select one, press the Scan All button and it fileio will search the whole program looking first for all the open strings. It will take the file that is opened the most times and then search for all read statements to that file. It will look for the longest read statement and then find the Form statement associated with that Read statement, and any DIM statements for any variables used.

If you don't like the file its chosen, click the "Open Scratch Pad" button to open the temp work file it uses into the program of your choice (I use myEdit for BRS files). Simply select all the open statements for the file you DO want to build off of, then click the Paste button to paste those open statements into the "Open String" list. After that click "Clear All" to erase what it did on the first search and then click "Scan All" again to rescan the program using this new data file.

You may have to help it a bit, but once it has a proper matching open statement, read statement, form statement and dim statements for any arrays used, press the "Generate Layout" button and it will build a layout for that file.

Finally, load the layout it built and clean up anything if you want, and consider adding better descriptions for each of the fields that you know (as it will use the variable names for both the subscripts AND descriptions in the layout).

When you're all done, click "Done".

==== Functions to Generate Layouts from your code ====

* [[#fnGenerateLayout_.26_fnWriteLayout|fnGenerateLayout]]
* [[#fnGenerateLayout_.26_fnWriteLayout|fnWriteLayout]]

=== Code Templates ===

One more tool FileIO has to help is the ability to generate code based on your file layouts.

Run FileIO and this time select a file layout and press "Generate Code". A window will pop up listing all the "Code Templates" that are available. Select one (and then select a key if it asks you - some templates require extra info). It looks like nothing happened, but the code you generated is now in your clip board. Paste it somewhere and take a look at it!

Code Templates help us to standardize our ways of doing things, which eventually leads to more and more powerful tools we can use. Code Templates also help ensure we use cleaner code by doing some of the busy-work of writing clean code for us.

==== Writing Code Templates ====
FileIO ships with several basic code templates. If you want to add your own, take a look in the filelay\templates folder (configurable in fileio.ini) and look at basic.brs. Copy it to your own program and then modify it to have your own code templates in it. Write me at gabriel.bakker@gmail.com with any questions. I want to help.

And if you write good code templates, its easy to share them with the BR community. Anyone can download your templates and place them in this folder and they'll instantly be available for use.

== FileIO Function Reference ==
''The FileIO Library contains a number of other useful functions.'' The following functions are available and you are welcome to use them:

=== Primary Functions ===

==== fnOpen ====
fnOpen is the primary function that opens a file, and it’s used like so:

''def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, DontSortSubs, Path$*255, Mat Descr$, Mat FieldWidths, SupressPrompt, IgnoreErrors, SuppressLog)''

Note that all of the parameters after MAT Form$ are optional. If you need to specify a parameter in the middle of the optional parameter group, just list zeroes and empty strings for the intervening unused parameters.

*FileName$ - The filename of the file layout for the file you’re reading.
*MAT F$ - The array that will be used to hold the string data for the file.
*MAT F – The array that will hold the numeric data for the file.
*MAT Form$ - An array of form statements.
*InputOnly – 1 means open for input only. 0 means open for OutIn and open every key file associated with the given data file (this is because all key files need to be open for the keys to be updated on an output) (defaults to 0). Files opened for input process considerably faster than files opened for output. Furthermore when files are opened for input only, alternate key files are ''not'' opened.
*KeyNum – This tells the function of which key to return the file handle (defaults to 1). Specify -1 to force the file to open Relative, without using its keys. If a file has no keys, it will always be opened Relative.
*DontSortSubs – The function by default, when compiling the Form statement, will sort the string and numeric subs in order to allow for reading the data into an array, and this parameter would turn this functionality off. However, if you are trying to read your data without reading it into an array, you are missing out on some serious efficiencies. You should normally leave this option turned off (0). This is a totally unsupported feature, and should always be set to 0, if it is specified at all.
*Path$ - The path to your data files. This optional parameter can be passed in by the calling function. It is prefixed to the beginning of the paths given in the file layout files. It is useful when your data files can be in different locations depending on the state of your program.
*mat Description$ - This optional parameter provides a way to read the description for each field from the original file layout. If the parameter is not provided, no description data will be returned.
*mat Fieldwidths – This optional parameter will return an array of the calculated display field widths. This number will always be at least large enough to contain the data for this field.
*SuppressPrompt - This optional parameter can be used to suppress the prompt normally given when fileIO creates a file. It can have three values. A value of 0, the default, uses the setting stored in your FileIO fnSettings routine to determine weather or not to prompt on Creation of a new file. A nonzero value always suppresses the prompt. A value of 1 indicates never to create a file if the file doesn't exist. A value of 2 automatically creates the file if the file doesn't exist.
*IgnoreErrors - Normally when fileio opens a data file, if there are errors trying to open the file, it prints them out to the debug console and pauses so that you can try to find out whats going wrong. If you specify 1 for "IgnoreErrors" it will cause Fileio to log those errors instead, and continue loading your program. This will result in the fnOpen file function returning Zero instead of the opened file number, so if you use IgnoreErrors, you need to test to make sure that fnOpen returned a file number before you try to access the file.
*SuppressLog - this optional parameter can be used to suppress writing to the log file for this one specific open statement. I use it for files that will be opened all the time, for example, the menu data file on one of my customers systems. Without this boolean parameter, his log file is quickly filled up with useless information any time his employees look at his menu. I specify this optional parameter to suppress logging anything about the menu file so that I can more easily find the actual programs they've used when looking in the logfile.

'''''Note: When using fnOpenFile, you really want to call your local function fnOpen, which in turn calls fnOpenFile for you.''''' FnOpenFile is for internal use only.

Example:

Let FFILE=FNOPEN(“FARM”,MAT FARM$,MAT FARM,MAT FORM$,0,2)
Let RFILE=FNOPEN(“ROUTE”,MAT ROUTE$,MAT ROUTE,MAT FORM$,1,3)
Let CFILE=FNOPEN(“CUSTOMER”,MAT CUSTOMER$,MAT CUSTOMER,MAT FORM$)

assuming:
farm.dat has 3 keys: farm.ky1, farm.ky2, farm.ky3
route.dat has 4 keys: route.ky1 … route.ky4
customer.dat has 2 keys: customer.ky1, customer.ky2

This will perform the following opens and set the following variables:

OPEN #1: “Name=Farm.Dat, kfname=farm.ky2”,internal,outin,keyed
OPEN #2: “Name=Farm.Dat, kfname=farm.ky1”,internal,outin,keyed
OPEN #3: “Name=Farm.Dat, kfname=farm.ky3”,internal,outin,keyed
OPEN #4: “Name=Route.Dat, kfname=route.ky3”,internal,input,keyed
OPEN #5: “Name=Customer.Dat,kfname=customer.ky1”,internal,outin,keyed
OPEN #6: “Name=Customer.Dat,kfname=customer.ky2”,internal,outin,keyed
LET FFILE=1
LET RFILE=4
LET CFILE=5

This will also resize the arrays, set the form statement, and create all the subscripts to make accessing the data clear and simple, as in the above example. The KEYNUM parameter is where you list the key file you would like to use for reading and writing. The extra keys are opened to ensure that all keys get updated properly when the file is changed.

Example:
DIM FORM$(1),PRICE$(1)*255,PRICE(1),
DIM DESCRIPTION$(1)*80,FIELDWIDTHS(1)

Let PRICEFILE=FNOPEN(“PRICE”,MAT PRICE$,MAT PRICE,MAT FORM$,0,2,0,"",MAT DESCRIPTION$)

Assuming the Price File layout (filelay\price) contains:

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30

This will perform the following opens and set the following variables:

OPEN #1: “Name=Price.Dat, kfname=Price.ky2”,internal,outin,keyed
OPEN #2: “Name=Price.Dat, kfname=Price.ky1”,internal,outin,keyed
OPEN #3: “Name=Price.Dat, kfname=Price.ky3”,internal,outin,keyed
let PRICEFILE=1
let PR_FARM=1
let PR_ITEM=2
let PR_GRADE=3
let PR_DESCR=4
let PR_PRICE=1
let PR_COST=2
let PR_XOPRICE=3
let PR_XOCOST=4
let PR_MOPRICE=5
let PR_MOCOST=6
let PR_VOPRICE=7
let PR_VOCOST=8
MAT FORM$(1)
MAT PRICE$(4)
MAT PRICE(8)
MAT DESCRIPTION$(12)
MAT FIELDWIDTHS(12)
let FORM$(1)=CFORM$(”form C 4,C 4,C 4,POS 74,C 30,POS 50,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2”)
let Description$(1)= “Farm Code (or blank)”
let Description$(2) = “Item Code”
let Description$(3) = “Quality”
let Description$(4) = “Description of Price Rule”
let Description$(5) = “Default Price”
let Description$(6) = “Default Cost”
let Description$(7) = “Default Christmas Price”
let Description$(8) = “Default Christmas Cost”
let Description$(9) = “Default Mothers D Price”
let Description$(10) = “Default Mothers D Cost”
let Description$(11) = “Default Valentine Price”
let Description$(12) = “Default Valentine Cost”
let FieldWidths(1) = 4
let FieldWidths(2) = 4
let FieldWidths(3) = 4
let FieldWidths(4) = 30
let FieldWidths(5) = 8
let FieldWidths(6) = 8
let FieldWidths(7) = 8
let FieldWidths(8) = 8
let FieldWidths(9) = 8
let FieldWidths(10) = 8
let FieldWidths(11) = 8
let FieldWidths(12) = 8

There are a few things I’d like to point out about the example above. First, you will notice that the form statement jumps around to put all the strings first, and then the numbers last. This is why it has a “POS 74, C 30,POS 50”. Then notice that the subscripts for the string variables are 1 .. 4, and the subscripts for the numbers are 1 .. 8. Finally, the order of the Description and FieldWidth fields also match the sorted positioning of the Form Statement.

The reason that we sort our form statements is so that BR will allow us to read the file into arrays by saying:

Read #pricefile, using form$(pricefile) : mat price$, mat price

Without resorting, the above statement would give a conversion error as BR attempted to put the PR_PRICE field inside mat price$(4). However, because we have reordered the form statement, we are able to read them safely into two arrays, and then we will be able to use the values without caring what position they are in the file, by simply saying PRICE$(PR_DESCRIPTION) when we want the description, and PRICE(PR_PRICE) when we want the pr_Price field.

Another thing you may notice about the above example is that it gives the calculated display length for the numeric fields as 8, when on the disk (and in the file layout) they are listed as BH 3.2. The reason for this is the program looks at the BH 3, and figures that a number that takes up 3 bytes on disk has a potential maximum size of 256**3 or 16,777,216, and therefore will need up to 8 characters of screen display space to view.

Finally, note that any field with a form statement of X is ignored by the library, except that the blank space is used when building the FORM statement.

==== fnCloseFile ====
This function will close the specified file number and all keys that were opened with the file. The purpose of this function is to facilitate the closing of the extra keys that are opened when you open a file for OutIn with the library. There is no need to use this for files opened for input because it is easier to just close the file directly. Secondary keys are not opened by FileIO for files opened for input only.

You must give the function the name of the file layout. It uses this information to determine how many keys were opened, and how many it must therefore close.

Then it basically starts at the file number you gave it, and closes the next X files that were opened with the same file name as this, where X is the number of keys associated with this file.

The syntax is:

''fnCloseFile(filenumber,filelay$;path$)''

*FileNumber – The filenumber of the file you are trying to close.
*FileLay$ - The name of the file layout for this file. This is used to determine how many keys the file would have been opened with and therefore how many we now need to close.
*Path$ - Optional Alternate Path. Use to close files that were opened using the open file's optional alternate path parameter.

==== fnGetFileNumber ====
FnGetFileNumber is a simple function to find a valid unused file handle. If you use this function in all of your programs, they will become much more portable, as you will never have to worry about your file handles fighting with each other. The function will return 0 if no free file number was found (but with 999 of them available now, I have never seen it happen).

''fnGetFileNumber(;X,Count)''

*X – This optional parameter will specify where to start looking.
*Count - This optional parameter will specify how many file numbers to find in a row. If count is 3, then fnGetFileNumber will return the first filenumber in the first gap of three unused file numbers that it finds.

=== File Reading Helper Functions ===

These functions perform various useful calculations to aid in interacting with data files when you're using fileio.

==== fnBuildKey$ ====
This function will return the key for a given record in a data file. It actually reads the file layout and builds the key to match the layout.

''FnBuildKey$(Layout$, Mat F$, Mat F; Keynum)''

*Layout$ - the name of the data file to build the key for.
*Mat F$ - the string array of the file object
*Mat F - the numeric array of the file object
*KeyNum - This optional parameter specifies which of the key files in the given layout the key should be built for.

To use this, you want some code like in the following example:

mat customer$=("") : mat Customer=(0)
let customer$(cu_name)=CustName$
let customer$(cu_phone)=CustPhone$
read #customer, using form$(Customer), key=fnBuildKey$("customer",mat Customer$,mat Customer,2) : mat Customer$, mat Customer nokey KeyNotFound
! The above code assumes that the second key of the Customer file is based on the Name and Phone fields.

By using this logic you are able to avoid directly specifying the key in your code - which means that even if the key changes in the future, as long as your code specifies enough information, it will still find the correct key. In our example, even if we dropped the phone number from the key in the future, or even if we expand the length of the Customer Name field, our code would still work and fnBuildKey$ would still build the correct key without us having to look at or change our code again.

This kind of reasoning is central to the fileio system, which, when implemented properly, ensures that you can change your data files in any way you need to in the future, without breaking your existing programs.

==== fnUniqueKey ====
This function tests to see if a given key is unique to the specified file. This function is very useful for situations where you need to ensure that the user-entered key is unique.

''fnUniqueKey(Fl,key$*255)''

*FL – The file number of the opened file.
*Key$ - This is the key to test. If this key is the key for a preexisting record in the file, the function will return false. If this key can not be found in the file, the function will return true.

==== fnMakeUniqueKey$ ====
This function generates a unique key for a given file. This is useful if you do not care what the key is, but it needs to be unique. I use this function in situations where the user never needs to know what the given key is.

This function reads the key length for the given file. Then it returns a string that is the right length, which is generated by counting in binary until a key is found that does not appear in the file. The first key found for a 4 byte key field would be chr$(0)&chr$(0)&chr$(0)&chr$(0). If that key was already in use in the file, the function would return chr$(0)&chr$(0)&chr$(0)&chr$(1). If that one was also in use, it would then try chr$(0)&chr$(0)&chr$(0)&chr$(2), and so on until it found one that wasn’t in use.

''FnMakeUniqueKey$(fl)''

*FL – This is the file number of the opened file for the desired key.

==== fnKey$ ====
This function formats the key for the given file number. All it does is ensure the key is the correct length. You should use fnBuildKey$ instead to properly build the correct key for the record you want to read.

''FnKey$(FileNumber, Key$)''

*FileNumber - the file number we are formatting the key for
*Key$ - the key we are trying to format.

==== fnNotInFile ====
This function will determine if a non-key element in a line is unique. It works almost exactly like fnUniqueKey specified above, except that it allows you to enter the subscript value of the element you are checking for uniqueness. You can use this to look for uniqueness in any field, not just in the key field. Additionally, the search engine used by this function looks for a partial match, and will only return true if the given string is not found anywhere in the specified element for the given file.

''fnNotInFile(string$*100,filename$,sub)''

*String$ - Value to check for uniqueness in this file.
*Filename$ - This is the name of the file layout of the file you want to check. This file does not have to be open in order for you to search it, because the function will open it for you.
*Sub – This is the subscript value of the element you are checking.

==== fnSortKeys ====
This function takes an array of Primary Keys indicating records in the data file, and resorts it into the order you would have expected using one of the other keys for your data file.

For example: Lets say you had a customer file, and the first key was Customer Code and the second key was Customer Last Name. This function would take an array of Customer Codes and sort it into Last Name order.

This function requires the file to already be opened (which is usually the case when you have an array of keys from that file).

''fnSortKeys(mat Keys$,Layout$,DataFile,mat F$,mat F,mat Form$;KeyNum)''

*mat Keys$ - the array of keys. These keys are based on whatever key the file was opened with in DataFile.
*Layout$ - the file layout for the file.
*DataFile - the open file number matching the key file that matches mat Keys$.
*mat F$ - array sized to hold the strings from the data file. This is the array you get back from fnOpen.
*mat F - array sized to hold the numerics from the data file. This is the array you get back from fnOpen.
*mat Form$ - array of form statements, that you get back from fnOpen.
*KeyNum - This is the key that we'll sort based on. If not given, the first key listed in the layout is assumed.

=== File Reading Functions ===

These functions actually read information from your data file and return it. These functions can be used to simplify the logic in your programs for many common tasks.

==== fnReadAllKeys ====
This function will read through a file, returning the specified element(s) from each record into (a) dynamically dimensioned array(s). For example, I could tell it to give me the Inventory Code for every inventory item in my database in one array, while placing the Inventory Description (name) for each item into the corresponding position in another array.

''fnReadAllKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$;sub2,mat out2$)''

*Fl – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array
*mat out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

For example:

FnReadAllKeys(InventFile,mat Invent$,mat Invent,mat Form$,IN_Code,mat InvtList$,IN_Name,mat InvtNames$)

==== fnReadMatchingKeys ====

This function will read through a file, returning the specified element(s) from each record where the key matches the specified key into (a) dynamically dimensioned array(s). This function is the same as the above function except this one will filter the results, returning only those records where the key matches the specified key.

''fnReadMatchingKeys(Fl,mat f$,mat f,mat fm$,key$,keysub,sub1,mat out1$;sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - Only records where the key field matches key$ will be returned.
*Keysub – This tells the function which element is the key element for this particular file number.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadAllNewKeys ====

This function will read through a file, returning the specified element(s) from each record that isn’t already there into (a) dynamically dimensioned array(s). This function is the same as the above function, except this one will filter the results returning only those records that don’t already exist in the array (eliminating duplicates).

''FnReadAllNewKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$; dont_reset,sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Dont_reset – By default the array will clear the contents of the arrays that are passed in. This Boolean flag will instruct the function to not empty the passed in arrays.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadFilterKeys ====

This function by Mikhail Zheleznov is a modification of the above functions. Like its predecessors, it reads an entire file, populating the specified arrays with data from all or some of the records in the file. The given subscripts specify which fields to return from each record. The key given specifies search criteria for the records. The filter specifies filtering criteria that can be preformed on the data before it is returned.

''FnReadFilterKeys(Fl,Mat F$,Mat F,Mat Fm$,Key$,Keyfld,Sub1,Mat Out1$;Filter$,Filter_Sub,Readlarger,Sub2,Mat Out2$, Sub3, Mat Out3$, Sub4,Mat Out4$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - The key to search for in the read statements
*Keyfld – the subscript of the key field in the data file. This must match the key field specified in the data file otherwise the function won’t work.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Filter$ – This optional parameter identifies matches to search for in the records. It works in conjunction with Filter_Sub
*Filter_Sub – This parameter specifies which field to look for in the records for matches to Filter$. Only records which have Filter$ in the specified field will be returned.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.
*Sub3 – Subscript of the element to return in the third array. This is optional. If it is specified, you must give MAT out3$, or BR will return an error.
*MAT out3$ - Array in which to return the third (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub3 is given (non-zero). This parameter will not be used if Sub3 is not given or is given as 0.
*Sub4 – Subscript of the element to return in the fourth array. This is optional. If it is specified, you must give MAT out4$, or BR will return an error.
*mat out4$ - Array in which to return the fourth (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub4 is given (non-zero). This parameter will not be used if Sub4 is not given or is given as 0.

This function was written by Mikhail Zheleznov for the fileIO library.

==== fnReadDescription$ ====
''fnReadDescription$(Fl,Subscript,key$,mat F$,mat F,mat Form$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout) (RT_NAME, which should equal 2 after opening routefile (unless we change the file layout later)).
*key$ - Item that should match a key in this file somewhere (in this case it is the route code from the farm record).
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading they have to be dimensioned properly, which is why we use our colorcat$ and our colorcat for these parameters.
*mat Form$ - This will need to be our array of form statements, so the function can read the file properly.

Lets take a look at how this function works:

In the example program I used above, I am reading the Color File to get details about each color. The color file contains a colorcat code field, but I want to display the colorcat description. The colorcat file contains a few details about a color category, and it is indexed based on colorcat code:

route.dat, RT_
route.key, CODE
recl=512
===================================================
CODE, Routing Code, C 6
NAME, Routing Name Description, C 30
MOFT, T/A/C (truck/air/courier), C 1
SHIPPINGDAY, Day of Week for Shipping, C 7

Now, as you know, in the above example, we have already opened the ColorCat File, and we have opened and read a Color record.

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
30180 LET ccode$=color$(CO_CODE) !:
LET Name$=color$(CO_NAME)

Now all that’s left to do is to take the Color File’s ColorCat code and use it to look up the ColorCat File’s description.

30190 LET ColorCat$ = fnReadDescription$(ColorCatFile, CC_NAME, Color$(CO_CATEGORY),
mat ColorCat$, mat ColorCat, mat form$)

==== fnReadUnopenedDescription$ ====
This function accomplishes the same thing as fnReadDescription except that it opens the data file for you. It is slower then FnReadDescription$, but it is easier to use.

''FnReadUnopenedDescription$(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the value of the key field in the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2, so sometimes it is a good idea to design your data files so that string field number two is a descriptive field, like Name or Description.

This function only works on the first key file for each data file. This function is a convenience function but it is slow because it opens the file and closes it for each call. Opening a file is one of the most time consuming program operations.

==== fnReadNumber ====

fnReadNumber does the same thing that ReadDescription does except it reads a numeric field instead of a description.

Lets take a look at how this function works:

''fnReadNumber(Fl,subscript,key$,mat F$,mat F,mat fm$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout).
*Key$ - Item that should match a key in this file somewhere.
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading. They have to be dimensioned properly by [[FileIO_Library#fnOpenFile|fnOpen]].
*mat Fm$ - This will need to be our array of form statements, so the function can read the file properly.

==== fnReadUnopenedNumber ====
This function accomplishes the same thing as fnReadNumber except that it opens the data file for you. It is slower then FnReadNumber, but it is easier to use.

''fnReadUnopenedNumber(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the key of the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2.

==== fnReadRelativeDescription$ ====
This function is the same as fnReadDescription$ but for Relative Files.

''fnReadRelativeDescription$(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat F,mat form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedDescription$ ====
This is the same as ReadUnopenedDescription$ but for Relative Files.

''fnReadRelUnopenedDescription(Layout$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRelativeNumber ====
This is the same as fnReadNumber but for Relative Files.

''fnReadRelativeNumber(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat f,mat Form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedNumber ====
This is the same as fnReadUnopenedNumber but for Relative Files.

''fnReadRelUnopenedNumber(LayoutName$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRecordWhere$ ====
This function returns the record where the given element matches the given value. It does not depend on any key files, and it can be used to locate a record based on any element. However, it loops through the entire data file to do this and it could be a bit slow for large data files. This function opens the file for you, so the file does not have to be already opened.

''FnReadRecordWhere$(Layout$,SearchSub,SearchKey$*255,ReturnSub)''

*Layout$ - the layout of the file we are searching
*SearchSub - Subscript of the element to look in
*SearchKey$ - The value we are looking for
*ReturnSub - Subscript of the element to return

=== FileIO Utility Functions ===
==== fnDataCrawler ====
This function launches the Data Crawler as a function, so you can make your own programs link to it. Special thanks to Mikhail Zheleznov for turning the DataCrawler into a library function.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnDataEdit ====
This function is the same as fnDataCrawler only it opens a Grid for editing.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnShowData ====

This function builds a list or a grid in a floating window that is tied to a data file. It uses the same function that the datacrawler uses, but its much more customizable. All other datacrawler functions are just wrappers for this one.

The first parameter is the only required parameter.

''def library fnShowData(FileLay$;Edit,sRow,sCol,Rows,Cols,KeyNumber,Caption$*127,Path$*255,KeyMatch$*255,SearchMatch$*255,CallingProgram$*255,mat Records,mat IncludeCols$,mat IncludeUI$,mat ColumnDescription$,mat ColumnWidths,mat ColumnForms$,DisplayField$*80,mat FilterFields$,mat FilterForm$,mat FilterCompare$,mat FilterCaption$,mat FilterDefaults$,mat FilterKey)''

*FileLay$ - the file layout you want to display
*Edit - 1 for Edit (Grid) and 0 for View (Listview)
*sRow, sCol - the start position. if not given, its centered. If given but out of bounds, they'll be automatically adjusted to fit the grid on the screen.
*Rows, Cols - the size. If not given, defaults to fullscreen. If given but not big enough to fit the UI elements you request, they're automatically adjusted to fit everthing.
*KeyNumber - the Key to use when reading the data, used with other parameters. If not given, the file is read Relative for faster performance. Required if KeyMatch$ is given.
*Caption$ - the Caption to display, defaults to FileIO's Datacrawler
*Path$ - Alternate path to use for data files (Prepended to the name found in the layout)
*KeyMatch$ - Show only records that match this key. You can use Partial Keys. If this parameter is given, you must also give KeyNumber (above).
*SearchMatch$ - Show only records that contain this substring in them anywhere
*CallingProgram$ - used for logging purposes, pass in the system function Program$
*mat Records - Show only these records in the Grid. Use it to control exactly what the user sees.
*mat IncludeCols$ - Show only these columns. These column names must match the subscript names from the file layout.
*mat IncludeUI$ - Which UI Options to show. Build this array with one element for each optional UI element to include. Explanations of UI elements follow:
**"ColumnsButton" - adds a Select Columns button that the user can use to modify which columns appear on the list.
**"ExportButton" - adds an Export to CSV button that exports the data to a CSV file.
**"ImportButton" - adds an Import from CSV button that imports from the CSV file.
**"AddButton" - adds a button that can be used to add records to the data file.
**"SaveButton" - adds a button allowing the user to save changes
**"DeleteButton" - adds a button allowing the user to delete a row
**"KeyButton" - adds a button allowing the user to jump to a specified position by key or by record number (depending on if the file is opened keyed or not)
**"QuitButton" - adds a Quit button to the screen (the Esc key also quits)
**"Search" - adds a case insensitive search box to the screen.
**"Border" - adds a border around the screen
**"Caption" - adds a caption. (If you specify a caption, this is automatically turned on. If you don't specify a caption but turn on caption here, then FileIO uses the default FileIO data crawler caption.
**"Recl" - adds the Recl to the caption
**"Position" - adds the positions to the field descriptions in the column headings.
*mat ColumnDescription$ - Show these captions. If blank, use the descriptions from the layout
*mat ColumnWidths - Use these widths for the data, if not given, calculate from the file layout
*mat ColumnForms$ - Display Format for the data, including DATE and FMT and PIC
*mat DisplayField$ - Counter Field to display on the Loading Window. If its a field with an associated DATE ColumnForms$ value, that column form will be used when displaying the Counter Field. It can be any of the following:
**REC - this will display the current "REC/LREC" data in the loading window.
**READCOUNT - this will display the "Record Count / LREC" in the loading window.
**FINDCOUNT - this will display the number of records that match the current search criteria by itself in the loading window.
**A Field Name - one of your field names will display that field value in the loading window
**A string literal - anything else will display as a string in the loading window, so you could put something like "Loading, please wait" here and it will display.
*mat FilterFields$ - Contains the subscript of the field to compare to
*mat FilterForm$ - Contains the format of the field to compare to
*mat FilterCompare$ - Contains the comparison type ("<>" or ">" or "=" or ">=" or "*") (* means do a substring search)
*mat FilterCaption$ - The caption for the filter box
*mat FilterDefaults$ - The default value for the filter information
*mat FilterKey - The action to use when filtering the data this way (0 means simple exclude, 1 means start here, -1 means stop here)
**The final five arrays can be used to add user filter boxes to the data grid. You need one element in each array for every custom user filter box on the screen.

==== fnBeginAudit ====

The [[AuditBR|FileIO Compare]] routine is available and can be called from within your programs. To do so, call fnBeginAudit to mark the Start of the compare, then do whatever you need, then run fnCompare to compare everything that has changed between when you ran fnBeginAudit and when you ran fnCompare.

See [[AuditBR#fnBeginAudit|the documentation]] for more details.

==== fnCompare ====

See [[AuditBR#fnCompare|the documentation]] for more details.

==== fnCSVImport ====

This function calls the FileIO Import routine, the same one that you get from the Datacrawlers Import Button.

''fnCsvImport(Layout$*64;SuppressDialog,FileName$*300,ImportModeKey)''

*Layout$ - The file layout to import into
*SupressDialog - 1 to Supress the Import Dialog
*FileName$ - the name of the CSV file (Required if Dialog is Suppressed)
*ImportModeKey - the Import Mode Key (Required if Dialog is Suppressed)
**-1 - Add all records to the file
**0 - Update by Record Number (The file must contain a RecNum column and it must be first)
**1+ - Any positive number means Update by that Key (as listed in the layout).

==== fnCSVExport ====

This function exports a data file to a CSV file.

''fnCsvExport(Layout$*64;SuppressDialog,Filename$*300,IncludeRecNums,KeyNumber,StartKey$,KeyMatch$,Startrec,mat Records,SearchMatch$)''

*Layout$ - The File Layout to Export
*SuppressDialog - (1 to Suppress the Export Dialog, 0 to show it)
*Filename$ - the output file name (Required if SuppressDialog is 1)
*IncludeRecNums - Include a column with the Record Numbers in it
*KeyNumber - Use this key when reading the data for export
*StartKey$ - Start with the record that matches StartKey$
*KeyMatch$ - Export only the record(s) that match KeyMatch$
*StartRec - Start with this Record Number
*mat Records - Export only these records
*SearchMatch$ - Export only records containing this search string anywhere in them

==== fnExportListViewCsv ====

Exports the contents of the specified Listview in CSV format.

''fnExportListViewCsv(Window,Spec$;GenFileName,Delim$,FileName$*255)''

*Window - The Window containing the listview.
*Spec$ - The Spec identifying the listview.
*GenFileName - Flag telling weather or not to generate the file name.
*Delim$ - Delimiter to use. Comma is default.
*Filename$ - Filename to use

==== fnGenerateLayout & fnWriteLayout ====

This function calls on the Generate File Layout Wizard to generate and save the layout indicated by the parameters you give it. You must give it the same valid parameters that you would have come up with if you worked through the layout wizard the normal way, by running FileIO directly and choosing "Generate Layout".

You can also bypass the automatic parsing and generate a layout by specifying all the data directly and using fnWriteLayout.

''fnGenerateLayout(mat OpenStrings$, ReadString$*999, FormString$*20000, DimString$*999; DisplayFile)''
''

*mat OpenString$ - array of all the open strings for the given file from one of your old programs.
*mat ReadString$ - solid read statement from one of your old programs reading the entire record, (or at least everything you want in the layout).
*mat FormString$ - the form statement that goes with the ReadString$ (practice using the Generate Layout Wizard the normal way for details)
*mat DimString$ - the string containing Dim statements for each array mentioned in ReadString$. We need this to know how big the arrays are.
*DisplayFile - if True (1), it will Display the new layout in notepad when its done creating it. If false (0), it will simply create the file.

fnGenerateLayout takes all the above information and parses it into a layout, then calls fnWriteLayout to actually write the layout.

If you already know the information you want to put in the layout, its more direct to call fnWriteLayout below.

''fnWriteLayout(Name$,FileName$*127,VER,PRE$,MAT KFNAME$,MAT KDESCRIPTION$,MAT SUBS$,MAT DESCR$,MAT FORM$;RECL,MAT EXTRA$,DISPLAYFILE)''

*Name$ - the name of the new layout
*FileName$*127 - the name of the data file
*Ver - the version of the data file
*Pre$ - the prefix to use for the data file
*mat KfName$ - array of all the keys for the file
*mat Kdescription$ - array of the subscripts that each key is based on
*mat Subs$ - the subscript for each field in the file
*mat Descr$ - the descriptions for each field in the file
*mat Form$ - the form specs for each field in the file
*Recl - (optional) the record length of the file
*mat Extra$ - (optional) Additonal Information for each field in the file, placed in the Comments column of the new layout. This column is ignored by standard fileio processing.
DisplayFile - if True, open the file in Notepad after it has been created.

==== fnSubstituteStringCode ====
A Large Text Field that is searched. Code is run and any resulting variables are set, if they exist inside String enclosed between Substitute Chars (default []), then they will be replaced with the values derived by the code.

''fnSubstituteStringCode(&String$,Code$*2048;SubstituteChar$)''

*String$ - the string to be searched
*Code$ - code to be run. The resulting variables can be substituted into String
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnSubstituteString ====
A Large Text Field that is searched. Any matching fields in the passed in record will be substituted into their places. For example, if the string contained [cu_name] and you ran substitutions on the Customer file, then [cu_name] would be replaced by the name in the actual Customer record.

''fnSubstituteString(&String$,Filelayout$,mat F$,mat F;SubstituteChar$)''

*String$ - the string to be searched
*FileLayout$ - the layout to be searched
*mat F$ - the record to be used for substitution
*mat F - the record to be used for substitution
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnShowMessage ====
Displays a message to the user, in a child window. Returns the child window number, so that you can close it when you're done with the message.

''WindowNumber=fnShowMessage(Message$*54)''

*Message - the Message to display to the user

=== File System Utility Functions ===
These functions perform other tasks that aid with interacting with the file system.

==== fnGetFileDateTime$ ====
This does a directory listing to determine the Last Modified Date and Time of the given file. You pass it a file name, not a file layout, and it can be used on any file. Its not limited to BR internal files.

The syntax is:

''let FileDate$=fnGetFileDateTime$(Filename$*255)''

==== fnProgressBar ====
There's a Progress Bar that FileIO uses when copying or updating data files. You can use it in your own functions by calling fnProgressBar inside the main loop of the process that you want to display the progress bar over, and by calling fnCloseBar when you're done.

''fnProgressBar(Percent;Color$,ProgressAfter,ProgressThreshhold,UpdateThreshhold,Caption$*255,MessageRow$*255)''

*Percent - Percentage Complete expressed as a float between 0 and 1
*Color$ - HTML Color Code of BR Color Attribute to color the Progress Bar. Defaults to Green.
*ProgressAfter - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*ProgressThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*UpdateThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*Caption$ - Optional message to display above the progress bar.
*MessageRow$ - Optional message to display on the progress bar.

==== fnCloseBar ====

''fnCloseBar''

Call this function to close the progress bar window when your task is done running.

==== fnCopyFile ====

''fnCopyFile(FromFile$*255,ToFile$*255)''

*FromFile$ - The file to copy.
*ToFile$ - The destination file name including path.

This function copies any file, by opening it as an external file and reading and writing the data to the destination file. The advantage of this technique, over using the BR copy command, is this routine is more reliable when run on client server where you may be transferring large files from one side to the other over the internet.

This fnCopyFile also has a progress bar that displays as the file is transferred, so the user knows your software is busy.

This function works over Client Server. Under Client Server, specify @: at the beginning of your filename, to specify that the file is on the client. If the file is on the server, simply leave the @: off. See the chapter on [[Copy#Client_Server|using BR's copy command under Client Server]] for more details on the "@:".

This function's parameters and syntax are modeled off of the built in BR copy command, and like that one, this should work for local transfers, LAN transfers, or even internet transfers. This function will work better for internet transfers then the built in BR Copy Command, however.

==== fnCopyDataFiles ====

''fnCopyDataFiles(DestinationFolder$*255)''

*DestinationFolder$ - the folder to copy your data files to.

This function reads your file layouts and makes a copy of every data file (and key file) in your system to the destination folder, utilizing fnCopyFile above, for better performance and reliability when running over the internet, as well as a progress bar for each individual file.

It also displays a listview while its copying so you can watch the progress while its transferring your data files.

This can be used for making backups of your BR data, or for transferring the latest data onto a laptop for access to it while you're on the road away from the internet.

==== fnReIndex ====

This function reindexes a single data file

''fnReIndex(DataFile$*255;CallingProgram$*255,IndexNum,Path$*25)''

*Datafile$ - the file layout of the file to index
*CallingProgram$ - used for logging, pass Program$ in here
*IndexNum - The index to rebuild - if not given, rebuilds all indexes
*Path$ - the optional alternate path to use for rebuilding the data file.

==== fnReIndexAllFiles ====

This function reindexes all your data files. It doesn't require any parameters.

''fnReIndexAllFiles''

==== fnUpdateFile ====
This function checks and Updates a data file if it needs to be updated, by opening and then closing the data file.

''fnUpdateFile(FileLayout$)''

*FileLayout$ - The name of the file to update

==== fnRemoveDeletes ====

This function, written by Susan Smith, removes deleted records by copying the file with the -D option.

''fnRemoveDeletes(LayoutName$*255;Path$*255,CallingProgram$*255)''

*LayoutName$ - the file layout
*Path$ - Optional Alternate Path
*CallingPRogram$ - used for logging, pass Program$ in here

=== Layout Interrogation ===
Layout interrogation functions are provided for convenience and to enable future dictionary changes without disrupting any programs that interrogate it.

==== fnMakeSubProc ====
This function obtains the subscript assignments that were assigned by fnOpen according to the file layout. The fnMakeSubProc$ routine obtains the subscript assignments without actually opening the file. This is useful when a file record is passed as arrays into a library function in another program, or when you chained to another program and you need to know how to reach the data in the arrays without actually reopening the file.

''fnMakeSubProc(filelay$;mat Subscripts$)''

*FileLay$ - The name of the file layout from which to read the subscripts.
*mat Subscripts$ - If you give this optional array, fnMakeSubProc passes the subscripts back in this array rather then in the subs.$$$ file. This is much faster and helps avoid sharing conflicts.

When this routine returns, you can set the subscripts in your program by executing every element of the Subscripts$ array in a for/next loop.

If you did not pass in a subscripts array, then the a procedure file named subs.$$$ is created. If you proc that file, the proper subscripts will be set.

==== fnReadLayoutArrays ====
This function reads the fields in a file layout into arrays. You call it like the following

''fnReadLayoutArrays(filelay$,&prefix$;mat SSubs$, mat NSubs$, mat SSpec$, mat NSpec$,mat SDescription$, mat NDescription$,Mat Spos,Mat Npos)''

*filelay$ - the name of the layout to read
*prefix$ - the return value for the prefix for the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

This function call would read the fields from the layout in filelay$, and it would return the prefix to prefix$. The Subs would be returned in mat SSubs$ and mat NSubs$.

The Spec statements are returned in mat SSpec$ and mat NSpec$ and the Descriptions are returned in mat SDescription$ and mat NDescription$. The start positions on disk of each element are returned in mat SPos and mat NPos.

All the arrays are optional. If you don’t pass them the information they are supposed to record is simply not returned.

==== fnReadLayoutHeader ====
This function reads the header for a given file layout.

''fnReadLayoutHeader(Layoutname$*255;&Filename$,Mat Keys$,Mat KeyDescription$)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file

==== fnReadEntireLayout ====
This function reads the entire layout by calling fnReadLayoutHeader and fnReadLayoutArrays.

''fnReadEntireLayout(Layoutname$*255;&Filename$,&Prefix$,Mat Keys$,Mat KeyDescription$,Mat Ssubs$,Mat Nsubs$,Mat Sspec$,Mat Nspec$,Mat Sdescription$,Mat Ndescription$,Mat Spos,Mat Npos)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*prefix$ - the return value for the prefix for the file
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

==== fnReadSubs ====
This function reads the subscripts from a layout into Subs arrays.

''fnReadSubs(Layout$,mat SSubs$,mat NSubs$,&Prefix$)''

*Layout$ - the file layout name
*mat SSubs$ - the String Subscript Names
*mat NSubs$ - the Number Subscript Names
*Prefix$ - the files Prefix

==== fnReadKeyFiles ====
This function reads the list of key files from the layout.

''fnReadKeyFiles(Layout$,mat Keys$)''

*Layout$ - The file layout
*mat Keys$ - output array, the keys are returned here.

==== fnLayoutExtension$ ====

This function returns the layout extension being used.

==== fnReadLayouts ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''FnReadLayouts(mat Dirlist$)''

*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all the file layouts that FileIO can find.

==== fnDirVersionHistoryFiles ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''fnDirVersionHistoryFiles(Layout$,mat DirList$;BypassExtension$)''
*Layout$ - Which layout to look up version history of
*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all previous versions from history of the requested layout.

==== fnReadLayoutPath$ ====
This function doesn't actually interrogate your layouts. Instead, it interrogates your settings and returns the path specified for your layout files. This would usually be "filelay\" but you can change it in [[#fnSettings|fileio.ini.]]

It has no parameters.

''let Path$=fnReadLayoutPath$''

==== fnDoesLayoutExist ====
This function returns true if the given file layout exists. It returns false if the layout does not exist.

''FnDoesLayoutExist(layout$)''

*Layout$ - Layout to test for

==== fnReadForm$ (uncompiled) ====
Sometimes you need to know the original form statement that fileio is using to read your data file, most often when you're debugging your file layout, and you're getting some problem when reading the file. The form statement that fileio normally returns is compiled using CFORM$ to save space in the array, and to make the execution of your read statements faster. You can use this function to return the original form statement for the file.

The syntax is:

''let FormStatement$=fnReadForm$*10000(FileLayout$)''

Remember to dimension FormStatement to something huge! fnReadForm$ can return up to 10,000 characters.

==== fnReadFormAndSubs ====

This function does the same as above but it also reads the subscripts from the file into an array.

''let fnReadFormAndSubs(Layout$,mat Subs$,&ReadForm$,&StringSize,&NumberSize)''

Note that unlike most of our functions, all the above parameters are required.

The layout is the layout you're interrogating. The Array will be populated with the subscripts after the function. The ReadForm$ variable will be filled with the form statement for the file. Remember to dimension it large enough. StringSize and NumberSize will contain the number of string fields and numeric fields in the file.

Mat Subs$ will be returned, strings first, numbers last, matching the form statement that is returned. So Subs$(1) is the first string subscript and Subs$(StringSize+1) is the first Numeric subscript.

==== fnClearLayoutCache ====

fnClearLayoutCash (v2.3+) clears out the cache of layout name and data to get realtime Updates to File Layouts.

=== Other Useful Functions (non-layout related) ===

==== fnAskCombo ====

Opens a window with a combo box and returns the users selection.

''fnAskCombo$*255(mat Description$;Caption$*60,Default$*255)''

*mat Description$ - contains the combo box choices
*Caption$ - contains the optional caption for the window
*Default$ - the text of the item in mat Description$ that you want to be selected by default

==== fnSendEmail ====

This function sends an email and an optional attachment to the email address specified.

''fnSendEmail(Emailaddress$*255,Message$*10000;Subject$*255,Invoicefile$*255)''

*EmailAddress$ - the Destination Email Address
*Message$ - the Message$ to send
*Subject$ - the subject
*InvoiceFile$ - the filename of a file to attach. This is the BR filename (the function automatically converts it to an OS Filename.)

The function returns 1 when the email was sent successfully, or 0 if it wasn't sent successfully.

In order to use this function, you must have the emailcfg file layout in your layouts folder and you must have a copy of SendEmail.exe which is free and can be downloaded from the internet. Both of these files are included with the latest update of fileio.

You also have to configure fileio with the authentication information for your email server.

To configure your email server, simply run FileIO to get the data crawler, then select the emailcfg file layout and press F5 to edit it. Add a row if the file is empty.

Simply fill in the information the file is asking for in the appropriate fields and save the data, and then test sending an email to make sure it worked.

More information about sendEmail.exe is available from the author's product site here: [http://caspian.dotconf.net/menu/Software/SendEmail/ http://caspian.dotconf.net/menu/Software/SendEmail/]

==== fnClientEnv$ ====

This function returns the value of a Windows Environment Variable on the client under Client Server.

''fnClientEnv$*255(EnvKey$)''

*EnvKey$ is the name of the Windows Environment Variable to check on the client.

The function returns the value of the entered environment variable.

==== fnClientServer ====

This function returns true if you're currently running in Client Server mode, and false if you're running in the old "native" mode.

==== fnEmpty & fnEmptyS ====
These functions test if the passed in array is empty or not..

The syntax is:

''fnEmpty(mat Numeric)''

or

''fnEmptyS(mat String$)''

Example:

def fnSomeFunction(String$,mat Array$; mat OtherArray)
if fnEmpty(mat OtherArray) then
! Arrays were empty.
end if
fnend

==== fnReadScreenSize ====
This function reads the screen size of the given window (or window 0 if a window wasn't passed.) This is useful for centering a window on the screen, or for making sure window 0 is big enough for the child window you're trying to create.

The syntax is:

''fnReadScreenSize(&Rows,&Cols;Window)''

*Rows & Cols - returns the screen size in rows and columns.
*Window - the window to interrogate. If not given, assumes [[Open_Window#Comments_and_Examples|Window 0]].

==== fnBuildProcFile ====
This function builds a proc file to be executed later. This function and the next simplify the process of executing code in a proc file. It can even be used to spawn a new session of BR.

To use it, call fnBuildProcFile one or more times and specify some lines of code to execute.

''fnBuildProcFile(Command$*255)''

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnRunProcFile ====

This function spawns a new copy of BR and in it, runs the proc file that you've previously built using fnBuildProcFile (above).

'' fnRunProcFile(;NoWait) ''

The optional parameter "NoWait" causes the other session to spawn and run in a new thread. If you don't specify NoWait, the current session pauses and waits for the other session to close before proceeding.

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnLog & fnErrLog ====
These next two functions are functions to aid in logging. When you call either of these two functions, you give them a string that you wish to log. They will open the FileIO Log File and add a record to the end of it containing some user information such as login_name and session$, and the string that you specified. FnErrLog does the same thing as fnLog except it also logs the Error Number and the Line.

The syntax is:

''FnLog(string$)''

*String$ - the Log Message

''FnErrLog(String$)''

*String$ - the Log Message

==== fnLogArray ====

This function logs the given arrays to the log file, logging each field in the arrays. Its useful for recording, for example, an entire data record that is about to be written to a data file.

The syntax is:
''fnLogarray(mat F$,mat f;Message$*512,CallingProgram$*255)''
The first two parameters, of course, are the array to log. The third parameter is an optional message to be recorded along with the array, and the fourth optional parameter is the CallingProgram$ to save in the log along with the message. (The CallingProgram$ parameter can usually be passed as the system function Program$)

==== fnSetLogChanges ====
This function works in conjunction with the next function, and they're for recording just what changed in a data file. When the file is read, you call fnSetLogChanges and record the "before" picture of the file record.

After changes have been made and saved back to disk, you can call fnLogChanges below to record the actual changes.

The syntax is:
''fnSetLogChanges(mat F$,mat F)''

==== fnLogChanges ====
This function is the other half of the function above. It compares the given arrays with the ones set previously in the above function and checks for changes. Then it generates a log message recording information about just the items that changed.

The syntax is:
''fnLogChanges(mat F$,mat F;Message$*1024,CallingProgram$*255,Layout$)''

You need to pass in the same two arrays as before, but this time the modified versions of them.

You can also optionally pass a 1024 byte log message to record with the log entry.

CallingProgram$ again should be passed as the system internal function Program$.

The final parameter allows the passing of a Layout$. If you pass a Layout$, that layout is read and the subscripts are used when making the log message of changes, so that its easier to read. If you pass a layout, it will identify the changed fields by name. If you don't it will identify those fields by relative position number.

==== fnViewLogFile ====
All of the above functions store the information by default into a BR internal file defined in the filelay\logfile layout.

The fnViewLog function uses fnShowData to call the Data Crawler to display the FileIO Log File in a searchable listview.

''fnViewLogFile(;ShowQuit,ShowColumns,ShowExport)''

*ShowQuit - Show a quit button on the UI (if off, ESC will quit).
*ShowColumns - Include a button to allow the user to select which columns to view.
*ShowExport - Include a button to export the log file to CSV.

==== fnReadLockedUsers ====

This function returns a list of all users using the locked data file.

''fnReadLockedUsers(mat Users$)''

*mat Users$ - the list of users is returned here

==== fnDisplayLength ====
This function calculates the display length of a field based on its form spec.

''fnDisplayLength(Spec$)''

*Spec - the Form Spec to return the display length of.

==== fnLength ====
This function calculates the length on disk of a field based on its form spec.

''fnLength(Spec$)''

*Spec$ - the Form Spec to return the length of.

==== fnStandardTime$ ====
Converts Military Time to Standard Time. Returns Standard Time$

''fnStandardTime$(MilitaryTime$;Seconds)''

*MilitaryTime$ - Time in 24 hr format.

==== fnMilitaryTime$ ====
''fnMilitaryTime$(StandardTime$;Seconds)''

*StandardTime$ - Time in AM/PM Format

==== fnCalculateHours ====
Calculates the difference between 2 specified times.

''fnCalculateHours(TimeIn$,TOut$,DaysIN,DaysOut)''

*TimeIn$ - From Time
*TimeOut$ - To Time
*DaysIn - Days Start
*DaysOut - Days End

==== fnBuildTime$ ====
Builds a time in the format used by the above functions.

''fnBuildTime$(H,M,S,P;Military,Seconds)''

*H - Hours
*M - Minutes
*S - Seconds
*P - Boolean indicating AM/PM - 0 is AM, 1 is PM
*Military - Flag indicating weather desired result is in Military Time or not
*Seconds - Flag indicating weather to count seconds or ignore them. (1 means count seconds)

==== fnParseTime ====
Takes a time and pulls out the values

''fnParseTime(T$,&H,&M,&S,&P)''

*T$ - the time to parse
*H - Return value for Hours
*M - Return value for Minutes
*S - Return value for Seconds
*P - Return Value for AM/PM

== FileIO fnSettings (Global Settings Code) ==

The FileIO library can be made to implement certain policies across the board. These are established by creating a file called fileio.ini and typing statements like the following into it. This file is "PROCed", so you don't want to put line numbers in it.

Anything you don't specify in fileio.ini will take its default value, shown below. So you only need to specify the items that you want to be different.

Note, for the boolean settings below, 1 denotes TRUE and 0 denotes FALSE.

let EnforceDupkeys=1 ! Enforce that key number 1 is unique key
let Defaultfilelayoutpath$="filelay\" ! Path To Your File Layouts
let Promptonfilecreate=1 ! Ask User Before Creating New Files
let Createlogfile=0 ! Use Logging
let StartFileNumber=1 ! Set above 300 to avoid conflicts with legacy programs.
let CheckIndex=0 ! Automatically Verify Indexes (slow)
let CompressColumns=0 ! Shrink or Expand Columns in Data Crawler by Default
let MaxColWidth=20 ! Max Default Column Width in Data Crawler
let LogLibrary$="" ! Defaut Log Library, defaults to None
let LogLayout$="" ! Log file layout, defaults to Internal File
let AnimateDatacrawler=1 ! Use ScreenIO Animation for Datacrawler
let TemplatePath$="filelay\template\" ! Default Template Path
let IgnoreLayouts$="" ! List any Ignore Layouts here.
let CloseFileSimple=0 ! Use simple comparison for fnCloseFile

==== EnforceDupkeys ====

Turn on the EnforceDupkeys option to force that the first key listed in your file layouts is a unique key. FileIO will generate the standard BR error for Dupkeys when attempting to create indexes if it is not unique.

==== DefaultFileLayoutPath$ ====

Use the DefaultFileLayoutPath option to specify the path from your programs to your file layout folder. The default is "filelay\". Use this setting if you want to place your file layouts in another folder from the default.

==== PromptOnFileCreate ====

Use the PromptOnFileCreate setting to cause FileIO to display a message box whenever it is attempting to create a new file. This happens during the automatic update procedure, as well as during any attempt to access a file that does not exist. This setting should be turned off in your live system, and only turned on for development purposes. If you use the message box to cancel creating of the new file, then the file is not created, and fileIO or your application will most likely give an error when you attempt to actually access the new file.

It can be useful during development to make sure that you don't accidentally create the wrong files, due to an incorrectly specified path or a typeo in the filename in the layout file. However, in a live system, these things have already been tested, and you generally want the default behavior, because you don't want your users to have the ability to cancel the normal operation of FileIO.

==== CreateLogFile ====

Use this option to specify weather or not to use the FileIO log file. If it is turned on, a log file called FileIO.log in the current directory is created with entries listing all attempts to open a file, automatically update one, or automatically update your indexes.

==== StartFileNumber ====

Use this option to set the starting file number that the fnGetFileNumber and the fnOpen functions use to search for available file numbers. This is so that if you have certian reserved file numbers in your code, you can make sure that FileIO will not use those reserved file numbers, causing a conflict with your already existing programs. The default is 1, which is fine if your software does not have any reserved file numbers.

The allowable BR file numbers are 1-200 and 300-999.

==== CheckIndex ====

This function is used for Partial FileIO Implementations. If all of your software uses FileIO then all of your indexes are kept automatically up to date by the FileIO library and BR's internal file processing systems. However, if some of your programs do not use FileIO, and you use the FileIO library to add a new index file that those other programs do not know about, then its possible for the additional index file to become out of date when the master file is updated by your other programs.

Use this setting to cause FileIO to check the DateTime stamp on all your index files when opening a new file, and automatically update any indexes that may have potentially gotten out of date from other programs.

This option slows down the processing of the fnOpen function, particularly when running under client server over the internet. If you know that every program in your application suite uses FileIO, and that any programs that do not use FileIO still properly update all the indexes that your data file uses, then you can safely leave this setting turned off, and optimize your performance when opening several files using the fileIO system.

==== CompressColumns ====
This instructs the datacrawler to use smaller widths for small columns. If CompressColumns is false, the data crawler will make the column the width of the field or the width of the caption, whichever is wider. If CompressColumns is true, it will use the width of the field, not the caption.

==== MaxColWidth ====
This limits the column width to a set amount. This is applied after CompressColumns above.

==== LogLibrary$ ====
If a library is specified here, then fileio looks for a BR library with the specified name, and attempts to call a library function in it called fnFileIOLog that. This function should expect six parameters, which are Logstring$, Login_Name$, Session$, Days of Date$, Time$, and CallingProgram$, if LogLayout is also nonblank.

If you specify a LogLibrary and LogLayout is blank, then it calls your function giving it only 1 parameter.

It will call your function '''''instead of''''' the normal log file. Use this to implement your own logging functions however you want.

==== LogLayout$ ====
Use this setting to specify an alternate file layout for an alternate file to do the logging in. Base the file layout for this file on the logfile we supply for you in the filelay folder. It should have at least those fields, which our log routine will automatically populate, but you can add other fields if you want (though you will need to manage them yourself).

If you don't specify LogLayout, the default filelay\logfile will be used. This will allow you to also use the fnViewLogFile function to access it.

==== AnimateDataCrawler ====
The sister library [[ScreenIO]] has a feature that allows you to use an animation of a clock in your loading screens in your own programs. If you have [[ScreenIO]] then FileIO will automatically detect it and use it to display a loading animation while the data in the data crawler loads.

Set AnimateDataCrawler to false (0) in your fileio.ini file to bypass the animations if you do have screenio but don't want to see the animations anyway.

==== TemplatePath$ ====
This setting points to the folder that contains the code templates used by the Generate Code button on the main page of the Data Crawler.

==== IgnoreLayouts$ ====
This is a comma delimited list of all layouts that you wish to suppress from appearing on the main page of the data crawler. You can still access these layouts with your code, but they won't be listed in the data crawler for you to access.

Whatever you're using for a log layout, is automatically added to this list.
==== CloseFileSimple ====
The fnCloseFile function closes all the individual handles to a data file that was opened for output using multiple keys.

For BR 4.18 and higher, we support a better algorithm for detecting which files are matches for a given opened file number.

Set CloseFileSimple to true (1) to force it to check the old way.

== FileIO Add-on Packages ==

Many FileIO Add-on packages are currently in the works.

=== ScreenIO Library ===

The [[ScreenIO Library]] is a sister library to the FileIO library. The ScreenIO library requires the FileIO library in order to run.

The ScreenIO library is a complete Rapid Application Design tool that enables you to implement custom screen functions anywhere in your exiting programs.

If you call the ScreenIO Library as a function library, you call a function called fnFM and tell it which screen you wish to use. The ScreenIO library loads your user interface, loads your data files, and preforms all the file maintenance operations you have designed into your screens.

You can find out the latest information about the ScreenIO library in the ScreenIO page.

=== Audit BR ===

The [[AuditBR|Audit BR]] developer tool makes a backup copy of your file layouts. Then you run some code you're trying to test, and finally, run Audit BR again, to get a report showing all the changes to any of your data files automatically.

AuditBR is now included directly in FileIO. To use it, select the layout from the list of layouts in the Datacrawler and press the "Compare" button.

== What’s New (also described above) ==
=== 2018 ===
*Support for dates in any storage formats on disk (v2.48)

=== 2015 ===
*Added Rec to display for fnShowData
*Added FormStatement$ for debugging of form statements inside fileio
*Added mat BadRead$ for debugging of 726 errors when making new layouts
*Fixed a bug causing crash when logging things from long program folders
*fnClientEnv$ - reads a Windows Environment variable on the client using the command shell
*fnAskCombo$ - added an optional parameter to set default selection.

=== 2010 - 2014 ===
*FileIO now caches your file layouts in memory to make it much faster then before when opening the same data file in multiple programs.
*Generate Layout Wizard
*fnShowData
*Improved Logging
*fnViewLogFile
*Import/Export
*Import/Export by Function
*Many other speed increases
*if ScreenIO is present, Datacrawler uses the animation routines
*fnBuildProcFile & fnRunProcFile
*fnGenerateLayout & fnWriteLayout
*fnReadForm$
*fnReadFormAndSubs
*fnGetFileDateTime$
*fnReadLayoutPath$
*fnSortKeys
*fnSetLogChanges
*fnLogChanges
*fnLogArray
*fnReadScreenSize
*fnEmpty
*fnEmptyS
*Many other useful functions that were added to the documentation at earlier dates.

=== Spring 2009 ===

'''''New Functions:'''''

The FileIO Library has been updated in Spring 2009 to provide several new functions:

*fnReadRecordWhere
*fnKey$
*fnBuildKey$
*fnReadUnopenedDescription$
*fnUpdateFile
*fnDisplayLength
*fnLength
*fnReadLayoutHeader
*fnReadEntireLayout

'''''Speed Increases:'''''

Thanks to the BR [[Profiler]], we have increased the speed of FileIO fnOpen function by ten times when running over a LAN and by 100 times when running over the internet using Client Server.

In order to get the new Speed Upgrades, you will need to make sure that you use the latest copy of the [[#fnOpen_Function|fnOpen]] function in each one of your programs that use FileIO.

'''''Network FileIO:'''''
This version of FileIO has been optimized to work better in network situations.

'''''FnSettings: '''''
There are more configuration options in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine.

'''''Automatic Update Speed Fix:'''''
The automatic update proceedure has been made to run more then 100 times faster then before according to our benchmarking tests.

=== Fall 2008 ===
'''''DataCrawler Grid:'''''

By popular request we added a read/write version to the data crawler. This version works exactly the same as the datacrawler did before but it displays all the contents of your data files in a grid instead of a listview.

When you run the fileIO library as a program, it launches a tool known as the [[#DataCrawler|DataCrawler]]. The DataCrawler shows a listview displaying all your layout files in it. If you select one, it builds another listview with all the data in your selected data file.

If you are looking at the first list of all your file layouts, and you press F5, a grid will be build displaying all the data in your data files. You can change any of the records you like, and when you're done, your changes will be saved to the data file. Additionally, you can Add or Delete records using the buttons at the bottom. Any changes you make are not written to the disk until you click the "Save" button. If you press ESC (Cancel) the grid is closed and all changes you made sinse the last save are lost.

This tool is for programmers only. Do not give your end users access to the DataCrawler.

Use the DataCrawler at your own risk. Gabriel Bakker and Sage AX are not responsible for any harm that comes to your data files through the use of this or any other tools we offer.

The DataCrawler is not designed to be used to maintain your data files. It can be used carefully to correct small things in your data files.

'''''Support for Nonstandard Paths:'''''

Many BR Vendors keep different versions of the same data files in different locations. For example, sometimes a BR vendor will use a different Data folder to represent data for different Warehouses, or Customers. In cases like this it is necessary for your programs to specify the path to your data files. They may do so by specifying the optional "PATH" parameter to your data files. See the section [[#fnOpenFile]] for more information.

'''''Support for Nonstandard Layout Files Path:'''''

Old versions of the fileIO library required you to place all your file layouts in a subfolder of your program directory called "filelay". We have now changed the Fileio library to allow you to place your file layouts any place you want. The only requirement is that they are all together in one folder by themselves.

If you use a nonstandard path in the fileIO library, it is necessary to make a change to the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code in your copy of fileio.br.

'''''Prompt on Create:'''''

The FileIO library automatically creates any data files that it can't find. This was done to make it easier to deploy your finished programs - if you had any empty data files you could omit them from the packages and they would be created when they were needed, on the fly.

The current version of the FileIO library contains the same ability. However, it prompts you before creating any data files. This helps to avoid bugs that happen from incorrectly specifying the path to your data files.

However, if you do intend for your data files to be autocreated, then you probably don't want your end users to modify them. Therefore, you can use the PromptOnCreate setting in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code to specify. If this value is set to true, then the fileIO library will prompt you whenever it attempts to Autocreate a data file. If it is set to false, then the fileIO library will create the data files without prompting you, like it always did before.

'''''fnSettings:'''''

The newest version of the FileIO library supports some features that require you to specify Global Settings values. These are done by modifying the contents of the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine at the beginning of the fileIO library.

=== Fall 2006 ===
Many improvements have been made in the FileIO library over the summer. This section is intended to acquaint you with the highlights of those changes. Most of these improvements were built from ideas generated during the discussion at the April conference.

'''''Intermixed String and Numeric Specs:'''''
The File Library has been expanded to allow the reading of data files that contain mixed string and numeric specs. This is to aid those of you who are planning on implementing the FileIO Library on existing data files which may not be organized with strings first and numbers second.

The central idea of the FileIO Library is based upon the reading of your data files into a String and Numeric array. This will enable you to refer to the fields in your file by using a named subscript, saying F$(FM_NAME) to refer, for example, to the farm file’s name field. The advantage to this is that when you change the file layout, all your existing programs will not have to be modified, because they will only be looking at F$(FM_NAME). If the name field changes from the third string field to the fourth, the value of FM_NAME will also change, and you won’t have to worry about updating your data files.

However, in order to support the reading of a data file with intermixed string and numeric specs, the generated form statement will actually calculate the position of any fields that are not in order, so that the file read statement will still return all string fields first (into your string array) and the numeric fields second (into your numeric array). You do not need to worry about this; the library does it for you. All you have to do is read your file and use the data values.

The only thing that is required is making sure that all your string subscript names end with a “$”. This will tell the library that they are strings. Thank you, George, for this suggestion.

'''''Versioning / Automatic Updates:'''''
The file layouts have been expanded to contain a version number. This version number will be used to determine when a file needs to be updated. The version number is the third parameter in the file layout.

Any time you wish to change your file layouts, simply increment this version number. Each time the library attempts to open a data file, the file’s version is checked and compared with the version in the file layout. If the file layout has been changed (if the version in the file layout is greater then the version in the file) then the file will be updated to the latest version. Depending on the file size this may take a couple of moments. A simple progress bar will be displayed on screen while this is happening. The progress bar will be displayed in its own window, so it should not affect anything your programs may have had on screen.

The library uses the following procedure for updating a file. First, the file is copied to a backup file (prefixed by the letter ‘o’ for old). So color.dat would become ocolor.dat, and color.key would become ocolor.key. Then the new file is created and marked with the proper version number. (color.dat, color.key). The old file is opened in read-only mode, and the new file is opened for OutIn. The update routine actually reads through the old file layout, and one record at a time creates a new record, using the new file layout, with the same data, saving it to the new data file.

When it is done upgrading, the progress bar window is closed, and the file is reopened in the fashion you described in your call to fnOpen, and flow returns to your program as though nothing unusual has happened.

If an error occurs during processing, the routine will do what it can to roll your data files back to the previous version, but please make frequent backups of your data files anyway, just to be safe.

'''''Error Checking – If there is a mistake in the file layout:'''''
The routine attempts to discover the cause of the error in the case that one is encountered due to a missing file, a file sharing violation, or an invalid or corrupt file layout. If this should happen, the program is paused, and a text message is printed out explaining the most likely source for the error, including what part of the file layout, if any, may have caused the error.

You may then examine the printed text, and the contents of the BR system variables ERR and LINE to determine the problem. If you type “GO”, the next line will be execute “system”, ending your program.

If the file was in the middle of an upgrade when the error happened, it will be automatically rolled back to the previous version, so that when you fix the problem and try to run your program again, the file will again attempt to update from the beginning, and you won’t have to worry about corrupted data.

However, please backup your data before upgrading your data files anyway, just to be safe.

'''''Implementation of Keys / Creation of New Data Files:'''''
The library has been expanded to automatically create all new data files, and to automatically update any existing files. This means that in the file layout header, two new fields that were previously ignored are no longer ignored. The RECL value that you specify in your file layout will be used, along with the description/definition of your keys file. When you open a new file (or update an existing one), the library will calculate the proper kps and kln by evaluating the key description. This key description must match up with subscript values from the data elements in your file, and more then one may be specified, but they must be separated with slashes (/). If I wanted my Farm File to be keyed based on CODE and NAME, the proper key description would be:

farm.key, CODE/NAME

The library will then look up the position and length on disk of the CODE and NAME fields and put them together to create the proper keys during an update or creation of a new file.

'''''DataCrawler:'''''
Perhaps the most exciting new addition to the library is the addition of a programming tool I like to call a DataCrawler. If you run the FileIO Library directly as a program, instead of using it as a library, it will function as a DataCrawler. The DataCrawler requires a New Gui version of BR, as it requires a ListView to be able to properly and easily display the data in your files.

If you run it in an older version of BR you will get a message, telling you to run it in a newer copy. If you run it in a New Gui version of BR with CONFIG GUI OFF, then GUI will be turned temporarily on for the use of the DataCrawler and then turned off again when you are finished. If you run it in a New Gui version of BR with GUI ON, it will just run normally.

When you run the DataCrawler, first you will see a ListView displaying every file layout it can find in the filelay folder. If you select a file, the DataCrawler will open a large ListView with as many columns as there are fields in the file. The Column Headings will come from the element descriptions in your data files, and the column widths will come from the displayed width of the fields. There will be a row for every record in your data file, and you can resize the column widths, and scroll around the data file to view the raw data of your BR data files on disk.

If you are dealing with a particularly enormous data file (50,000+ records) it can take a moment to populate the ListView with the data in your data file. You may hit ESC to stop loading if you like, and view only the already loaded records.

If you would like to look up a particular record (based only upon the primary key for the data file), you may press F4. This will give you a window which asks you to input the key or partial key. When you press enter, the file will be reloaded, starting at the key you specified and continuing on to the end of the file, or until you press ESC. The records you are looking for should appear at the top of the ListView.

To reset the ListView and look at the contents of the entire file again, simply press F4, and enter a blank (“”) key.

Finally, as with any ListView, you may resort your data by clicking on any of the column headings. Then you can use the slider bar at the right to scroll down to the record you desire.

This is a programming tool and is not designed to be used by an end user. This tool will open your file in read-only mode. It will not allow you to modify the data; I leave that as an exercise for the reader. However, it will update any datafiles you view to the latest version (if they need to be updated) when it opens them, just as any other program that uses the library will do.

== Appendix (Examples)==

=== Example.br ===
00010 ! example.br - This program is an example of for the data reading simplification
00020 ! Copyright April 2006 by Gabriel Bakker
00030 ! Distributed open source as a Christmas gift to brag members
00040 !
00100 execute "config gui off"
01020 DIM form$(1)*255
01030 DIM color$(1)*255,color(1)
01040 DIM colorcat$(1)*255,colorcat(1)
02020 library "fileio": fnopenfile, fnreaddescription$
04000 !
04010 Openfiles: ! Open your files here
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)
06000 ! gosub WriteFiles ! If you want to test this line, make sure to drop flag from 4030
07000 !
07010 MainBit: ! This'un here's tha Main Bit
07030 RESTORE #ColorFile:
07100 ReadNextcolor: ! Read next record
07120 read #ColorFile, using form$(ColorFile) : mat Color$, mat Color eof EndReadColor
07180 PRINT Color$(co_name)&" ("&Color$(co_html)&") is a member of the '";
07190 PRINT trim$(fnReadDescription$(ColorcatFile,cc_Name,Color$(co_category),mat Colorcat$,mat Colorcat,mat form$))&"' category."
07290 goto ReadNextColor
07300 EndReadcolor: ! Finished with Color File
08000 STOP
25000 !
25010 WriteFiles: ! Uncalled routine to demonstrate writing files
25105 let color$(co_code)="GD" !:
let color$(co_Name)="Gold" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFD700"
25110 write #colorfile, using form$(colorfile): mat color$, mat color
25115 let color$(co_code)="LV" !:
let color$(co_Name)="Lavender" !:
let color$(co_Category)="BL" !:
let color$(co_html)="E6E6FA"
25120 write #colorfile, using form$(colorfile): mat color$, mat color
25125 let color$(co_Code)="OR" !:
let color$(co_Name)="Orange" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFA500"
25130 write #colorfile, using form$(colorfile): mat color$, mat color
25205 let colorcat$(cc_Code)="YL" !:
let colorcat$(cc_Name)="Yellows" !:
let colorcat$(cc_html)="FFFF00"
25210 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25215 let colorcat$(cc_Code)="BL" !:
let colorcat$(cc_Name)="Blues" !:
let colorcat$(cc_html)="0000FF"
25220 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25300 return
40000 !
40010 Open: ! ***** Function to call library openfile and proc subs
40020 def fnOpen(FILENAME$, MAT F$, MAT F, MAT FORM$;INPUTONLY,KEYNUM,___,INDEX)
40025 dim _FileIOSubs$(1)*50
40030 let fnopen=fnopenfile(FILENAME$, MAT F$, MAT F, MAT FORM$,INPUTONLY,KEYNUM,MAT _FileIOSubs$)
40040 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
40090 fnend
50000 !
60000 Ignore: Continue

Color File Layout
color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

ColorCat File Layout
colorcat.dat, CC_, 0
colorcat.key, CODE
recl=127
===================================================
CODE$, Category Code, C 6
NAME$, English Name for Color, V 30
HTML$, HTML Code for the Color, C 6

Example Layout showing multiple keys (price)
price.dat, PR_, 0
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2

[[Category:Utilities_Third_Party]]

FileIO Library

2024-09-11T21:52:57Z

Gordon.dye: /* File Layouts */

The '''FileIO''' Library began as a project to find a way to reduce the effort associated with making changes to data file layouts. Thanks to the Fileio library, when I have to make a change to a data file layout for my customers today, I can complete the task in under 1 minute, and not a single program needs to be changed in order to continue working with the new file layout. In fact, I don’t even have to update my customer’s data files, as the FileIO library takes care of this for me as well.

The trick is to define each of your file layouts in an ASCII text file layout file that is described below. The FileIO Library will parse through your file layouts, and it will instruct your programs how to access the file data after it has been read. It will also automatically detect when you make changes to the file layout, and it will update your customer’s data files on the fly to make sure they have the latest version. Finally, it contains a DataCrawler that you can use to examine the contents of any of your BR data files in a raw format.

For more information about the FileIO Library visit the [http://www.sageax.com/products/fileio-library/ Sage AX Website]

To download the latest copy of FileIO, click [http://www.sageax.com/downloads/FileIO.zip here.]

== Method of Operation ==
The file IO library parses a formatted text file layout and uses this information to structure the opening and the reading of a file “object”. The word object here is used to refer to all the data in a given record layout in one of your files. This library is easy to use, and provided you follow some simple standards, it will simplify your life immensely.

Your programs will need to define one array for all [[Form|BR data file form statements]] and add a snippet of code (given below) to the program for interfacing with with the library. For each file you will need to define a couple of arrays and use the library to open them. From that point on access to data is simple and direct.

=== File Object Arrays ===

First, in your program you must create two arrays to store the file information. If we are dealing with the Color File these would be MAT COLOR$ and MAT COLOR. One will store all the string information about a color, and the other will store the related numeric data. Our working example will involve two files: a Color File and a Color Category File. You should dimension these as follows:

01030 DIM color$(1)*1000,color(1)
01040 DIM colorcat$(1)*1000,colorcat(1)

We're dimensioning the string array elements to 1000 bytes each. This is the length of one field in the color file. The array element length needs to be at least as big as the largest string field in the data file.

However, it is recommended to make sure the length is long enough to handle any field you might eventually add to the file at any point in the future. BR supports multi-line textboxes, so I sometimes add long memo fields to my data files that might be 400 or 800 or even 1000 characters long, therefore 1000 is the length I use now in all my new development.

But anything will work as long as its long enough to handle the largest data field in your file.

=== Forms Array ===

Your programs will need a string variable array to store the form statements associated with reading files. This form statements array will be dynamically generated or expanded whenever the a file is opened. It will say:

01020 DIM form$(1)*255

This form statement will be compiled by the FileIO open statement. BR limits all compiloed form statements to 255 bytes, so 255 is sufficient to hold the compiled Forms$ statements.

=== Library Linkage ===

You will also need the library statement:

02020 library "fileio.br": fnopenfile, fnreaddescription$

=== fnOpen Function ===

Now, add the following snippet of code to interface with the library. Note that this snippet can be copied in exactly as provided and no customization of it is needed.

Because BR libraries do not share global variables with the programs they are called from, we will need to execute a procedure file whenever we open a file - to set the names of all of our variables. Add the following snippet of code into your program. It will create an FnOpen function that calls the library and runs the proc file. The $$$ at the end of the procfile name tells the procfile to self-destruct after execution. Since this procfile is used simply to return variable information back from the library to the main program, we don’t need it sitting around collecting dust.

99010 OPEN: ! ***** Function To Call Library Openfile And Proc Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
99030 dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
99050 if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
99060 fnend

Or, for those with [[Lexi]]: (same but without line numbers)
OPEN: ! ***** Function To Call Library Openfile And Proc Subs
def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
fnend

=== Using FileIO in Your Programs ===
Now you are ready to process files. 
'''''You simply open the files by saying:'''''

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

'''''read each file as follows:'''''

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
'''''and access the data:'''''

30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name)

=== How it Works ===
The above statements tell the File Library to look in the filelay folder to find the file layout for the Color File, and read it to find out what the Color File looks like. Then it OPENs the Color File, and sets MAT COLOR$ and MAT COLOR to the correct number of elements to hold an entire color record. Finally, it will define several variables that we can use as pointers (subscripts) into these arrays to access the data read into the 2 arrays, and it will assign the file handle to a variable called "colorfile".

The second open statement above will do the same thing to the color category file, except the parameter value "1" tells the function to open readonly. The array subscripts assignment procedure file (passed back from Fileio) will be executed, thereby assigning values to the subscript names in the calling program. So, if I had a file layout such as the following:

color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

Then the functions would do the same thing as the following individual lines of code (assuming the next available file handle was 5):

DIM FORM$(5)*255
DIM COLOR$(9)*1023, COLOR(1)
OPEN #5: “Name=color.dat, kfname=color.key”,internal,outin,keyed
LET FORM$(5)=”form C 6,V 30,V 6,C 6”
LET FORM$(5)=CFORM$(FORM$(5))
LET COLORFILE=5
CO_CODE=1
CO_NAME=2
CO_CATEGORY=3
CO_HTML=4

The data is used by referencing the file array, with the subscript name, so the color’s description becomes color$(co_Name).

In the old days, if we wanted to change the file layout of our file, all of the programs that used that file would have to be changed one at a time to use the new file layout. Also, if the order of the fields changed, then all the programs would have to also be changed to use the new fields.

But now, using this function, we can change the file layout all we want. If we later want to insert a field into the file layout before color name, I won’t have to look at this program again; this program will just work fine, because the library maps the subscripts to the actual fields.

Also, the code is easier to read and maintain.

=== Example ===
The whole thing looks like this:

01025 ! Dimension the Arrays
01030 DIM color$(1)*1023,color(1)
01040 DIM colorcat$(1)*1023,colorcat(1)
01050 DIM form$(1)*255
02000 !
02020 library "fileio.br": fnopenfile, fnreaddescription$
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$) ! Open the file
05000 !
30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore ! Read the file
30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name) ! Use the data by referincing it in the file arrays
80000 !
90000 ! Every program using fileio needs the following code
99010 OPEN: ! ***** Function To Call Library Openfile And Generate Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths)
99030 dim _FileIOSubs$(1)*800
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$)
99050 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
99060 fnend

== File Layouts ==
Now lets inspect the anatomy of a properly formatted file layout. These should be placed in a subdirectory called filelay.
In this example, a farm management system uses a price file to manage seasonal prices:

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...
<hr>
price.dat, PR_, 1

The first line contains the name of the Farm Record, a unique string to prefix all of your subscript pointers, and the file version number. The subscript prefix is to ensure that the program knows the difference between the Farm File’s Farm Code, and the Route File’s Route Code. (One will be RT_CODE and the other is FM_CODE). These are separated by a comma. Spacing does not matter, so adjust your spacing so that it looks nice.

The Version number is used to determine when the data has changed, and an update needs to be made to your data file. Your file layouts should all start at version 0, and each time you want to make a change, you may increment this value by 1.

Each time you open a file with the FILEIO library, it reads the file version number of the file on disk (using the BR version() function), and then it compares it to the version number in your file layout. If your file layout has a higher version number then your existing data file, then the library opens the backup of the file layout for the version of the data file that exists on disk. It makes a backup copy of the existing data file, and creates a new file with the proper version number. Then it reads your records one at a time, and copies all the data from the old file into the new file one field at a time. If a field is dropped from the file layout, that data gets lost. If fields are rearranged, the data is copied and saved in the new file in the new positions. If a new field is added, it starts out blank (or 0).

If you look in the filelay folder, you will notice a version folder. This contains several files ending with a number. For example you may see a color.0, and a color.1 file.

If you run the fnopen function and it can not find your data file (usually because this is a new file and it hasn’t been created yet), ''the library will automatically create your file,'' based on the information you give in the first part of the file layout.

Also, whenever you make changes to your file layout, the function library will automatically update the data files on disk for you. It does this by renaming the old file, creating a new one with the new version number, and then copying the data from the old one to the new one a record at a time.

Any time it creates a file, or updates the file on disk, it creates a backup of the file ''layout''. The first time you run a program that tries to read your new data file, it will create the data file for you and make a backup of the layout, and if the number in your file layout is 0, then it will create, for example, a filelay\version\price.0 file, a backup of your file layout that the library uses to figure out what has changed the next time you try to update the file.

If you wish to make any changes to this data file, first you increment the version number, (in this case make the 0 into a 1). Then change the file layout all you want. You may rearrange fields, add new fields, add or remove keys, or change the record length.

The only step necessary for having your data files updated is to increment the version number every time you make a change to the file layout.

You may make any changes you like to the file layouts, but do not change the names of your existing subscripts. If you change the subscript name, not only will all the programs that reference that subscript be broken, but additionally, the routine will not understand that you are changing the name. It will think you are dropping the old field and adding a new field and any data stored in this location will be lost when the file is updated.

price.key, FARM

The second line contains the name of the first key, and a definition telling what the key is based on. These are separated by a comma. The key definition is made up of each of the subscript names in this file that form the keyfields for the file. When the library is called to open a file, if the file does not exist, or if it needs to be updated, a new one will be created. The function will read these subscript names that form your key definitions, and it will calculate the proper key position (KPS=) and length (KLN=) values. Then the create routine will use this information with the Index command to create the new key files.

price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127

Notice that the third key is based on three different fields. These are separated by a “/”. It is important that you use a “/” to separate your keys when you are building a key out of more then one field, because the function uses this “/” to help it make the proper BR syntax for defining complex key fields.

Also, note the "-U" at the end of the fieldname in the 4th key. This indicates that the "Description" part of that key is case insensitive. This translates to using the "U" on part of your key spec in Business Rules.

The file can have as many keys as you want. The function will keep parsing key file names until it reaches the next part of the layout. It opens any OutIn files with all keys so that any changes you may make to the data stored on disk will be properly reflected in all the key files.

The optional RECL= Parameter is read and used whenever a new file is created or an old one is updated. If it is not specified, the record length is calculated from the fields in the layout.

===================================================

The next line in the file is skipped by the parsing routine, and its purpose is to make the file layouts more readable to a programmer.

 
FARM$, Farm Code (or blank), C 4

Following the file and key structure, the fields are defined. There are three parameters on each field definition line, and you make one line for each field in your file layout. The first parameter is the subscript name that you will use in your program to refer to this data element. Place a $ at the end of the subscript name for all string elements. Don’t place anything at the end of the subscript name for numeric elements. Note that each of these names will be prefixed by the second parameter of the very first line of this layout.

The second parameter is the description. This description is for the benefit of the programmer, so when the programmer is reading the file layouts, (s)he can tell which field does what. The spaces are ignored, so you may include as many spaces as you wish to make the layout look good. It does seem like good general guidelines would be to limit your layout lines to 255 characters and your descriptions to 80.

The description is also used by the built in DataCrawler, a program that reads any of your data files and displays the entire contents in raw form in a listview. The Descriptions become the headings for each column in the listview.

Those descriptions are also used for the default captions for your fields if you use ScreenIO, a library for building GUI programs that itself builds off of fileio.

The third parameter is the form statement, which is pretty straightforward. Any items with a form statement of type “X” will be ignored, except that the length will still be used to calculate the position on disk of all remaining fields in the record. The library will take X fields into consideration when building the form statement, but not at any other time.

The fourth parameter is optionally a [[#Support for Dates|Disk Date Format]]. You can specify DATE(Julian) if you're storing your dates in Julian format on disk. Or you can specify DATE(cymd) or DATE(ymd) or DATE(mdy) or any other valid date spec here, and FileIO will treat this field like a date.

Your programs will still have to unpack it for you, fileio can't do that because fileio doesn't read the file for you.

However, the data crawler, the automatic updates, and screenIO, are all compatible with these dates specified in your file layout.

If the fourth parameter is anything other then DATE(format), then its treated as a comment and ignored.

The fifth and all later columns, if any, are treated as comments and ignored.

! default cost is normally zero
Comment line text must begin with an exclamation point, but it may be indented. Comment lines may appear anywhere (vertically) and are ignored. 
Blank lines are ignored as well.

#eof#
additional comments...
After the last field definition, an ''optional'' #eof# line may be specified, in which case any lines after that will be ignored.

 
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...

And that’s all there is to it.

=== Support for Dates ===
As of V2.48, file layouts support dates in any storage formats on disk. Whether you store your dates in Julian or in YMD or MDY or any other format, specify so in the 4th column of your file layouts, using the FileIO Date Keyword. ex: DATE(Julian) or DATE(YMD) or any other valid BR Date Format.

[[File:Dates0.png]]

When this is specified, it enables the FileIO data exploration tool (Data Crawler) to display the dates in human readable format. This works for both Viewing, and for Editing.

The new Date functionality also supports the File Layout Upgrade facility, allowing you to change the format of your dates on disk and FileIO will handle it automatically, upgrading the field to use the new date format for you.

It works also for Exporting your data files to CSV, and is supported automatically in the FileIO functions that do those exports. It converts the dates on export to a standard format (Default: m/d/cy) that you can specify in your FileIO.Ini File.

And it extends ScreenIO's date features to all date fields, no matter what format they're stored in. (Previously, ScreenIO's advanced date features only worked for dates stored in Julian on disk.)

This update adds two new ini file options:
CODE: SELECT ALL
DateFormatExport$='m/d/cy' ! Format of Dates when Exporting to CSV
DateFormatDisplay$='m/d/cy' ! Format of Dates when displaying in Data Crawler

You can use these to specify your preferred Date format for Viewing/Editing, and your preferred Date format for Exporting.

Remember, you can see the full list of FileIO ini file options, by looking in the source code at the top of FileIO.

There is a new optional parameter for all layout reading functions, mat NDateSpec$ and mat SDateSpec$ which correspond with the other arrays, to let you know which fields are date fields, so that you can develop routines in your programs to automatically pack and unpack the dates.

Important Note: Using FileIO, the reading of the data file is still done directly in your programs. So this does not change how your existing programs work. It does not unpack the dates for you in your programs. You still have to do all that.

For this reason, upgrading to the new Date processing will not break any of your current code.

=== Debugging Tips ===

When you're making new layouts, a missing comma can cause FileIO to parse the layout wrong and give you errors. Here are a couple tips to help ensure your layouts are error free before using them in your programs.

*Use the Data Crawler to test your layout. The data crawler is the simplest way to test your new layout without writing any code. It opens it and accesses the file in a very simple and straight forward manor to help identify any errors in the layout that you might have.

*If you have trouble with the form statement, you can't see whats in it because FileIO uses CForm$ to compile your form statement to make your programs run faster. But here's a way to tell what the original form statement was that FileIO generated when it put the strings first and numbers last in your program: Open the file in the Data Crawler. When you get an error, type "Print FormStatement$" to see the original form statement.

This works even if your file is working fine. Any time the file is opened with the data crawler, you can press CTRL-A and then type PRINT FormStatement$ and it will print out the uncompiled form statement for the file.

== Utilities ==

Now that you have your file layouts defined, you have access to several powerful utilities right out of the box using Fileio. Additionally, several more utilities are available as [[#FileIO_Add-on_Packages|Add-Ons]], including our most popular development tool [[Screenio|ScreenIO]]. You can read more about them in their section below.

But for now, lets take a look at some of the wonderful free utilities that come built into Fileio.

Some of these utilities are accessible from your code via library functions, but the primary way you access any of them is by simply loading the FileIO Library and running it directly.

=== DataCrawler ===
The data crawler is the original utility of FileIO. This utility shows you first a list of all data files allowing you to select one.

Select a data file and press enter, and FileIO will then display a listview containing all the data in the data file. This list is sized based on the size of your main BR window (window 0) automatically to take up the full size available to it, so if you want to see more, try [[Open Window|opening window 0]] larger before running FileIO.

At the top of the window is a filter box, and you can type anything you want in there and click "Refresh" and it will reread the data file, shortening the list to show only those records that match (case insensitive) what you have typed.

If you have ScreenIO installed, then FileIO's data crawler will take advantage of the included Animation Engine in ScreenIO to animate a loading window while the listview is displaying. If you don't have ScreenIO then FileIO will simply load the listview.

If you don't want to wait for the entire file to load, press ESC to stop the load process.

If the file is empty, FileIO will display a message box letting you know.

This tool is very useful for sorting out data errors. It will allow you to look inside any data file you have a layout for and directly view the data there.

At the bottom of the Data Crawler are several buttons. There's a Jump button that repositions the file by a key you specify and then loads the list with the data from that key on down to the end of the file.

There is a "Columns" button which you can use to decide which columns should show up on the listview. Fewer columns means faster loading so sometimes for large files I press ESC immediately when the file first starts loading to cancel the load. Then I click "Columns" and check only the columns I want to see. Finally I press the "Refresh" button to trigger it to read the file again and this time it loads much faster then before.

Next you'll find an Export button which starts the process for exporting a file to CSV. You can read more on that in the next section. And next to that is a Quit button.

In this example, we loaded the file "Read Only" so it put everything in a listview. But there are times when its useful to fix data errors this way too, especially during development. So if you want to directly edit your data file, on the first page select the file you want to edit and instead of pressing "Enter" or clicking "View", this time press "F5". F5 is the secret Edit button that loads a data file into a grid instead.

You can use the grid to change records, delete them or add them, and in addition to the buttons listed above, it also has an "Import" button for importing a CSV file into this data file.

Any changes you make to the data file are not saved until you click the "Save" button (which also only appears when you're in Edit mode).

In the 01/2015 release of FileIO, each records rec # is displayed in the listview, to aid in debugging bad data problems.

==== Debugging Tip ====
Any time you're viewing a file layout in the Data Crawler, you can see the Uncompiled Form Statement by pressing CTRL-A to get to an ATTN prompt, and then entering the command:

print FormStatement$

and it will print out the original form statement.

==== Another Debugging Tip ====

The FileIO Datacrawler ignores records that it cannot read. This is to allow for data files that have multiple record layouts in one data file. You make a custom layout for each record type and the data crawler shows just the records that match that type in the file.

However that becomes a problem when you're making a layout to work with an existing data file. Error 726 indicates that something minor in the file layout doesn't match the data on the disk, but these errors are ignored so you might see either an empty data file, or a data file with some records missing. If that happens, you need to see the missing records in order to figure out what is wrong with your layout. '''''It's very important that you don't try to use a file layout that isn't quite working right. Make sure your layout works and can read every record of a file that it should read before using it.'''''

To see the records that could not be read in a file, run the data crawler on the layout, then press CTRL-A to get an ATTN prompt. From there, enter the command

print mat BadRead$

and it will print all the records that were ignored because the file layout didn't match them. It prints out the raw data from the file.

==== Function Access to use Data Crawler in your programs ====
You can use the data crawler in your own programs by using one of the following functions:
* [[#fnDataCrawler|fnDataCrawler]] - Open a Listview showing the data file
* [[#fnDataEdit|fnDataEdit]] - Display the data in an editable grid
* [[#fnShowData|fnShowData]] - This function does the same thing as the above two, but with many many more options allowing you to customize exactly what appears and exactly what they're allowed to change.

Note: its not recommended to allow your customers to use the data crawler to access your data files directly. There's no way to specify validations or do anything complicated, so unless you're careful, there are lots of ways your customers could use this tool to do damage to your data files. It is a programmer tool only.

If you do decide to use it for your end users, be careful how you implement it.

=== Import/Export to CSV ===

You can use FileIO to export your data files to CSV or import from CSV into your data file. To do this, you want to run the data crawler and select the file layout you're looking for. Then, view it (or press F5 to edit if you want to import something). Click on the Export button and it will ask you to select a file. Once that is selected it will ask a couple other simple questions, and when you've specified the options to your satisfaction, click the Export! button. A new CSV file will be created.

Import is even more simple. To import, you must be in Edit mode (press F5 to select the file instead of the enter key) and then simply select the Import button. It will ask you again to choose the file, and then it will ask you if it should update all files by Record Number (if record number is recorded in the CSV file) or by Key (if the file has keys) or to just Add all information to the file. Select what you want and press Import and the CSV file is added to the BR data file.

==== Function Access to Import/Export from your programs ====

You can use the following functions to call the Import and Export functionality from your code.

*[[#fnCSVImport|fnCSVImport]]
*[[#fnCSVExport|fnCSVExport]]

These functions are intended to give you the ability to use our functionality to write your own import and export routines for your customers, because its not a good idea to let your customers run the Data Crawler.

=== Generate Layout Wizard ===

There is also a Generate Layout Wizard utility in FileIO. This utility is there to help you build your file layouts. It is designed to work with a certain style of BR programming that was common in the 80s and 90s. So if your software is written in a style that opens the file directly, and reads/writes the data to a long series of individual variables, the Generate Layout Wizard is for you.

To use it, start by running FileIO. Then, don't select a layout - instead, click on the "Generate Layout" button.

You'll see a screen with a bunch of large text boxes, a small grid, and some buttons.

The first thing you want to do is select the "Browse" button and then select a .wb or .br file that contains a program that reads or writes Most of the File.

When you select one, press the Scan All button and it fileio will search the whole program looking first for all the open strings. It will take the file that is opened the most times and then search for all read statements to that file. It will look for the longest read statement and then find the Form statement associated with that Read statement, and any DIM statements for any variables used.

If you don't like the file its chosen, click the "Open Scratch Pad" button to open the temp work file it uses into the program of your choice (I use myEdit for BRS files). Simply select all the open statements for the file you DO want to build off of, then click the Paste button to paste those open statements into the "Open String" list. After that click "Clear All" to erase what it did on the first search and then click "Scan All" again to rescan the program using this new data file.

You may have to help it a bit, but once it has a proper matching open statement, read statement, form statement and dim statements for any arrays used, press the "Generate Layout" button and it will build a layout for that file.

Finally, load the layout it built and clean up anything if you want, and consider adding better descriptions for each of the fields that you know (as it will use the variable names for both the subscripts AND descriptions in the layout).

When you're all done, click "Done".

==== Functions to Generate Layouts from your code ====

* [[#fnGenerateLayout_.26_fnWriteLayout|fnGenerateLayout]]
* [[#fnGenerateLayout_.26_fnWriteLayout|fnWriteLayout]]

=== Code Templates ===

One more tool FileIO has to help is the ability to generate code based on your file layouts.

Run FileIO and this time select a file layout and press "Generate Code". A window will pop up listing all the "Code Templates" that are available. Select one (and then select a key if it asks you - some templates require extra info). It looks like nothing happened, but the code you generated is now in your clip board. Paste it somewhere and take a look at it!

Code Templates help us to standardize our ways of doing things, which eventually leads to more and more powerful tools we can use. Code Templates also help ensure we use cleaner code by doing some of the busy-work of writing clean code for us.

==== Writing Code Templates ====
FileIO ships with several basic code templates. If you want to add your own, take a look in the filelay\templates folder (configurable in fileio.ini) and look at basic.brs. Copy it to your own program and then modify it to have your own code templates in it. Write me at gabriel.bakker@gmail.com with any questions. I want to help.

And if you write good code templates, its easy to share them with the BR community. Anyone can download your templates and place them in this folder and they'll instantly be available for use.

== FileIO Function Reference ==
''The FileIO Library contains a number of other useful functions.'' The following functions are available and you are welcome to use them:

=== Primary Functions ===

==== fnOpen ====
fnOpen is the primary function that opens a file, and it’s used like so:

''def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, DontSortSubs, Path$*255, Mat Descr$, Mat FieldWidths, SupressPrompt, IgnoreErrors, SuppressLog)''

Note that all of the parameters after MAT Form$ are optional. If you need to specify a parameter in the middle of the optional parameter group, just list zeroes and empty strings for the intervening unused parameters.

*FileName$ - The filename of the file layout for the file you’re reading.
*MAT F$ - The array that will be used to hold the string data for the file.
*MAT F – The array that will hold the numeric data for the file.
*MAT Form$ - An array of form statements.
*InputOnly – 1 means open for input only. 0 means open for OutIn and open every key file associated with the given data file (this is because all key files need to be open for the keys to be updated on an output) (defaults to 0). Files opened for input process considerably faster than files opened for output. Furthermore when files are opened for input only, alternate key files are ''not'' opened.
*KeyNum – This tells the function of which key to return the file handle (defaults to 1). Specify -1 to force the file to open Relative, without using its keys. If a file has no keys, it will always be opened Relative.
*DontSortSubs – The function by default, when compiling the Form statement, will sort the string and numeric subs in order to allow for reading the data into an array, and this parameter would turn this functionality off. However, if you are trying to read your data without reading it into an array, you are missing out on some serious efficiencies. You should normally leave this option turned off (0). This is a totally unsupported feature, and should always be set to 0, if it is specified at all.
*Path$ - The path to your data files. This optional parameter can be passed in by the calling function. It is prefixed to the beginning of the paths given in the file layout files. It is useful when your data files can be in different locations depending on the state of your program.
*mat Description$ - This optional parameter provides a way to read the description for each field from the original file layout. If the parameter is not provided, no description data will be returned.
*mat Fieldwidths – This optional parameter will return an array of the calculated display field widths. This number will always be at least large enough to contain the data for this field.
*SuppressPrompt - This optional parameter can be used to suppress the prompt normally given when fileIO creates a file. It can have three values. A value of 0, the default, uses the setting stored in your FileIO fnSettings routine to determine weather or not to prompt on Creation of a new file. A nonzero value always suppresses the prompt. A value of 1 indicates never to create a file if the file doesn't exist. A value of 2 automatically creates the file if the file doesn't exist.
*IgnoreErrors - Normally when fileio opens a data file, if there are errors trying to open the file, it prints them out to the debug console and pauses so that you can try to find out whats going wrong. If you specify 1 for "IgnoreErrors" it will cause Fileio to log those errors instead, and continue loading your program. This will result in the fnOpen file function returning Zero instead of the opened file number, so if you use IgnoreErrors, you need to test to make sure that fnOpen returned a file number before you try to access the file.
*SuppressLog - this optional parameter can be used to suppress writing to the log file for this one specific open statement. I use it for files that will be opened all the time, for example, the menu data file on one of my customers systems. Without this boolean parameter, his log file is quickly filled up with useless information any time his employees look at his menu. I specify this optional parameter to suppress logging anything about the menu file so that I can more easily find the actual programs they've used when looking in the logfile.

'''''Note: When using fnOpenFile, you really want to call your local function fnOpen, which in turn calls fnOpenFile for you.''''' FnOpenFile is for internal use only.

Example:

Let FFILE=FNOPEN(“FARM”,MAT FARM$,MAT FARM,MAT FORM$,0,2)
Let RFILE=FNOPEN(“ROUTE”,MAT ROUTE$,MAT ROUTE,MAT FORM$,1,3)
Let CFILE=FNOPEN(“CUSTOMER”,MAT CUSTOMER$,MAT CUSTOMER,MAT FORM$)

assuming:
farm.dat has 3 keys: farm.ky1, farm.ky2, farm.ky3
route.dat has 4 keys: route.ky1 … route.ky4
customer.dat has 2 keys: customer.ky1, customer.ky2

This will perform the following opens and set the following variables:

OPEN #1: “Name=Farm.Dat, kfname=farm.ky2”,internal,outin,keyed
OPEN #2: “Name=Farm.Dat, kfname=farm.ky1”,internal,outin,keyed
OPEN #3: “Name=Farm.Dat, kfname=farm.ky3”,internal,outin,keyed
OPEN #4: “Name=Route.Dat, kfname=route.ky3”,internal,input,keyed
OPEN #5: “Name=Customer.Dat,kfname=customer.ky1”,internal,outin,keyed
OPEN #6: “Name=Customer.Dat,kfname=customer.ky2”,internal,outin,keyed
LET FFILE=1
LET RFILE=4
LET CFILE=5

This will also resize the arrays, set the form statement, and create all the subscripts to make accessing the data clear and simple, as in the above example. The KEYNUM parameter is where you list the key file you would like to use for reading and writing. The extra keys are opened to ensure that all keys get updated properly when the file is changed.

Example:
DIM FORM$(1),PRICE$(1)*255,PRICE(1),
DIM DESCRIPTION$(1)*80,FIELDWIDTHS(1)

Let PRICEFILE=FNOPEN(“PRICE”,MAT PRICE$,MAT PRICE,MAT FORM$,0,2,0,"",MAT DESCRIPTION$)

Assuming the Price File layout (filelay\price) contains:

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30

This will perform the following opens and set the following variables:

OPEN #1: “Name=Price.Dat, kfname=Price.ky2”,internal,outin,keyed
OPEN #2: “Name=Price.Dat, kfname=Price.ky1”,internal,outin,keyed
OPEN #3: “Name=Price.Dat, kfname=Price.ky3”,internal,outin,keyed
let PRICEFILE=1
let PR_FARM=1
let PR_ITEM=2
let PR_GRADE=3
let PR_DESCR=4
let PR_PRICE=1
let PR_COST=2
let PR_XOPRICE=3
let PR_XOCOST=4
let PR_MOPRICE=5
let PR_MOCOST=6
let PR_VOPRICE=7
let PR_VOCOST=8
MAT FORM$(1)
MAT PRICE$(4)
MAT PRICE(8)
MAT DESCRIPTION$(12)
MAT FIELDWIDTHS(12)
let FORM$(1)=CFORM$(”form C 4,C 4,C 4,POS 74,C 30,POS 50,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2”)
let Description$(1)= “Farm Code (or blank)”
let Description$(2) = “Item Code”
let Description$(3) = “Quality”
let Description$(4) = “Description of Price Rule”
let Description$(5) = “Default Price”
let Description$(6) = “Default Cost”
let Description$(7) = “Default Christmas Price”
let Description$(8) = “Default Christmas Cost”
let Description$(9) = “Default Mothers D Price”
let Description$(10) = “Default Mothers D Cost”
let Description$(11) = “Default Valentine Price”
let Description$(12) = “Default Valentine Cost”
let FieldWidths(1) = 4
let FieldWidths(2) = 4
let FieldWidths(3) = 4
let FieldWidths(4) = 30
let FieldWidths(5) = 8
let FieldWidths(6) = 8
let FieldWidths(7) = 8
let FieldWidths(8) = 8
let FieldWidths(9) = 8
let FieldWidths(10) = 8
let FieldWidths(11) = 8
let FieldWidths(12) = 8

There are a few things I’d like to point out about the example above. First, you will notice that the form statement jumps around to put all the strings first, and then the numbers last. This is why it has a “POS 74, C 30,POS 50”. Then notice that the subscripts for the string variables are 1 .. 4, and the subscripts for the numbers are 1 .. 8. Finally, the order of the Description and FieldWidth fields also match the sorted positioning of the Form Statement.

The reason that we sort our form statements is so that BR will allow us to read the file into arrays by saying:

Read #pricefile, using form$(pricefile) : mat price$, mat price

Without resorting, the above statement would give a conversion error as BR attempted to put the PR_PRICE field inside mat price$(4). However, because we have reordered the form statement, we are able to read them safely into two arrays, and then we will be able to use the values without caring what position they are in the file, by simply saying PRICE$(PR_DESCRIPTION) when we want the description, and PRICE(PR_PRICE) when we want the pr_Price field.

Another thing you may notice about the above example is that it gives the calculated display length for the numeric fields as 8, when on the disk (and in the file layout) they are listed as BH 3.2. The reason for this is the program looks at the BH 3, and figures that a number that takes up 3 bytes on disk has a potential maximum size of 256**3 or 16,777,216, and therefore will need up to 8 characters of screen display space to view.

Finally, note that any field with a form statement of X is ignored by the library, except that the blank space is used when building the FORM statement.

==== fnCloseFile ====
This function will close the specified file number and all keys that were opened with the file. The purpose of this function is to facilitate the closing of the extra keys that are opened when you open a file for OutIn with the library. There is no need to use this for files opened for input because it is easier to just close the file directly. Secondary keys are not opened by FileIO for files opened for input only.

You must give the function the name of the file layout. It uses this information to determine how many keys were opened, and how many it must therefore close.

Then it basically starts at the file number you gave it, and closes the next X files that were opened with the same file name as this, where X is the number of keys associated with this file.

The syntax is:

''fnCloseFile(filenumber,filelay$;path$)''

*FileNumber – The filenumber of the file you are trying to close.
*FileLay$ - The name of the file layout for this file. This is used to determine how many keys the file would have been opened with and therefore how many we now need to close.
*Path$ - Optional Alternate Path. Use to close files that were opened using the open file's optional alternate path parameter.

==== fnGetFileNumber ====
FnGetFileNumber is a simple function to find a valid unused file handle. If you use this function in all of your programs, they will become much more portable, as you will never have to worry about your file handles fighting with each other. The function will return 0 if no free file number was found (but with 999 of them available now, I have never seen it happen).

''fnGetFileNumber(;X,Count)''

*X – This optional parameter will specify where to start looking.
*Count - This optional parameter will specify how many file numbers to find in a row. If count is 3, then fnGetFileNumber will return the first filenumber in the first gap of three unused file numbers that it finds.

=== File Reading Helper Functions ===

These functions perform various useful calculations to aid in interacting with data files when you're using fileio.

==== fnBuildKey$ ====
This function will return the key for a given record in a data file. It actually reads the file layout and builds the key to match the layout.

''FnBuildKey$(Layout$, Mat F$, Mat F; Keynum)''

*Layout$ - the name of the data file to build the key for.
*Mat F$ - the string array of the file object
*Mat F - the numeric array of the file object
*KeyNum - This optional parameter specifies which of the key files in the given layout the key should be built for.

To use this, you want some code like in the following example:

mat customer$=("") : mat Customer=(0)
let customer$(cu_name)=CustName$
let customer$(cu_phone)=CustPhone$
read #customer, using form$(Customer), key=fnBuildKey$("customer",mat Customer$,mat Customer,2) : mat Customer$, mat Customer nokey KeyNotFound
! The above code assumes that the second key of the Customer file is based on the Name and Phone fields.

By using this logic you are able to avoid directly specifying the key in your code - which means that even if the key changes in the future, as long as your code specifies enough information, it will still find the correct key. In our example, even if we dropped the phone number from the key in the future, or even if we expand the length of the Customer Name field, our code would still work and fnBuildKey$ would still build the correct key without us having to look at or change our code again.

This kind of reasoning is central to the fileio system, which, when implemented properly, ensures that you can change your data files in any way you need to in the future, without breaking your existing programs.

==== fnUniqueKey ====
This function tests to see if a given key is unique to the specified file. This function is very useful for situations where you need to ensure that the user-entered key is unique.

''fnUniqueKey(Fl,key$*255)''

*FL – The file number of the opened file.
*Key$ - This is the key to test. If this key is the key for a preexisting record in the file, the function will return false. If this key can not be found in the file, the function will return true.

==== fnMakeUniqueKey$ ====
This function generates a unique key for a given file. This is useful if you do not care what the key is, but it needs to be unique. I use this function in situations where the user never needs to know what the given key is.

This function reads the key length for the given file. Then it returns a string that is the right length, which is generated by counting in binary until a key is found that does not appear in the file. The first key found for a 4 byte key field would be chr$(0)&chr$(0)&chr$(0)&chr$(0). If that key was already in use in the file, the function would return chr$(0)&chr$(0)&chr$(0)&chr$(1). If that one was also in use, it would then try chr$(0)&chr$(0)&chr$(0)&chr$(2), and so on until it found one that wasn’t in use.

''FnMakeUniqueKey$(fl)''

*FL – This is the file number of the opened file for the desired key.

==== fnKey$ ====
This function formats the key for the given file number. All it does is ensure the key is the correct length. You should use fnBuildKey$ instead to properly build the correct key for the record you want to read.

''FnKey$(FileNumber, Key$)''

*FileNumber - the file number we are formatting the key for
*Key$ - the key we are trying to format.

==== fnNotInFile ====
This function will determine if a non-key element in a line is unique. It works almost exactly like fnUniqueKey specified above, except that it allows you to enter the subscript value of the element you are checking for uniqueness. You can use this to look for uniqueness in any field, not just in the key field. Additionally, the search engine used by this function looks for a partial match, and will only return true if the given string is not found anywhere in the specified element for the given file.

''fnNotInFile(string$*100,filename$,sub)''

*String$ - Value to check for uniqueness in this file.
*Filename$ - This is the name of the file layout of the file you want to check. This file does not have to be open in order for you to search it, because the function will open it for you.
*Sub – This is the subscript value of the element you are checking.

==== fnSortKeys ====
This function takes an array of Primary Keys indicating records in the data file, and resorts it into the order you would have expected using one of the other keys for your data file.

For example: Lets say you had a customer file, and the first key was Customer Code and the second key was Customer Last Name. This function would take an array of Customer Codes and sort it into Last Name order.

This function requires the file to already be opened (which is usually the case when you have an array of keys from that file).

''fnSortKeys(mat Keys$,Layout$,DataFile,mat F$,mat F,mat Form$;KeyNum)''

*mat Keys$ - the array of keys. These keys are based on whatever key the file was opened with in DataFile.
*Layout$ - the file layout for the file.
*DataFile - the open file number matching the key file that matches mat Keys$.
*mat F$ - array sized to hold the strings from the data file. This is the array you get back from fnOpen.
*mat F - array sized to hold the numerics from the data file. This is the array you get back from fnOpen.
*mat Form$ - array of form statements, that you get back from fnOpen.
*KeyNum - This is the key that we'll sort based on. If not given, the first key listed in the layout is assumed.

=== File Reading Functions ===

These functions actually read information from your data file and return it. These functions can be used to simplify the logic in your programs for many common tasks.

==== fnReadAllKeys ====
This function will read through a file, returning the specified element(s) from each record into (a) dynamically dimensioned array(s). For example, I could tell it to give me the Inventory Code for every inventory item in my database in one array, while placing the Inventory Description (name) for each item into the corresponding position in another array.

''fnReadAllKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$;sub2,mat out2$)''

*Fl – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array
*mat out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

For example:

FnReadAllKeys(InventFile,mat Invent$,mat Invent,mat Form$,IN_Code,mat InvtList$,IN_Name,mat InvtNames$)

==== fnReadMatchingKeys ====

This function will read through a file, returning the specified element(s) from each record where the key matches the specified key into (a) dynamically dimensioned array(s). This function is the same as the above function except this one will filter the results, returning only those records where the key matches the specified key.

''fnReadMatchingKeys(Fl,mat f$,mat f,mat fm$,key$,keysub,sub1,mat out1$;sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - Only records where the key field matches key$ will be returned.
*Keysub – This tells the function which element is the key element for this particular file number.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadAllNewKeys ====

This function will read through a file, returning the specified element(s) from each record that isn’t already there into (a) dynamically dimensioned array(s). This function is the same as the above function, except this one will filter the results returning only those records that don’t already exist in the array (eliminating duplicates).

''FnReadAllNewKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$; dont_reset,sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Dont_reset – By default the array will clear the contents of the arrays that are passed in. This Boolean flag will instruct the function to not empty the passed in arrays.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadFilterKeys ====

This function by Mikhail Zheleznov is a modification of the above functions. Like its predecessors, it reads an entire file, populating the specified arrays with data from all or some of the records in the file. The given subscripts specify which fields to return from each record. The key given specifies search criteria for the records. The filter specifies filtering criteria that can be preformed on the data before it is returned.

''FnReadFilterKeys(Fl,Mat F$,Mat F,Mat Fm$,Key$,Keyfld,Sub1,Mat Out1$;Filter$,Filter_Sub,Readlarger,Sub2,Mat Out2$, Sub3, Mat Out3$, Sub4,Mat Out4$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - The key to search for in the read statements
*Keyfld – the subscript of the key field in the data file. This must match the key field specified in the data file otherwise the function won’t work.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Filter$ – This optional parameter identifies matches to search for in the records. It works in conjunction with Filter_Sub
*Filter_Sub – This parameter specifies which field to look for in the records for matches to Filter$. Only records which have Filter$ in the specified field will be returned.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.
*Sub3 – Subscript of the element to return in the third array. This is optional. If it is specified, you must give MAT out3$, or BR will return an error.
*MAT out3$ - Array in which to return the third (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub3 is given (non-zero). This parameter will not be used if Sub3 is not given or is given as 0.
*Sub4 – Subscript of the element to return in the fourth array. This is optional. If it is specified, you must give MAT out4$, or BR will return an error.
*mat out4$ - Array in which to return the fourth (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub4 is given (non-zero). This parameter will not be used if Sub4 is not given or is given as 0.

This function was written by Mikhail Zheleznov for the fileIO library.

==== fnReadDescription$ ====
''fnReadDescription$(Fl,Subscript,key$,mat F$,mat F,mat Form$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout) (RT_NAME, which should equal 2 after opening routefile (unless we change the file layout later)).
*key$ - Item that should match a key in this file somewhere (in this case it is the route code from the farm record).
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading they have to be dimensioned properly, which is why we use our colorcat$ and our colorcat for these parameters.
*mat Form$ - This will need to be our array of form statements, so the function can read the file properly.

Lets take a look at how this function works:

In the example program I used above, I am reading the Color File to get details about each color. The color file contains a colorcat code field, but I want to display the colorcat description. The colorcat file contains a few details about a color category, and it is indexed based on colorcat code:

route.dat, RT_
route.key, CODE
recl=512
===================================================
CODE, Routing Code, C 6
NAME, Routing Name Description, C 30
MOFT, T/A/C (truck/air/courier), C 1
SHIPPINGDAY, Day of Week for Shipping, C 7

Now, as you know, in the above example, we have already opened the ColorCat File, and we have opened and read a Color record.

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
30180 LET ccode$=color$(CO_CODE) !:
LET Name$=color$(CO_NAME)

Now all that’s left to do is to take the Color File’s ColorCat code and use it to look up the ColorCat File’s description.

30190 LET ColorCat$ = fnReadDescription$(ColorCatFile, CC_NAME, Color$(CO_CATEGORY),
mat ColorCat$, mat ColorCat, mat form$)

==== fnReadUnopenedDescription$ ====
This function accomplishes the same thing as fnReadDescription except that it opens the data file for you. It is slower then FnReadDescription$, but it is easier to use.

''FnReadUnopenedDescription$(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the value of the key field in the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2, so sometimes it is a good idea to design your data files so that string field number two is a descriptive field, like Name or Description.

This function only works on the first key file for each data file. This function is a convenience function but it is slow because it opens the file and closes it for each call. Opening a file is one of the most time consuming program operations.

==== fnReadNumber ====

fnReadNumber does the same thing that ReadDescription does except it reads a numeric field instead of a description.

Lets take a look at how this function works:

''fnReadNumber(Fl,subscript,key$,mat F$,mat F,mat fm$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout).
*Key$ - Item that should match a key in this file somewhere.
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading. They have to be dimensioned properly by [[FileIO_Library#fnOpenFile|fnOpen]].
*mat Fm$ - This will need to be our array of form statements, so the function can read the file properly.

==== fnReadUnopenedNumber ====
This function accomplishes the same thing as fnReadNumber except that it opens the data file for you. It is slower then FnReadNumber, but it is easier to use.

''fnReadUnopenedNumber(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the key of the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2.

==== fnReadRelativeDescription$ ====
This function is the same as fnReadDescription$ but for Relative Files.

''fnReadRelativeDescription$(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat F,mat form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedDescription$ ====
This is the same as ReadUnopenedDescription$ but for Relative Files.

''fnReadRelUnopenedDescription(Layout$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRelativeNumber ====
This is the same as fnReadNumber but for Relative Files.

''fnReadRelativeNumber(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat f,mat Form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedNumber ====
This is the same as fnReadUnopenedNumber but for Relative Files.

''fnReadRelUnopenedNumber(LayoutName$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRecordWhere$ ====
This function returns the record where the given element matches the given value. It does not depend on any key files, and it can be used to locate a record based on any element. However, it loops through the entire data file to do this and it could be a bit slow for large data files. This function opens the file for you, so the file does not have to be already opened.

''FnReadRecordWhere$(Layout$,SearchSub,SearchKey$*255,ReturnSub)''

*Layout$ - the layout of the file we are searching
*SearchSub - Subscript of the element to look in
*SearchKey$ - The value we are looking for
*ReturnSub - Subscript of the element to return

=== FileIO Utility Functions ===
==== fnDataCrawler ====
This function launches the Data Crawler as a function, so you can make your own programs link to it. Special thanks to Mikhail Zheleznov for turning the DataCrawler into a library function.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnDataEdit ====
This function is the same as fnDataCrawler only it opens a Grid for editing.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnShowData ====

This function builds a list or a grid in a floating window that is tied to a data file. It uses the same function that the datacrawler uses, but its much more customizable. All other datacrawler functions are just wrappers for this one.

The first parameter is the only required parameter.

''def library fnShowData(FileLay$;Edit,sRow,sCol,Rows,Cols,KeyNumber,Caption$*127,Path$*255,KeyMatch$*255,SearchMatch$*255,CallingProgram$*255,mat Records,mat IncludeCols$,mat IncludeUI$,mat ColumnDescription$,mat ColumnWidths,mat ColumnForms$,DisplayField$*80,mat FilterFields$,mat FilterForm$,mat FilterCompare$,mat FilterCaption$,mat FilterDefaults$,mat FilterKey)''

*FileLay$ - the file layout you want to display
*Edit - 1 for Edit (Grid) and 0 for View (Listview)
*sRow, sCol - the start position. if not given, its centered. If given but out of bounds, they'll be automatically adjusted to fit the grid on the screen.
*Rows, Cols - the size. If not given, defaults to fullscreen. If given but not big enough to fit the UI elements you request, they're automatically adjusted to fit everthing.
*KeyNumber - the Key to use when reading the data, used with other parameters. If not given, the file is read Relative for faster performance. Required if KeyMatch$ is given.
*Caption$ - the Caption to display, defaults to FileIO's Datacrawler
*Path$ - Alternate path to use for data files (Prepended to the name found in the layout)
*KeyMatch$ - Show only records that match this key. You can use Partial Keys. If this parameter is given, you must also give KeyNumber (above).
*SearchMatch$ - Show only records that contain this substring in them anywhere
*CallingProgram$ - used for logging purposes, pass in the system function Program$
*mat Records - Show only these records in the Grid. Use it to control exactly what the user sees.
*mat IncludeCols$ - Show only these columns. These column names must match the subscript names from the file layout.
*mat IncludeUI$ - Which UI Options to show. Build this array with one element for each optional UI element to include. Explanations of UI elements follow:
**"ColumnsButton" - adds a Select Columns button that the user can use to modify which columns appear on the list.
**"ExportButton" - adds an Export to CSV button that exports the data to a CSV file.
**"ImportButton" - adds an Import from CSV button that imports from the CSV file.
**"AddButton" - adds a button that can be used to add records to the data file.
**"SaveButton" - adds a button allowing the user to save changes
**"DeleteButton" - adds a button allowing the user to delete a row
**"KeyButton" - adds a button allowing the user to jump to a specified position by key or by record number (depending on if the file is opened keyed or not)
**"QuitButton" - adds a Quit button to the screen (the Esc key also quits)
**"Search" - adds a case insensitive search box to the screen.
**"Border" - adds a border around the screen
**"Caption" - adds a caption. (If you specify a caption, this is automatically turned on. If you don't specify a caption but turn on caption here, then FileIO uses the default FileIO data crawler caption.
**"Recl" - adds the Recl to the caption
**"Position" - adds the positions to the field descriptions in the column headings.
*mat ColumnDescription$ - Show these captions. If blank, use the descriptions from the layout
*mat ColumnWidths - Use these widths for the data, if not given, calculate from the file layout
*mat ColumnForms$ - Display Format for the data, including DATE and FMT and PIC
*mat DisplayField$ - Counter Field to display on the Loading Window. If its a field with an associated DATE ColumnForms$ value, that column form will be used when displaying the Counter Field. It can be any of the following:
**REC - this will display the current "REC/LREC" data in the loading window.
**READCOUNT - this will display the "Record Count / LREC" in the loading window.
**FINDCOUNT - this will display the number of records that match the current search criteria by itself in the loading window.
**A Field Name - one of your field names will display that field value in the loading window
**A string literal - anything else will display as a string in the loading window, so you could put something like "Loading, please wait" here and it will display.
*mat FilterFields$ - Contains the subscript of the field to compare to
*mat FilterForm$ - Contains the format of the field to compare to
*mat FilterCompare$ - Contains the comparison type ("<>" or ">" or "=" or ">=" or "*") (* means do a substring search)
*mat FilterCaption$ - The caption for the filter box
*mat FilterDefaults$ - The default value for the filter information
*mat FilterKey - The action to use when filtering the data this way (0 means simple exclude, 1 means start here, -1 means stop here)
**The final five arrays can be used to add user filter boxes to the data grid. You need one element in each array for every custom user filter box on the screen.

==== fnBeginAudit ====

The [[AuditBR|FileIO Compare]] routine is available and can be called from within your programs. To do so, call fnBeginAudit to mark the Start of the compare, then do whatever you need, then run fnCompare to compare everything that has changed between when you ran fnBeginAudit and when you ran fnCompare.

See [[AuditBR#fnBeginAudit|the documentation]] for more details.

==== fnCompare ====

See [[AuditBR#fnCompare|the documentation]] for more details.

==== fnCSVImport ====

This function calls the FileIO Import routine, the same one that you get from the Datacrawlers Import Button.

''fnCsvImport(Layout$*64;SuppressDialog,FileName$*300,ImportModeKey)''

*Layout$ - The file layout to import into
*SupressDialog - 1 to Supress the Import Dialog
*FileName$ - the name of the CSV file (Required if Dialog is Suppressed)
*ImportModeKey - the Import Mode Key (Required if Dialog is Suppressed)
**-1 - Add all records to the file
**0 - Update by Record Number (The file must contain a RecNum column and it must be first)
**1+ - Any positive number means Update by that Key (as listed in the layout).

==== fnCSVExport ====

This function exports a data file to a CSV file.

''fnCsvExport(Layout$*64;SuppressDialog,Filename$*300,IncludeRecNums,KeyNumber,StartKey$,KeyMatch$,Startrec,mat Records,SearchMatch$)''

*Layout$ - The File Layout to Export
*SuppressDialog - (1 to Suppress the Export Dialog, 0 to show it)
*Filename$ - the output file name (Required if SuppressDialog is 1)
*IncludeRecNums - Include a column with the Record Numbers in it
*KeyNumber - Use this key when reading the data for export
*StartKey$ - Start with the record that matches StartKey$
*KeyMatch$ - Export only the record(s) that match KeyMatch$
*StartRec - Start with this Record Number
*mat Records - Export only these records
*SearchMatch$ - Export only records containing this search string anywhere in them

==== fnExportListViewCsv ====

Exports the contents of the specified Listview in CSV format.

''fnExportListViewCsv(Window,Spec$;GenFileName,Delim$,FileName$*255)''

*Window - The Window containing the listview.
*Spec$ - The Spec identifying the listview.
*GenFileName - Flag telling weather or not to generate the file name.
*Delim$ - Delimiter to use. Comma is default.
*Filename$ - Filename to use

==== fnGenerateLayout & fnWriteLayout ====

This function calls on the Generate File Layout Wizard to generate and save the layout indicated by the parameters you give it. You must give it the same valid parameters that you would have come up with if you worked through the layout wizard the normal way, by running FileIO directly and choosing "Generate Layout".

You can also bypass the automatic parsing and generate a layout by specifying all the data directly and using fnWriteLayout.

''fnGenerateLayout(mat OpenStrings$, ReadString$*999, FormString$*20000, DimString$*999; DisplayFile)''
''

*mat OpenString$ - array of all the open strings for the given file from one of your old programs.
*mat ReadString$ - solid read statement from one of your old programs reading the entire record, (or at least everything you want in the layout).
*mat FormString$ - the form statement that goes with the ReadString$ (practice using the Generate Layout Wizard the normal way for details)
*mat DimString$ - the string containing Dim statements for each array mentioned in ReadString$. We need this to know how big the arrays are.
*DisplayFile - if True (1), it will Display the new layout in notepad when its done creating it. If false (0), it will simply create the file.

fnGenerateLayout takes all the above information and parses it into a layout, then calls fnWriteLayout to actually write the layout.

If you already know the information you want to put in the layout, its more direct to call fnWriteLayout below.

''fnWriteLayout(Name$,FileName$*127,VER,PRE$,MAT KFNAME$,MAT KDESCRIPTION$,MAT SUBS$,MAT DESCR$,MAT FORM$;RECL,MAT EXTRA$,DISPLAYFILE)''

*Name$ - the name of the new layout
*FileName$*127 - the name of the data file
*Ver - the version of the data file
*Pre$ - the prefix to use for the data file
*mat KfName$ - array of all the keys for the file
*mat Kdescription$ - array of the subscripts that each key is based on
*mat Subs$ - the subscript for each field in the file
*mat Descr$ - the descriptions for each field in the file
*mat Form$ - the form specs for each field in the file
*Recl - (optional) the record length of the file
*mat Extra$ - (optional) Additonal Information for each field in the file, placed in the Comments column of the new layout. This column is ignored by standard fileio processing.
DisplayFile - if True, open the file in Notepad after it has been created.

==== fnSubstituteStringCode ====
A Large Text Field that is searched. Code is run and any resulting variables are set, if they exist inside String enclosed between Substitute Chars (default []), then they will be replaced with the values derived by the code.

''fnSubstituteStringCode(&String$,Code$*2048;SubstituteChar$)''

*String$ - the string to be searched
*Code$ - code to be run. The resulting variables can be substituted into String
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnSubstituteString ====
A Large Text Field that is searched. Any matching fields in the passed in record will be substituted into their places. For example, if the string contained [cu_name] and you ran substitutions on the Customer file, then [cu_name] would be replaced by the name in the actual Customer record.

''fnSubstituteString(&String$,Filelayout$,mat F$,mat F;SubstituteChar$)''

*String$ - the string to be searched
*FileLayout$ - the layout to be searched
*mat F$ - the record to be used for substitution
*mat F - the record to be used for substitution
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnShowMessage ====
Displays a message to the user, in a child window. Returns the child window number, so that you can close it when you're done with the message.

''WindowNumber=fnShowMessage(Message$*54)''

*Message - the Message to display to the user

=== File System Utility Functions ===
These functions perform other tasks that aid with interacting with the file system.

==== fnGetFileDateTime$ ====
This does a directory listing to determine the Last Modified Date and Time of the given file. You pass it a file name, not a file layout, and it can be used on any file. Its not limited to BR internal files.

The syntax is:

''let FileDate$=fnGetFileDateTime$(Filename$*255)''

==== fnProgressBar ====
There's a Progress Bar that FileIO uses when copying or updating data files. You can use it in your own functions by calling fnProgressBar inside the main loop of the process that you want to display the progress bar over, and by calling fnCloseBar when you're done.

''fnProgressBar(Percent;Color$,ProgressAfter,ProgressThreshhold,UpdateThreshhold,Caption$*255,MessageRow$*255)''

*Percent - Percentage Complete expressed as a float between 0 and 1
*Color$ - HTML Color Code of BR Color Attribute to color the Progress Bar. Defaults to Green.
*ProgressAfter - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*ProgressThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*UpdateThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*Caption$ - Optional message to display above the progress bar.
*MessageRow$ - Optional message to display on the progress bar.

==== fnCloseBar ====

''fnCloseBar''

Call this function to close the progress bar window when your task is done running.

==== fnCopyFile ====

''fnCopyFile(FromFile$*255,ToFile$*255)''

*FromFile$ - The file to copy.
*ToFile$ - The destination file name including path.

This function copies any file, by opening it as an external file and reading and writing the data to the destination file. The advantage of this technique, over using the BR copy command, is this routine is more reliable when run on client server where you may be transferring large files from one side to the other over the internet.

This fnCopyFile also has a progress bar that displays as the file is transferred, so the user knows your software is busy.

This function works over Client Server. Under Client Server, specify @: at the beginning of your filename, to specify that the file is on the client. If the file is on the server, simply leave the @: off. See the chapter on [[Copy#Client_Server|using BR's copy command under Client Server]] for more details on the "@:".

This function's parameters and syntax are modeled off of the built in BR copy command, and like that one, this should work for local transfers, LAN transfers, or even internet transfers. This function will work better for internet transfers then the built in BR Copy Command, however.

==== fnCopyDataFiles ====

''fnCopyDataFiles(DestinationFolder$*255)''

*DestinationFolder$ - the folder to copy your data files to.

This function reads your file layouts and makes a copy of every data file (and key file) in your system to the destination folder, utilizing fnCopyFile above, for better performance and reliability when running over the internet, as well as a progress bar for each individual file.

It also displays a listview while its copying so you can watch the progress while its transferring your data files.

This can be used for making backups of your BR data, or for transferring the latest data onto a laptop for access to it while you're on the road away from the internet.

==== fnReIndex ====

This function reindexes a single data file

''fnReIndex(DataFile$*255;CallingProgram$*255,IndexNum,Path$*25)''

*Datafile$ - the file layout of the file to index
*CallingProgram$ - used for logging, pass Program$ in here
*IndexNum - The index to rebuild - if not given, rebuilds all indexes
*Path$ - the optional alternate path to use for rebuilding the data file.

==== fnReIndexAllFiles ====

This function reindexes all your data files. It doesn't require any parameters.

''fnReIndexAllFiles''

==== fnUpdateFile ====
This function checks and Updates a data file if it needs to be updated, by opening and then closing the data file.

''fnUpdateFile(FileLayout$)''

*FileLayout$ - The name of the file to update

==== fnRemoveDeletes ====

This function, written by Susan Smith, removes deleted records by copying the file with the -D option.

''fnRemoveDeletes(LayoutName$*255;Path$*255,CallingProgram$*255)''

*LayoutName$ - the file layout
*Path$ - Optional Alternate Path
*CallingPRogram$ - used for logging, pass Program$ in here

=== Layout Interrogation ===
Layout interrogation functions are provided for convenience and to enable future dictionary changes without disrupting any programs that interrogate it.

==== fnMakeSubProc ====
This function obtains the subscript assignments that were assigned by fnOpen according to the file layout. The fnMakeSubProc$ routine obtains the subscript assignments without actually opening the file. This is useful when a file record is passed as arrays into a library function in another program, or when you chained to another program and you need to know how to reach the data in the arrays without actually reopening the file.

''fnMakeSubProc(filelay$;mat Subscripts$)''

*FileLay$ - The name of the file layout from which to read the subscripts.
*mat Subscripts$ - If you give this optional array, fnMakeSubProc passes the subscripts back in this array rather then in the subs.$$$ file. This is much faster and helps avoid sharing conflicts.

When this routine returns, you can set the subscripts in your program by executing every element of the Subscripts$ array in a for/next loop.

If you did not pass in a subscripts array, then the a procedure file named subs.$$$ is created. If you proc that file, the proper subscripts will be set.

==== fnReadLayoutArrays ====
This function reads the fields in a file layout into arrays. You call it like the following

''fnReadLayoutArrays(filelay$,&prefix$;mat SSubs$, mat NSubs$, mat SSpec$, mat NSpec$,mat SDescription$, mat NDescription$,Mat Spos,Mat Npos)''

*filelay$ - the name of the layout to read
*prefix$ - the return value for the prefix for the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

This function call would read the fields from the layout in filelay$, and it would return the prefix to prefix$. The Subs would be returned in mat SSubs$ and mat NSubs$.

The Spec statements are returned in mat SSpec$ and mat NSpec$ and the Descriptions are returned in mat SDescription$ and mat NDescription$. The start positions on disk of each element are returned in mat SPos and mat NPos.

All the arrays are optional. If you don’t pass them the information they are supposed to record is simply not returned.

==== fnReadLayoutHeader ====
This function reads the header for a given file layout.

''fnReadLayoutHeader(Layoutname$*255;&Filename$,Mat Keys$,Mat KeyDescription$)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file

==== fnReadEntireLayout ====
This function reads the entire layout by calling fnReadLayoutHeader and fnReadLayoutArrays.

''fnReadEntireLayout(Layoutname$*255;&Filename$,&Prefix$,Mat Keys$,Mat KeyDescription$,Mat Ssubs$,Mat Nsubs$,Mat Sspec$,Mat Nspec$,Mat Sdescription$,Mat Ndescription$,Mat Spos,Mat Npos)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*prefix$ - the return value for the prefix for the file
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

==== fnReadSubs ====
This function reads the subscripts from a layout into Subs arrays.

''fnReadSubs(Layout$,mat SSubs$,mat NSubs$,&Prefix$)''

*Layout$ - the file layout name
*mat SSubs$ - the String Subscript Names
*mat NSubs$ - the Number Subscript Names
*Prefix$ - the files Prefix

==== fnReadKeyFiles ====
This function reads the list of key files from the layout.

''fnReadKeyFiles(Layout$,mat Keys$)''

*Layout$ - The file layout
*mat Keys$ - output array, the keys are returned here.

==== fnLayoutExtension$ ====

This function returns the layout extension being used.

==== fnReadLayouts ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''FnReadLayouts(mat Dirlist$)''

*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all the file layouts that FileIO can find.

==== fnDirVersionHistoryFiles ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''fnDirVersionHistoryFiles(Layout$,mat DirList$;BypassExtension$)''
*Layout$ - Which layout to look up version history of
*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all previous versions from history of the requested layout.

==== fnReadLayoutPath$ ====
This function doesn't actually interrogate your layouts. Instead, it interrogates your settings and returns the path specified for your layout files. This would usually be "filelay\" but you can change it in [[#fnSettings|fileio.ini.]]

It has no parameters.

''let Path$=fnReadLayoutPath$''

==== fnDoesLayoutExist ====
This function returns true if the given file layout exists. It returns false if the layout does not exist.

''FnDoesLayoutExist(layout$)''

*Layout$ - Layout to test for

==== fnReadForm$ (uncompiled) ====
Sometimes you need to know the original form statement that fileio is using to read your data file, most often when you're debugging your file layout, and you're getting some problem when reading the file. The form statement that fileio normally returns is compiled using CFORM$ to save space in the array, and to make the execution of your read statements faster. You can use this function to return the original form statement for the file.

The syntax is:

''let FormStatement$=fnReadForm$*10000(FileLayout$)''

Remember to dimension FormStatement to something huge! fnReadForm$ can return up to 10,000 characters.

==== fnReadFormAndSubs ====

This function does the same as above but it also reads the subscripts from the file into an array.

''let fnReadFormAndSubs(Layout$,mat Subs$,&ReadForm$,&StringSize,&NumberSize)''

Note that unlike most of our functions, all the above parameters are required.

The layout is the layout you're interrogating. The Array will be populated with the subscripts after the function. The ReadForm$ variable will be filled with the form statement for the file. Remember to dimension it large enough. StringSize and NumberSize will contain the number of string fields and numeric fields in the file.

Mat Subs$ will be returned, strings first, numbers last, matching the form statement that is returned. So Subs$(1) is the first string subscript and Subs$(StringSize+1) is the first Numeric subscript.

==== fnClearLayoutCache ====

fnClearLayoutCash (v2.3+) clears out the cache of layout name and data to get realtime Updates to File Layouts.

=== Other Useful Functions (non-layout related) ===

==== fnAskCombo ====

Opens a window with a combo box and returns the users selection.

''fnAskCombo$*255(mat Description$;Caption$*60,Default$*255)''

*mat Description$ - contains the combo box choices
*Caption$ - contains the optional caption for the window
*Default$ - the text of the item in mat Description$ that you want to be selected by default

==== fnSendEmail ====

This function sends an email and an optional attachment to the email address specified.

''fnSendEmail(Emailaddress$*255,Message$*10000;Subject$*255,Invoicefile$*255)''

*EmailAddress$ - the Destination Email Address
*Message$ - the Message$ to send
*Subject$ - the subject
*InvoiceFile$ - the filename of a file to attach. This is the BR filename (the function automatically converts it to an OS Filename.)

The function returns 1 when the email was sent successfully, or 0 if it wasn't sent successfully.

In order to use this function, you must have the emailcfg file layout in your layouts folder and you must have a copy of SendEmail.exe which is free and can be downloaded from the internet. Both of these files are included with the latest update of fileio.

You also have to configure fileio with the authentication information for your email server.

To configure your email server, simply run FileIO to get the data crawler, then select the emailcfg file layout and press F5 to edit it. Add a row if the file is empty.

Simply fill in the information the file is asking for in the appropriate fields and save the data, and then test sending an email to make sure it worked.

More information about sendEmail.exe is available from the author's product site here: [http://caspian.dotconf.net/menu/Software/SendEmail/ http://caspian.dotconf.net/menu/Software/SendEmail/]

==== fnClientEnv$ ====

This function returns the value of a Windows Environment Variable on the client under Client Server.

''fnClientEnv$*255(EnvKey$)''

*EnvKey$ is the name of the Windows Environment Variable to check on the client.

The function returns the value of the entered environment variable.

==== fnClientServer ====

This function returns true if you're currently running in Client Server mode, and false if you're running in the old "native" mode.

==== fnEmpty & fnEmptyS ====
These functions test if the passed in array is empty or not..

The syntax is:

''fnEmpty(mat Numeric)''

or

''fnEmptyS(mat String$)''

Example:

def fnSomeFunction(String$,mat Array$; mat OtherArray)
if fnEmpty(mat OtherArray) then
! Arrays were empty.
end if
fnend

==== fnReadScreenSize ====
This function reads the screen size of the given window (or window 0 if a window wasn't passed.) This is useful for centering a window on the screen, or for making sure window 0 is big enough for the child window you're trying to create.

The syntax is:

''fnReadScreenSize(&Rows,&Cols;Window)''

*Rows & Cols - returns the screen size in rows and columns.
*Window - the window to interrogate. If not given, assumes [[Open_Window#Comments_and_Examples|Window 0]].

==== fnBuildProcFile ====
This function builds a proc file to be executed later. This function and the next simplify the process of executing code in a proc file. It can even be used to spawn a new session of BR.

To use it, call fnBuildProcFile one or more times and specify some lines of code to execute.

''fnBuildProcFile(Command$*255)''

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnRunProcFile ====

This function spawns a new copy of BR and in it, runs the proc file that you've previously built using fnBuildProcFile (above).

'' fnRunProcFile(;NoWait) ''

The optional parameter "NoWait" causes the other session to spawn and run in a new thread. If you don't specify NoWait, the current session pauses and waits for the other session to close before proceeding.

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnLog & fnErrLog ====
These next two functions are functions to aid in logging. When you call either of these two functions, you give them a string that you wish to log. They will open the FileIO Log File and add a record to the end of it containing some user information such as login_name and session$, and the string that you specified. FnErrLog does the same thing as fnLog except it also logs the Error Number and the Line.

The syntax is:

''FnLog(string$)''

*String$ - the Log Message

''FnErrLog(String$)''

*String$ - the Log Message

==== fnLogArray ====

This function logs the given arrays to the log file, logging each field in the arrays. Its useful for recording, for example, an entire data record that is about to be written to a data file.

The syntax is:
''fnLogarray(mat F$,mat f;Message$*512,CallingProgram$*255)''
The first two parameters, of course, are the array to log. The third parameter is an optional message to be recorded along with the array, and the fourth optional parameter is the CallingProgram$ to save in the log along with the message. (The CallingProgram$ parameter can usually be passed as the system function Program$)

==== fnSetLogChanges ====
This function works in conjunction with the next function, and they're for recording just what changed in a data file. When the file is read, you call fnSetLogChanges and record the "before" picture of the file record.

After changes have been made and saved back to disk, you can call fnLogChanges below to record the actual changes.

The syntax is:
''fnSetLogChanges(mat F$,mat F)''

==== fnLogChanges ====
This function is the other half of the function above. It compares the given arrays with the ones set previously in the above function and checks for changes. Then it generates a log message recording information about just the items that changed.

The syntax is:
''fnLogChanges(mat F$,mat F;Message$*1024,CallingProgram$*255,Layout$)''

You need to pass in the same two arrays as before, but this time the modified versions of them.

You can also optionally pass a 1024 byte log message to record with the log entry.

CallingProgram$ again should be passed as the system internal function Program$.

The final parameter allows the passing of a Layout$. If you pass a Layout$, that layout is read and the subscripts are used when making the log message of changes, so that its easier to read. If you pass a layout, it will identify the changed fields by name. If you don't it will identify those fields by relative position number.

==== fnViewLogFile ====
All of the above functions store the information by default into a BR internal file defined in the filelay\logfile layout.

The fnViewLog function uses fnShowData to call the Data Crawler to display the FileIO Log File in a searchable listview.

''fnViewLogFile(;ShowQuit,ShowColumns,ShowExport)''

*ShowQuit - Show a quit button on the UI (if off, ESC will quit).
*ShowColumns - Include a button to allow the user to select which columns to view.
*ShowExport - Include a button to export the log file to CSV.

==== fnReadLockedUsers ====

This function returns a list of all users using the locked data file.

''fnReadLockedUsers(mat Users$)''

*mat Users$ - the list of users is returned here

==== fnDisplayLength ====
This function calculates the display length of a field based on its form spec.

''fnDisplayLength(Spec$)''

*Spec - the Form Spec to return the display length of.

==== fnLength ====
This function calculates the length on disk of a field based on its form spec.

''fnLength(Spec$)''

*Spec$ - the Form Spec to return the length of.

==== fnStandardTime$ ====
Converts Military Time to Standard Time. Returns Standard Time$

''fnStandardTime$(MilitaryTime$;Seconds)''

*MilitaryTime$ - Time in 24 hr format.

==== fnMilitaryTime$ ====
''fnMilitaryTime$(StandardTime$;Seconds)''

*StandardTime$ - Time in AM/PM Format

==== fnCalculateHours ====
Calculates the difference between 2 specified times.

''fnCalculateHours(TimeIn$,TOut$,DaysIN,DaysOut)''

*TimeIn$ - From Time
*TimeOut$ - To Time
*DaysIn - Days Start
*DaysOut - Days End

==== fnBuildTime$ ====
Builds a time in the format used by the above functions.

''fnBuildTime$(H,M,S,P;Military,Seconds)''

*H - Hours
*M - Minutes
*S - Seconds
*P - Boolean indicating AM/PM - 0 is AM, 1 is PM
*Military - Flag indicating weather desired result is in Military Time or not
*Seconds - Flag indicating weather to count seconds or ignore them. (1 means count seconds)

==== fnParseTime ====
Takes a time and pulls out the values

''fnParseTime(T$,&H,&M,&S,&P)''

*T$ - the time to parse
*H - Return value for Hours
*M - Return value for Minutes
*S - Return value for Seconds
*P - Return Value for AM/PM

== FileIO fnSettings (Global Settings Code) ==

The FileIO library can be made to implement certain policies across the board. These are established by creating a file called fileio.ini and typing statements like the following into it. This file is "PROCed", so you don't want to put line numbers in it.

Anything you don't specify in fileio.ini will take its default value, shown below. So you only need to specify the items that you want to be different.

Note, for the boolean settings below, 1 denotes TRUE and 0 denotes FALSE.

let EnforceDupkeys=1 ! Enforce that key number 1 is unique key
let Defaultfilelayoutpath$="filelay\" ! Path To Your File Layouts
let Promptonfilecreate=1 ! Ask User Before Creating New Files
let Createlogfile=0 ! Use Logging
let StartFileNumber=1 ! Set above 300 to avoid conflicts with legacy programs.
let CheckIndex=0 ! Automatically Verify Indexes (slow)
let CompressColumns=0 ! Shrink or Expand Columns in Data Crawler by Default
let MaxColWidth=20 ! Max Default Column Width in Data Crawler
let LogLibrary$="" ! Defaut Log Library, defaults to None
let LogLayout$="" ! Log file layout, defaults to Internal File
let AnimateDatacrawler=1 ! Use ScreenIO Animation for Datacrawler
let TemplatePath$="filelay\template\" ! Default Template Path
let IgnoreLayouts$="" ! List any Ignore Layouts here.
let CloseFileSimple=0 ! Use simple comparison for fnCloseFile

==== EnforceDupkeys ====

Turn on the EnforceDupkeys option to force that the first key listed in your file layouts is a unique key. FileIO will generate the standard BR error for Dupkeys when attempting to create indexes if it is not unique.

==== DefaultFileLayoutPath$ ====

Use the DefaultFileLayoutPath option to specify the path from your programs to your file layout folder. The default is "filelay\". Use this setting if you want to place your file layouts in another folder from the default.

==== PromptOnFileCreate ====

Use the PromptOnFileCreate setting to cause FileIO to display a message box whenever it is attempting to create a new file. This happens during the automatic update procedure, as well as during any attempt to access a file that does not exist. This setting should be turned off in your live system, and only turned on for development purposes. If you use the message box to cancel creating of the new file, then the file is not created, and fileIO or your application will most likely give an error when you attempt to actually access the new file.

It can be useful during development to make sure that you don't accidentally create the wrong files, due to an incorrectly specified path or a typeo in the filename in the layout file. However, in a live system, these things have already been tested, and you generally want the default behavior, because you don't want your users to have the ability to cancel the normal operation of FileIO.

==== CreateLogFile ====

Use this option to specify weather or not to use the FileIO log file. If it is turned on, a log file called FileIO.log in the current directory is created with entries listing all attempts to open a file, automatically update one, or automatically update your indexes.

==== StartFileNumber ====

Use this option to set the starting file number that the fnGetFileNumber and the fnOpen functions use to search for available file numbers. This is so that if you have certian reserved file numbers in your code, you can make sure that FileIO will not use those reserved file numbers, causing a conflict with your already existing programs. The default is 1, which is fine if your software does not have any reserved file numbers.

The allowable BR file numbers are 1-200 and 300-999.

==== CheckIndex ====

This function is used for Partial FileIO Implementations. If all of your software uses FileIO then all of your indexes are kept automatically up to date by the FileIO library and BR's internal file processing systems. However, if some of your programs do not use FileIO, and you use the FileIO library to add a new index file that those other programs do not know about, then its possible for the additional index file to become out of date when the master file is updated by your other programs.

Use this setting to cause FileIO to check the DateTime stamp on all your index files when opening a new file, and automatically update any indexes that may have potentially gotten out of date from other programs.

This option slows down the processing of the fnOpen function, particularly when running under client server over the internet. If you know that every program in your application suite uses FileIO, and that any programs that do not use FileIO still properly update all the indexes that your data file uses, then you can safely leave this setting turned off, and optimize your performance when opening several files using the fileIO system.

==== CompressColumns ====
This instructs the datacrawler to use smaller widths for small columns. If CompressColumns is false, the data crawler will make the column the width of the field or the width of the caption, whichever is wider. If CompressColumns is true, it will use the width of the field, not the caption.

==== MaxColWidth ====
This limits the column width to a set amount. This is applied after CompressColumns above.

==== LogLibrary$ ====
If a library is specified here, then fileio looks for a BR library with the specified name, and attempts to call a library function in it called fnFileIOLog that. This function should expect six parameters, which are Logstring$, Login_Name$, Session$, Days of Date$, Time$, and CallingProgram$, if LogLayout is also nonblank.

If you specify a LogLibrary and LogLayout is blank, then it calls your function giving it only 1 parameter.

It will call your function '''''instead of''''' the normal log file. Use this to implement your own logging functions however you want.

==== LogLayout$ ====
Use this setting to specify an alternate file layout for an alternate file to do the logging in. Base the file layout for this file on the logfile we supply for you in the filelay folder. It should have at least those fields, which our log routine will automatically populate, but you can add other fields if you want (though you will need to manage them yourself).

If you don't specify LogLayout, the default filelay\logfile will be used. This will allow you to also use the fnViewLogFile function to access it.

==== AnimateDataCrawler ====
The sister library [[ScreenIO]] has a feature that allows you to use an animation of a clock in your loading screens in your own programs. If you have [[ScreenIO]] then FileIO will automatically detect it and use it to display a loading animation while the data in the data crawler loads.

Set AnimateDataCrawler to false (0) in your fileio.ini file to bypass the animations if you do have screenio but don't want to see the animations anyway.

==== TemplatePath$ ====
This setting points to the folder that contains the code templates used by the Generate Code button on the main page of the Data Crawler.

==== IgnoreLayouts$ ====
This is a comma delimited list of all layouts that you wish to suppress from appearing on the main page of the data crawler. You can still access these layouts with your code, but they won't be listed in the data crawler for you to access.

Whatever you're using for a log layout, is automatically added to this list.
==== CloseFileSimple ====
The fnCloseFile function closes all the individual handles to a data file that was opened for output using multiple keys.

For BR 4.18 and higher, we support a better algorithm for detecting which files are matches for a given opened file number.

Set CloseFileSimple to true (1) to force it to check the old way.

== FileIO Add-on Packages ==

Many FileIO Add-on packages are currently in the works.

=== ScreenIO Library ===

The [[ScreenIO Library]] is a sister library to the FileIO library. The ScreenIO library requires the FileIO library in order to run.

The ScreenIO library is a complete Rapid Application Design tool that enables you to implement custom screen functions anywhere in your exiting programs.

If you call the ScreenIO Library as a function library, you call a function called fnFM and tell it which screen you wish to use. The ScreenIO library loads your user interface, loads your data files, and preforms all the file maintenance operations you have designed into your screens.

You can find out the latest information about the ScreenIO library in the ScreenIO page.

=== Audit BR ===

The [[AuditBR|Audit BR]] developer tool makes a backup copy of your file layouts. Then you run some code you're trying to test, and finally, run Audit BR again, to get a report showing all the changes to any of your data files automatically.

AuditBR is now included directly in FileIO. To use it, select the layout from the list of layouts in the Datacrawler and press the "Compare" button.

== What’s New (also described above) ==
=== 2018 ===
*Support for dates in any storage formats on disk (v2.48)

=== 2015 ===
*Added Rec to display for fnShowData
*Added FormStatement$ for debugging of form statements inside fileio
*Added mat BadRead$ for debugging of 726 errors when making new layouts
*Fixed a bug causing crash when logging things from long program folders
*fnClientEnv$ - reads a Windows Environment variable on the client using the command shell
*fnAskCombo$ - added an optional parameter to set default selection.

=== 2010 - 2014 ===
*FileIO now caches your file layouts in memory to make it much faster then before when opening the same data file in multiple programs.
*Generate Layout Wizard
*fnShowData
*Improved Logging
*fnViewLogFile
*Import/Export
*Import/Export by Function
*Many other speed increases
*if ScreenIO is present, Datacrawler uses the animation routines
*fnBuildProcFile & fnRunProcFile
*fnGenerateLayout & fnWriteLayout
*fnReadForm$
*fnReadFormAndSubs
*fnGetFileDateTime$
*fnReadLayoutPath$
*fnSortKeys
*fnSetLogChanges
*fnLogChanges
*fnLogArray
*fnReadScreenSize
*fnEmpty
*fnEmptyS
*Many other useful functions that were added to the documentation at earlier dates.

=== Spring 2009 ===

'''''New Functions:'''''

The FileIO Library has been updated in Spring 2009 to provide several new functions:

*fnReadRecordWhere
*fnKey$
*fnBuildKey$
*fnReadUnopenedDescription$
*fnUpdateFile
*fnDisplayLength
*fnLength
*fnReadLayoutHeader
*fnReadEntireLayout

'''''Speed Increases:'''''

Thanks to the BR [[Profiler]], we have increased the speed of FileIO fnOpen function by ten times when running over a LAN and by 100 times when running over the internet using Client Server.

In order to get the new Speed Upgrades, you will need to make sure that you use the latest copy of the [[#fnOpen_Function|fnOpen]] function in each one of your programs that use FileIO.

'''''Network FileIO:'''''
This version of FileIO has been optimized to work better in network situations.

'''''FnSettings: '''''
There are more configuration options in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine.

'''''Automatic Update Speed Fix:'''''
The automatic update proceedure has been made to run more then 100 times faster then before according to our benchmarking tests.

=== Fall 2008 ===
'''''DataCrawler Grid:'''''

By popular request we added a read/write version to the data crawler. This version works exactly the same as the datacrawler did before but it displays all the contents of your data files in a grid instead of a listview.

When you run the fileIO library as a program, it launches a tool known as the [[#DataCrawler|DataCrawler]]. The DataCrawler shows a listview displaying all your layout files in it. If you select one, it builds another listview with all the data in your selected data file.

If you are looking at the first list of all your file layouts, and you press F5, a grid will be build displaying all the data in your data files. You can change any of the records you like, and when you're done, your changes will be saved to the data file. Additionally, you can Add or Delete records using the buttons at the bottom. Any changes you make are not written to the disk until you click the "Save" button. If you press ESC (Cancel) the grid is closed and all changes you made sinse the last save are lost.

This tool is for programmers only. Do not give your end users access to the DataCrawler.

Use the DataCrawler at your own risk. Gabriel Bakker and Sage AX are not responsible for any harm that comes to your data files through the use of this or any other tools we offer.

The DataCrawler is not designed to be used to maintain your data files. It can be used carefully to correct small things in your data files.

'''''Support for Nonstandard Paths:'''''

Many BR Vendors keep different versions of the same data files in different locations. For example, sometimes a BR vendor will use a different Data folder to represent data for different Warehouses, or Customers. In cases like this it is necessary for your programs to specify the path to your data files. They may do so by specifying the optional "PATH" parameter to your data files. See the section [[#fnOpenFile]] for more information.

'''''Support for Nonstandard Layout Files Path:'''''

Old versions of the fileIO library required you to place all your file layouts in a subfolder of your program directory called "filelay". We have now changed the Fileio library to allow you to place your file layouts any place you want. The only requirement is that they are all together in one folder by themselves.

If you use a nonstandard path in the fileIO library, it is necessary to make a change to the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code in your copy of fileio.br.

'''''Prompt on Create:'''''

The FileIO library automatically creates any data files that it can't find. This was done to make it easier to deploy your finished programs - if you had any empty data files you could omit them from the packages and they would be created when they were needed, on the fly.

The current version of the FileIO library contains the same ability. However, it prompts you before creating any data files. This helps to avoid bugs that happen from incorrectly specifying the path to your data files.

However, if you do intend for your data files to be autocreated, then you probably don't want your end users to modify them. Therefore, you can use the PromptOnCreate setting in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code to specify. If this value is set to true, then the fileIO library will prompt you whenever it attempts to Autocreate a data file. If it is set to false, then the fileIO library will create the data files without prompting you, like it always did before.

'''''fnSettings:'''''

The newest version of the FileIO library supports some features that require you to specify Global Settings values. These are done by modifying the contents of the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine at the beginning of the fileIO library.

=== Fall 2006 ===
Many improvements have been made in the FileIO library over the summer. This section is intended to acquaint you with the highlights of those changes. Most of these improvements were built from ideas generated during the discussion at the April conference.

'''''Intermixed String and Numeric Specs:'''''
The File Library has been expanded to allow the reading of data files that contain mixed string and numeric specs. This is to aid those of you who are planning on implementing the FileIO Library on existing data files which may not be organized with strings first and numbers second.

The central idea of the FileIO Library is based upon the reading of your data files into a String and Numeric array. This will enable you to refer to the fields in your file by using a named subscript, saying F$(FM_NAME) to refer, for example, to the farm file’s name field. The advantage to this is that when you change the file layout, all your existing programs will not have to be modified, because they will only be looking at F$(FM_NAME). If the name field changes from the third string field to the fourth, the value of FM_NAME will also change, and you won’t have to worry about updating your data files.

However, in order to support the reading of a data file with intermixed string and numeric specs, the generated form statement will actually calculate the position of any fields that are not in order, so that the file read statement will still return all string fields first (into your string array) and the numeric fields second (into your numeric array). You do not need to worry about this; the library does it for you. All you have to do is read your file and use the data values.

The only thing that is required is making sure that all your string subscript names end with a “$”. This will tell the library that they are strings. Thank you, George, for this suggestion.

'''''Versioning / Automatic Updates:'''''
The file layouts have been expanded to contain a version number. This version number will be used to determine when a file needs to be updated. The version number is the third parameter in the file layout.

Any time you wish to change your file layouts, simply increment this version number. Each time the library attempts to open a data file, the file’s version is checked and compared with the version in the file layout. If the file layout has been changed (if the version in the file layout is greater then the version in the file) then the file will be updated to the latest version. Depending on the file size this may take a couple of moments. A simple progress bar will be displayed on screen while this is happening. The progress bar will be displayed in its own window, so it should not affect anything your programs may have had on screen.

The library uses the following procedure for updating a file. First, the file is copied to a backup file (prefixed by the letter ‘o’ for old). So color.dat would become ocolor.dat, and color.key would become ocolor.key. Then the new file is created and marked with the proper version number. (color.dat, color.key). The old file is opened in read-only mode, and the new file is opened for OutIn. The update routine actually reads through the old file layout, and one record at a time creates a new record, using the new file layout, with the same data, saving it to the new data file.

When it is done upgrading, the progress bar window is closed, and the file is reopened in the fashion you described in your call to fnOpen, and flow returns to your program as though nothing unusual has happened.

If an error occurs during processing, the routine will do what it can to roll your data files back to the previous version, but please make frequent backups of your data files anyway, just to be safe.

'''''Error Checking – If there is a mistake in the file layout:'''''
The routine attempts to discover the cause of the error in the case that one is encountered due to a missing file, a file sharing violation, or an invalid or corrupt file layout. If this should happen, the program is paused, and a text message is printed out explaining the most likely source for the error, including what part of the file layout, if any, may have caused the error.

You may then examine the printed text, and the contents of the BR system variables ERR and LINE to determine the problem. If you type “GO”, the next line will be execute “system”, ending your program.

If the file was in the middle of an upgrade when the error happened, it will be automatically rolled back to the previous version, so that when you fix the problem and try to run your program again, the file will again attempt to update from the beginning, and you won’t have to worry about corrupted data.

However, please backup your data before upgrading your data files anyway, just to be safe.

'''''Implementation of Keys / Creation of New Data Files:'''''
The library has been expanded to automatically create all new data files, and to automatically update any existing files. This means that in the file layout header, two new fields that were previously ignored are no longer ignored. The RECL value that you specify in your file layout will be used, along with the description/definition of your keys file. When you open a new file (or update an existing one), the library will calculate the proper kps and kln by evaluating the key description. This key description must match up with subscript values from the data elements in your file, and more then one may be specified, but they must be separated with slashes (/). If I wanted my Farm File to be keyed based on CODE and NAME, the proper key description would be:

farm.key, CODE/NAME

The library will then look up the position and length on disk of the CODE and NAME fields and put them together to create the proper keys during an update or creation of a new file.

'''''DataCrawler:'''''
Perhaps the most exciting new addition to the library is the addition of a programming tool I like to call a DataCrawler. If you run the FileIO Library directly as a program, instead of using it as a library, it will function as a DataCrawler. The DataCrawler requires a New Gui version of BR, as it requires a ListView to be able to properly and easily display the data in your files.

If you run it in an older version of BR you will get a message, telling you to run it in a newer copy. If you run it in a New Gui version of BR with CONFIG GUI OFF, then GUI will be turned temporarily on for the use of the DataCrawler and then turned off again when you are finished. If you run it in a New Gui version of BR with GUI ON, it will just run normally.

When you run the DataCrawler, first you will see a ListView displaying every file layout it can find in the filelay folder. If you select a file, the DataCrawler will open a large ListView with as many columns as there are fields in the file. The Column Headings will come from the element descriptions in your data files, and the column widths will come from the displayed width of the fields. There will be a row for every record in your data file, and you can resize the column widths, and scroll around the data file to view the raw data of your BR data files on disk.

If you are dealing with a particularly enormous data file (50,000+ records) it can take a moment to populate the ListView with the data in your data file. You may hit ESC to stop loading if you like, and view only the already loaded records.

If you would like to look up a particular record (based only upon the primary key for the data file), you may press F4. This will give you a window which asks you to input the key or partial key. When you press enter, the file will be reloaded, starting at the key you specified and continuing on to the end of the file, or until you press ESC. The records you are looking for should appear at the top of the ListView.

To reset the ListView and look at the contents of the entire file again, simply press F4, and enter a blank (“”) key.

Finally, as with any ListView, you may resort your data by clicking on any of the column headings. Then you can use the slider bar at the right to scroll down to the record you desire.

This is a programming tool and is not designed to be used by an end user. This tool will open your file in read-only mode. It will not allow you to modify the data; I leave that as an exercise for the reader. However, it will update any datafiles you view to the latest version (if they need to be updated) when it opens them, just as any other program that uses the library will do.

== Appendix (Examples)==

=== Example.br ===
00010 ! example.br - This program is an example of for the data reading simplification
00020 ! Copyright April 2006 by Gabriel Bakker
00030 ! Distributed open source as a Christmas gift to brag members
00040 !
00100 execute "config gui off"
01020 DIM form$(1)*255
01030 DIM color$(1)*255,color(1)
01040 DIM colorcat$(1)*255,colorcat(1)
02020 library "fileio": fnopenfile, fnreaddescription$
04000 !
04010 Openfiles: ! Open your files here
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)
06000 ! gosub WriteFiles ! If you want to test this line, make sure to drop flag from 4030
07000 !
07010 MainBit: ! This'un here's tha Main Bit
07030 RESTORE #ColorFile:
07100 ReadNextcolor: ! Read next record
07120 read #ColorFile, using form$(ColorFile) : mat Color$, mat Color eof EndReadColor
07180 PRINT Color$(co_name)&" ("&Color$(co_html)&") is a member of the '";
07190 PRINT trim$(fnReadDescription$(ColorcatFile,cc_Name,Color$(co_category),mat Colorcat$,mat Colorcat,mat form$))&"' category."
07290 goto ReadNextColor
07300 EndReadcolor: ! Finished with Color File
08000 STOP
25000 !
25010 WriteFiles: ! Uncalled routine to demonstrate writing files
25105 let color$(co_code)="GD" !:
let color$(co_Name)="Gold" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFD700"
25110 write #colorfile, using form$(colorfile): mat color$, mat color
25115 let color$(co_code)="LV" !:
let color$(co_Name)="Lavender" !:
let color$(co_Category)="BL" !:
let color$(co_html)="E6E6FA"
25120 write #colorfile, using form$(colorfile): mat color$, mat color
25125 let color$(co_Code)="OR" !:
let color$(co_Name)="Orange" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFA500"
25130 write #colorfile, using form$(colorfile): mat color$, mat color
25205 let colorcat$(cc_Code)="YL" !:
let colorcat$(cc_Name)="Yellows" !:
let colorcat$(cc_html)="FFFF00"
25210 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25215 let colorcat$(cc_Code)="BL" !:
let colorcat$(cc_Name)="Blues" !:
let colorcat$(cc_html)="0000FF"
25220 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25300 return
40000 !
40010 Open: ! ***** Function to call library openfile and proc subs
40020 def fnOpen(FILENAME$, MAT F$, MAT F, MAT FORM$;INPUTONLY,KEYNUM,___,INDEX)
40025 dim _FileIOSubs$(1)*50
40030 let fnopen=fnopenfile(FILENAME$, MAT F$, MAT F, MAT FORM$,INPUTONLY,KEYNUM,MAT _FileIOSubs$)
40040 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
40090 fnend
50000 !
60000 Ignore: Continue

Color File Layout
color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

ColorCat File Layout
colorcat.dat, CC_, 0
colorcat.key, CODE
recl=127
===================================================
CODE$, Category Code, C 6
NAME$, English Name for Color, V 30
HTML$, HTML Code for the Color, C 6

Example Layout showing multiple keys (price)
price.dat, PR_, 0
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2

[[Category:Utilities_Third_Party]]

FileIO Library

2024-09-11T15:49:43Z

Gordon.dye: /* How it Works */

The '''FileIO''' Library began as a project to find a way to reduce the effort associated with making changes to data file layouts. Thanks to the Fileio library, when I have to make a change to a data file layout for my customers today, I can complete the task in under 1 minute, and not a single program needs to be changed in order to continue working with the new file layout. In fact, I don’t even have to update my customer’s data files, as the FileIO library takes care of this for me as well.

The trick is to define each of your file layouts in an ASCII text file layout file that is described below. The FileIO Library will parse through your file layouts, and it will instruct your programs how to access the file data after it has been read. It will also automatically detect when you make changes to the file layout, and it will update your customer’s data files on the fly to make sure they have the latest version. Finally, it contains a DataCrawler that you can use to examine the contents of any of your BR data files in a raw format.

For more information about the FileIO Library visit the [http://www.sageax.com/products/fileio-library/ Sage AX Website]

To download the latest copy of FileIO, click [http://www.sageax.com/downloads/FileIO.zip here.]

== Method of Operation ==
The file IO library parses a formatted text file layout and uses this information to structure the opening and the reading of a file “object”. The word object here is used to refer to all the data in a given record layout in one of your files. This library is easy to use, and provided you follow some simple standards, it will simplify your life immensely.

Your programs will need to define one array for all [[Form|BR data file form statements]] and add a snippet of code (given below) to the program for interfacing with with the library. For each file you will need to define a couple of arrays and use the library to open them. From that point on access to data is simple and direct.

=== File Object Arrays ===

First, in your program you must create two arrays to store the file information. If we are dealing with the Color File these would be MAT COLOR$ and MAT COLOR. One will store all the string information about a color, and the other will store the related numeric data. Our working example will involve two files: a Color File and a Color Category File. You should dimension these as follows:

01030 DIM color$(1)*1000,color(1)
01040 DIM colorcat$(1)*1000,colorcat(1)

We're dimensioning the string array elements to 1000 bytes each. This is the length of one field in the color file. The array element length needs to be at least as big as the largest string field in the data file.

However, it is recommended to make sure the length is long enough to handle any field you might eventually add to the file at any point in the future. BR supports multi-line textboxes, so I sometimes add long memo fields to my data files that might be 400 or 800 or even 1000 characters long, therefore 1000 is the length I use now in all my new development.

But anything will work as long as its long enough to handle the largest data field in your file.

=== Forms Array ===

Your programs will need a string variable array to store the form statements associated with reading files. This form statements array will be dynamically generated or expanded whenever the a file is opened. It will say:

01020 DIM form$(1)*255

This form statement will be compiled by the FileIO open statement. BR limits all compiloed form statements to 255 bytes, so 255 is sufficient to hold the compiled Forms$ statements.

=== Library Linkage ===

You will also need the library statement:

02020 library "fileio.br": fnopenfile, fnreaddescription$

=== fnOpen Function ===

Now, add the following snippet of code to interface with the library. Note that this snippet can be copied in exactly as provided and no customization of it is needed.

Because BR libraries do not share global variables with the programs they are called from, we will need to execute a procedure file whenever we open a file - to set the names of all of our variables. Add the following snippet of code into your program. It will create an FnOpen function that calls the library and runs the proc file. The $$$ at the end of the procfile name tells the procfile to self-destruct after execution. Since this procfile is used simply to return variable information back from the library to the main program, we don’t need it sitting around collecting dust.

99010 OPEN: ! ***** Function To Call Library Openfile And Proc Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
99030 dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
99050 if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
99060 fnend

Or, for those with [[Lexi]]: (same but without line numbers)
OPEN: ! ***** Function To Call Library Openfile And Proc Subs
def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
fnend

=== Using FileIO in Your Programs ===
Now you are ready to process files. 
'''''You simply open the files by saying:'''''

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

'''''read each file as follows:'''''

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
'''''and access the data:'''''

30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name)

=== How it Works ===
The above statements tell the File Library to look in the filelay folder to find the file layout for the Color File, and read it to find out what the Color File looks like. Then it OPENs the Color File, and sets MAT COLOR$ and MAT COLOR to the correct number of elements to hold an entire color record. Finally, it will define several variables that we can use as pointers (subscripts) into these arrays to access the data read into the 2 arrays, and it will assign the file handle to a variable called "colorfile".

The second open statement above will do the same thing to the color category file, except the parameter value "1" tells the function to open readonly. The array subscripts assignment procedure file (passed back from Fileio) will be executed, thereby assigning values to the subscript names in the calling program. So, if I had a file layout such as the following:

color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

Then the functions would do the same thing as the following individual lines of code (assuming the next available file handle was 5):

DIM FORM$(5)*255
DIM COLOR$(9)*1023, COLOR(1)
OPEN #5: “Name=color.dat, kfname=color.key”,internal,outin,keyed
LET FORM$(5)=”form C 6,V 30,V 6,C 6”
LET FORM$(5)=CFORM$(FORM$(5))
LET COLORFILE=5
CO_CODE=1
CO_NAME=2
CO_CATEGORY=3
CO_HTML=4

The data is used by referencing the file array, with the subscript name, so the color’s description becomes color$(co_Name).

In the old days, if we wanted to change the file layout of our file, all of the programs that used that file would have to be changed one at a time to use the new file layout. Also, if the order of the fields changed, then all the programs would have to also be changed to use the new fields.

But now, using this function, we can change the file layout all we want. If we later want to insert a field into the file layout before color name, I won’t have to look at this program again; this program will just work fine, because the library maps the subscripts to the actual fields.

Also, the code is easier to read and maintain.

=== Example ===
The whole thing looks like this:

01025 ! Dimension the Arrays
01030 DIM color$(1)*1023,color(1)
01040 DIM colorcat$(1)*1023,colorcat(1)
01050 DIM form$(1)*255
02000 !
02020 library "fileio.br": fnopenfile, fnreaddescription$
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$) ! Open the file
05000 !
30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore ! Read the file
30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name) ! Use the data by referincing it in the file arrays
80000 !
90000 ! Every program using fileio needs the following code
99010 OPEN: ! ***** Function To Call Library Openfile And Generate Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths)
99030 dim _FileIOSubs$(1)*800
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$)
99050 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
99060 fnend

== File Layouts ==
Now lets inspect the anatomy of a properly formatted file layout. These should be placed in a subdirectory called filelay.

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...
<hr>
price.dat, PR_, 1

The first line contains the name of the Farm File, a unique string to prefix all of your subscript pointers, and the file version number. The subscript value is to ensure that the program knows the difference between the Farm File’s Farm Code, and the Route File’s Route Code. (One will be RT_CODE and the other is FM_CODE). These are separated by a comma. Spacing does not matter, so adjust your spacing so that it looks nice.

The Version number is used to determine when the data has changed, and an update needs to be made to your data file. Your file layouts should all start at version 0, and each time you want to make a change, you may increment this value by 1.

Each time you open a file with the FILEIO library, it reads the file version number of the file on disk (using the BR version() function), and then it compares it to the version number in your file layout. If your file layout has a higher version number then your existing data file, then the library opens the backup of the file layout for the version of the data file that exists on disk. It makes a backup copy of the existing data file, and creates a new file with the proper version number. Then it reads your records one at a time, and copies all the data from the old file into the new file one field at a time. If a field is dropped from the file layout, that data gets lost. If fields are rearranged, the data is copied and saved in the new file in the new positions. If a new field is added, it starts out blank (or 0).

If you look in the filelay folder, you will notice a version folder. This contains several files ending with a number. For example you may see a color.0, and a color.1 file.

If you run the fnopen function and it can not find your data file (usually because this is a new file and it hasn’t been created yet), ''the library will automatically create your file,'' based on the information you give in the first part of the file layout.

Also, whenever you make changes to your file layout, the function library will automatically update the data files on disk for you. It does this by renaming the old file, creating a new one with the new version number, and then copying the data from the old one to the new one a record at a time.

Any time it creates a file, or updates the file on disk, it creates a backup of the file ''layout''. The first time you run a program that tries to read your new data file, it will create the data file for you and make a backup of the layout, and if the number in your file layout is 0, then it will create, for example, a filelay\version\price.0 file, a backup of your file layout that the library uses to figure out what has changed the next time you try to update the file.

If you wish to make any changes to this data file, first you increment the version number, (in this case make the 0 into a 1). Then change the file layout all you want. You may rearrange fields, add new fields, add or remove keys, or change the record length.

The only step necessary for having your data files updated is to increment the version number every time you make a change to the file layout.

You may make any changes you like to the file layouts, but do not change the names of your existing subscripts. If you change the subscript name, not only will all the programs that reference that subscript be broken, but additionally, the routine will not understand that you are changing the name. It will think you are dropping the old field and adding a new field and any data stored in this location will be lost when the file is updated.

price.key, FARM

The second line contains the name of the first key, and a definition telling what the key is based on. These are separated by a comma. The key definition is made up of each of the subscript names in this file that form the keyfields for the file. When the library is called to open a file, if the file does not exist, or if it needs to be updated, a new one will be created. The function will read these subscript names that form your key definitions, and it will calculate the proper key position (KPS=) and length (KLN=) values. Then the create routine will use this information with the Index command to create the new key files.

price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127

Notice that the third key is based on three different fields. These are separated by a “/”. It is important that you use a “/” to separate your keys when you are building a key out of more then one field, because the function uses this “/” to help it make the proper BR syntax for defining complex key fields.

Also, note the "-U" at the end of the fieldname in the 4th key. This indicates that the "Description" part of that key is case insensitive. This translates to using the "U" on part of your key spec in Business Rules.

The file can have as many keys as you want. The function will keep parsing key file names until it reaches the next part of the layout. It opens any OutIn files with all keys so that any changes you may make to the data stored on disk will be properly reflected in all the key files.

The optional RECL= Parameter is read and used whenever a new file is created or an old one is updated. If it is not specified, the record length is calculated from the fields in the layout.

===================================================

The next line in the file is skipped by the parsing routine, and its purpose is to make the file layouts more readable to a programmer.

 
FARM$, Farm Code (or blank), C 4

Following the file and key structure, the fields are defined. There are three parameters on each field definition line, and you make one line for each field in your file layout. The first parameter is the subscript name that you will use in your program to refer to this data element. Place a $ at the end of the subscript name for all string elements. Don’t place anything at the end of the subscript name for numeric elements. Note that each of these names will be prefixed by the second parameter of the very first line of this layout.

The second parameter is the description. This description is for the benefit of the programmer, so when the programmer is reading the file layouts, (s)he can tell which field does what. The spaces are ignored, so you may include as many spaces as you wish to make the layout look good. It does seem like good general guidelines would be to limit your layout lines to 255 characters and your descriptions to 80.

The description is also used by the built in DataCrawler, a program that reads any of your data files and displays the entire contents in raw form in a listview. The Descriptions become the headings for each column in the listview.

Those descriptions are also used for the default captions for your fields if you use ScreenIO, a library for building GUI programs that itself builds off of fileio.

The third parameter is the form statement, which is pretty straightforward. Any items with a form statement of type “X” will be ignored, except that the length will still be used to calculate the position on disk of all remaining fields in the record. The library will take X fields into consideration when building the form statement, but not at any other time.

The fourth parameter is optionally a [[#Support for Dates|Disk Date Format]]. You can specify DATE(Julian) if you're storing your dates in Julian format on disk. Or you can specify DATE(cymd) or DATE(ymd) or DATE(mdy) or any other valid date spec here, and FileIO will treat this field like a date.

Your programs will still have to unpack it for you, fileio can't do that because fileio doesn't read the file for you.

However, the data crawler, the automatic updates, and screenIO, are all compatible with these dates specified in your file layout.

If the fourth parameter is anything other then DATE(format), then its treated as a comment and ignored.

The fifth and all later columns, if any, are treated as comments and ignored.

! default cost is normally zero
Comment line text must begin with an exclamation point, but it may be indented. Comment lines may appear anywhere (vertically) and are ignored. 
Blank lines are ignored as well.

#eof#
additional comments...
After the last field definition, an ''optional'' #eof# line may be specified, in which case any lines after that will be ignored.

 
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...

And that’s all there is to it.

=== Support for Dates ===
As of V2.48, file layouts support dates in any storage formats on disk. Whether you store your dates in Julian or in YMD or MDY or any other format, specify so in the 4th column of your file layouts, using the FileIO Date Keyword. ex: DATE(Julian) or DATE(YMD) or any other valid BR Date Format.

[[File:Dates0.png]]

When this is specified, it enables the FileIO data exploration tool (Data Crawler) to display the dates in human readable format. This works for both Viewing, and for Editing.

The new Date functionality also supports the File Layout Upgrade facility, allowing you to change the format of your dates on disk and FileIO will handle it automatically, upgrading the field to use the new date format for you.

It works also for Exporting your data files to CSV, and is supported automatically in the FileIO functions that do those exports. It converts the dates on export to a standard format (Default: m/d/cy) that you can specify in your FileIO.Ini File.

And it extends ScreenIO's date features to all date fields, no matter what format they're stored in. (Previously, ScreenIO's advanced date features only worked for dates stored in Julian on disk.)

This update adds two new ini file options:
CODE: SELECT ALL
DateFormatExport$='m/d/cy' ! Format of Dates when Exporting to CSV
DateFormatDisplay$='m/d/cy' ! Format of Dates when displaying in Data Crawler

You can use these to specify your preferred Date format for Viewing/Editing, and your preferred Date format for Exporting.

Remember, you can see the full list of FileIO ini file options, by looking in the source code at the top of FileIO.

There is a new optional parameter for all layout reading functions, mat NDateSpec$ and mat SDateSpec$ which correspond with the other arrays, to let you know which fields are date fields, so that you can develop routines in your programs to automatically pack and unpack the dates.

Important Note: Using FileIO, the reading of the data file is still done directly in your programs. So this does not change how your existing programs work. It does not unpack the dates for you in your programs. You still have to do all that.

For this reason, upgrading to the new Date processing will not break any of your current code.

=== Debugging Tips ===

When you're making new layouts, a missing comma can cause FileIO to parse the layout wrong and give you errors. Here are a couple tips to help ensure your layouts are error free before using them in your programs.

*Use the Data Crawler to test your layout. The data crawler is the simplest way to test your new layout without writing any code. It opens it and accesses the file in a very simple and straight forward manor to help identify any errors in the layout that you might have.

*If you have trouble with the form statement, you can't see whats in it because FileIO uses CForm$ to compile your form statement to make your programs run faster. But here's a way to tell what the original form statement was that FileIO generated when it put the strings first and numbers last in your program: Open the file in the Data Crawler. When you get an error, type "Print FormStatement$" to see the original form statement.

This works even if your file is working fine. Any time the file is opened with the data crawler, you can press CTRL-A and then type PRINT FormStatement$ and it will print out the uncompiled form statement for the file.

== Utilities ==

Now that you have your file layouts defined, you have access to several powerful utilities right out of the box using Fileio. Additionally, several more utilities are available as [[#FileIO_Add-on_Packages|Add-Ons]], including our most popular development tool [[Screenio|ScreenIO]]. You can read more about them in their section below.

But for now, lets take a look at some of the wonderful free utilities that come built into Fileio.

Some of these utilities are accessible from your code via library functions, but the primary way you access any of them is by simply loading the FileIO Library and running it directly.

=== DataCrawler ===
The data crawler is the original utility of FileIO. This utility shows you first a list of all data files allowing you to select one.

Select a data file and press enter, and FileIO will then display a listview containing all the data in the data file. This list is sized based on the size of your main BR window (window 0) automatically to take up the full size available to it, so if you want to see more, try [[Open Window|opening window 0]] larger before running FileIO.

At the top of the window is a filter box, and you can type anything you want in there and click "Refresh" and it will reread the data file, shortening the list to show only those records that match (case insensitive) what you have typed.

If you have ScreenIO installed, then FileIO's data crawler will take advantage of the included Animation Engine in ScreenIO to animate a loading window while the listview is displaying. If you don't have ScreenIO then FileIO will simply load the listview.

If you don't want to wait for the entire file to load, press ESC to stop the load process.

If the file is empty, FileIO will display a message box letting you know.

This tool is very useful for sorting out data errors. It will allow you to look inside any data file you have a layout for and directly view the data there.

At the bottom of the Data Crawler are several buttons. There's a Jump button that repositions the file by a key you specify and then loads the list with the data from that key on down to the end of the file.

There is a "Columns" button which you can use to decide which columns should show up on the listview. Fewer columns means faster loading so sometimes for large files I press ESC immediately when the file first starts loading to cancel the load. Then I click "Columns" and check only the columns I want to see. Finally I press the "Refresh" button to trigger it to read the file again and this time it loads much faster then before.

Next you'll find an Export button which starts the process for exporting a file to CSV. You can read more on that in the next section. And next to that is a Quit button.

In this example, we loaded the file "Read Only" so it put everything in a listview. But there are times when its useful to fix data errors this way too, especially during development. So if you want to directly edit your data file, on the first page select the file you want to edit and instead of pressing "Enter" or clicking "View", this time press "F5". F5 is the secret Edit button that loads a data file into a grid instead.

You can use the grid to change records, delete them or add them, and in addition to the buttons listed above, it also has an "Import" button for importing a CSV file into this data file.

Any changes you make to the data file are not saved until you click the "Save" button (which also only appears when you're in Edit mode).

In the 01/2015 release of FileIO, each records rec # is displayed in the listview, to aid in debugging bad data problems.

==== Debugging Tip ====
Any time you're viewing a file layout in the Data Crawler, you can see the Uncompiled Form Statement by pressing CTRL-A to get to an ATTN prompt, and then entering the command:

print FormStatement$

and it will print out the original form statement.

==== Another Debugging Tip ====

The FileIO Datacrawler ignores records that it cannot read. This is to allow for data files that have multiple record layouts in one data file. You make a custom layout for each record type and the data crawler shows just the records that match that type in the file.

However that becomes a problem when you're making a layout to work with an existing data file. Error 726 indicates that something minor in the file layout doesn't match the data on the disk, but these errors are ignored so you might see either an empty data file, or a data file with some records missing. If that happens, you need to see the missing records in order to figure out what is wrong with your layout. '''''It's very important that you don't try to use a file layout that isn't quite working right. Make sure your layout works and can read every record of a file that it should read before using it.'''''

To see the records that could not be read in a file, run the data crawler on the layout, then press CTRL-A to get an ATTN prompt. From there, enter the command

print mat BadRead$

and it will print all the records that were ignored because the file layout didn't match them. It prints out the raw data from the file.

==== Function Access to use Data Crawler in your programs ====
You can use the data crawler in your own programs by using one of the following functions:
* [[#fnDataCrawler|fnDataCrawler]] - Open a Listview showing the data file
* [[#fnDataEdit|fnDataEdit]] - Display the data in an editable grid
* [[#fnShowData|fnShowData]] - This function does the same thing as the above two, but with many many more options allowing you to customize exactly what appears and exactly what they're allowed to change.

Note: its not recommended to allow your customers to use the data crawler to access your data files directly. There's no way to specify validations or do anything complicated, so unless you're careful, there are lots of ways your customers could use this tool to do damage to your data files. It is a programmer tool only.

If you do decide to use it for your end users, be careful how you implement it.

=== Import/Export to CSV ===

You can use FileIO to export your data files to CSV or import from CSV into your data file. To do this, you want to run the data crawler and select the file layout you're looking for. Then, view it (or press F5 to edit if you want to import something). Click on the Export button and it will ask you to select a file. Once that is selected it will ask a couple other simple questions, and when you've specified the options to your satisfaction, click the Export! button. A new CSV file will be created.

Import is even more simple. To import, you must be in Edit mode (press F5 to select the file instead of the enter key) and then simply select the Import button. It will ask you again to choose the file, and then it will ask you if it should update all files by Record Number (if record number is recorded in the CSV file) or by Key (if the file has keys) or to just Add all information to the file. Select what you want and press Import and the CSV file is added to the BR data file.

==== Function Access to Import/Export from your programs ====

You can use the following functions to call the Import and Export functionality from your code.

*[[#fnCSVImport|fnCSVImport]]
*[[#fnCSVExport|fnCSVExport]]

These functions are intended to give you the ability to use our functionality to write your own import and export routines for your customers, because its not a good idea to let your customers run the Data Crawler.

=== Generate Layout Wizard ===

There is also a Generate Layout Wizard utility in FileIO. This utility is there to help you build your file layouts. It is designed to work with a certain style of BR programming that was common in the 80s and 90s. So if your software is written in a style that opens the file directly, and reads/writes the data to a long series of individual variables, the Generate Layout Wizard is for you.

To use it, start by running FileIO. Then, don't select a layout - instead, click on the "Generate Layout" button.

You'll see a screen with a bunch of large text boxes, a small grid, and some buttons.

The first thing you want to do is select the "Browse" button and then select a .wb or .br file that contains a program that reads or writes Most of the File.

When you select one, press the Scan All button and it fileio will search the whole program looking first for all the open strings. It will take the file that is opened the most times and then search for all read statements to that file. It will look for the longest read statement and then find the Form statement associated with that Read statement, and any DIM statements for any variables used.

If you don't like the file its chosen, click the "Open Scratch Pad" button to open the temp work file it uses into the program of your choice (I use myEdit for BRS files). Simply select all the open statements for the file you DO want to build off of, then click the Paste button to paste those open statements into the "Open String" list. After that click "Clear All" to erase what it did on the first search and then click "Scan All" again to rescan the program using this new data file.

You may have to help it a bit, but once it has a proper matching open statement, read statement, form statement and dim statements for any arrays used, press the "Generate Layout" button and it will build a layout for that file.

Finally, load the layout it built and clean up anything if you want, and consider adding better descriptions for each of the fields that you know (as it will use the variable names for both the subscripts AND descriptions in the layout).

When you're all done, click "Done".

==== Functions to Generate Layouts from your code ====

* [[#fnGenerateLayout_.26_fnWriteLayout|fnGenerateLayout]]
* [[#fnGenerateLayout_.26_fnWriteLayout|fnWriteLayout]]

=== Code Templates ===

One more tool FileIO has to help is the ability to generate code based on your file layouts.

Run FileIO and this time select a file layout and press "Generate Code". A window will pop up listing all the "Code Templates" that are available. Select one (and then select a key if it asks you - some templates require extra info). It looks like nothing happened, but the code you generated is now in your clip board. Paste it somewhere and take a look at it!

Code Templates help us to standardize our ways of doing things, which eventually leads to more and more powerful tools we can use. Code Templates also help ensure we use cleaner code by doing some of the busy-work of writing clean code for us.

==== Writing Code Templates ====
FileIO ships with several basic code templates. If you want to add your own, take a look in the filelay\templates folder (configurable in fileio.ini) and look at basic.brs. Copy it to your own program and then modify it to have your own code templates in it. Write me at gabriel.bakker@gmail.com with any questions. I want to help.

And if you write good code templates, its easy to share them with the BR community. Anyone can download your templates and place them in this folder and they'll instantly be available for use.

== FileIO Function Reference ==
''The FileIO Library contains a number of other useful functions.'' The following functions are available and you are welcome to use them:

=== Primary Functions ===

==== fnOpen ====
fnOpen is the primary function that opens a file, and it’s used like so:

''def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, DontSortSubs, Path$*255, Mat Descr$, Mat FieldWidths, SupressPrompt, IgnoreErrors, SuppressLog)''

Note that all of the parameters after MAT Form$ are optional. If you need to specify a parameter in the middle of the optional parameter group, just list zeroes and empty strings for the intervening unused parameters.

*FileName$ - The filename of the file layout for the file you’re reading.
*MAT F$ - The array that will be used to hold the string data for the file.
*MAT F – The array that will hold the numeric data for the file.
*MAT Form$ - An array of form statements.
*InputOnly – 1 means open for input only. 0 means open for OutIn and open every key file associated with the given data file (this is because all key files need to be open for the keys to be updated on an output) (defaults to 0). Files opened for input process considerably faster than files opened for output. Furthermore when files are opened for input only, alternate key files are ''not'' opened.
*KeyNum – This tells the function of which key to return the file handle (defaults to 1). Specify -1 to force the file to open Relative, without using its keys. If a file has no keys, it will always be opened Relative.
*DontSortSubs – The function by default, when compiling the Form statement, will sort the string and numeric subs in order to allow for reading the data into an array, and this parameter would turn this functionality off. However, if you are trying to read your data without reading it into an array, you are missing out on some serious efficiencies. You should normally leave this option turned off (0). This is a totally unsupported feature, and should always be set to 0, if it is specified at all.
*Path$ - The path to your data files. This optional parameter can be passed in by the calling function. It is prefixed to the beginning of the paths given in the file layout files. It is useful when your data files can be in different locations depending on the state of your program.
*mat Description$ - This optional parameter provides a way to read the description for each field from the original file layout. If the parameter is not provided, no description data will be returned.
*mat Fieldwidths – This optional parameter will return an array of the calculated display field widths. This number will always be at least large enough to contain the data for this field.
*SuppressPrompt - This optional parameter can be used to suppress the prompt normally given when fileIO creates a file. It can have three values. A value of 0, the default, uses the setting stored in your FileIO fnSettings routine to determine weather or not to prompt on Creation of a new file. A nonzero value always suppresses the prompt. A value of 1 indicates never to create a file if the file doesn't exist. A value of 2 automatically creates the file if the file doesn't exist.
*IgnoreErrors - Normally when fileio opens a data file, if there are errors trying to open the file, it prints them out to the debug console and pauses so that you can try to find out whats going wrong. If you specify 1 for "IgnoreErrors" it will cause Fileio to log those errors instead, and continue loading your program. This will result in the fnOpen file function returning Zero instead of the opened file number, so if you use IgnoreErrors, you need to test to make sure that fnOpen returned a file number before you try to access the file.
*SuppressLog - this optional parameter can be used to suppress writing to the log file for this one specific open statement. I use it for files that will be opened all the time, for example, the menu data file on one of my customers systems. Without this boolean parameter, his log file is quickly filled up with useless information any time his employees look at his menu. I specify this optional parameter to suppress logging anything about the menu file so that I can more easily find the actual programs they've used when looking in the logfile.

'''''Note: When using fnOpenFile, you really want to call your local function fnOpen, which in turn calls fnOpenFile for you.''''' FnOpenFile is for internal use only.

Example:

Let FFILE=FNOPEN(“FARM”,MAT FARM$,MAT FARM,MAT FORM$,0,2)
Let RFILE=FNOPEN(“ROUTE”,MAT ROUTE$,MAT ROUTE,MAT FORM$,1,3)
Let CFILE=FNOPEN(“CUSTOMER”,MAT CUSTOMER$,MAT CUSTOMER,MAT FORM$)

assuming:
farm.dat has 3 keys: farm.ky1, farm.ky2, farm.ky3
route.dat has 4 keys: route.ky1 … route.ky4
customer.dat has 2 keys: customer.ky1, customer.ky2

This will perform the following opens and set the following variables:

OPEN #1: “Name=Farm.Dat, kfname=farm.ky2”,internal,outin,keyed
OPEN #2: “Name=Farm.Dat, kfname=farm.ky1”,internal,outin,keyed
OPEN #3: “Name=Farm.Dat, kfname=farm.ky3”,internal,outin,keyed
OPEN #4: “Name=Route.Dat, kfname=route.ky3”,internal,input,keyed
OPEN #5: “Name=Customer.Dat,kfname=customer.ky1”,internal,outin,keyed
OPEN #6: “Name=Customer.Dat,kfname=customer.ky2”,internal,outin,keyed
LET FFILE=1
LET RFILE=4
LET CFILE=5

This will also resize the arrays, set the form statement, and create all the subscripts to make accessing the data clear and simple, as in the above example. The KEYNUM parameter is where you list the key file you would like to use for reading and writing. The extra keys are opened to ensure that all keys get updated properly when the file is changed.

Example:
DIM FORM$(1),PRICE$(1)*255,PRICE(1),
DIM DESCRIPTION$(1)*80,FIELDWIDTHS(1)

Let PRICEFILE=FNOPEN(“PRICE”,MAT PRICE$,MAT PRICE,MAT FORM$,0,2,0,"",MAT DESCRIPTION$)

Assuming the Price File layout (filelay\price) contains:

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30

This will perform the following opens and set the following variables:

OPEN #1: “Name=Price.Dat, kfname=Price.ky2”,internal,outin,keyed
OPEN #2: “Name=Price.Dat, kfname=Price.ky1”,internal,outin,keyed
OPEN #3: “Name=Price.Dat, kfname=Price.ky3”,internal,outin,keyed
let PRICEFILE=1
let PR_FARM=1
let PR_ITEM=2
let PR_GRADE=3
let PR_DESCR=4
let PR_PRICE=1
let PR_COST=2
let PR_XOPRICE=3
let PR_XOCOST=4
let PR_MOPRICE=5
let PR_MOCOST=6
let PR_VOPRICE=7
let PR_VOCOST=8
MAT FORM$(1)
MAT PRICE$(4)
MAT PRICE(8)
MAT DESCRIPTION$(12)
MAT FIELDWIDTHS(12)
let FORM$(1)=CFORM$(”form C 4,C 4,C 4,POS 74,C 30,POS 50,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2”)
let Description$(1)= “Farm Code (or blank)”
let Description$(2) = “Item Code”
let Description$(3) = “Quality”
let Description$(4) = “Description of Price Rule”
let Description$(5) = “Default Price”
let Description$(6) = “Default Cost”
let Description$(7) = “Default Christmas Price”
let Description$(8) = “Default Christmas Cost”
let Description$(9) = “Default Mothers D Price”
let Description$(10) = “Default Mothers D Cost”
let Description$(11) = “Default Valentine Price”
let Description$(12) = “Default Valentine Cost”
let FieldWidths(1) = 4
let FieldWidths(2) = 4
let FieldWidths(3) = 4
let FieldWidths(4) = 30
let FieldWidths(5) = 8
let FieldWidths(6) = 8
let FieldWidths(7) = 8
let FieldWidths(8) = 8
let FieldWidths(9) = 8
let FieldWidths(10) = 8
let FieldWidths(11) = 8
let FieldWidths(12) = 8

There are a few things I’d like to point out about the example above. First, you will notice that the form statement jumps around to put all the strings first, and then the numbers last. This is why it has a “POS 74, C 30,POS 50”. Then notice that the subscripts for the string variables are 1 .. 4, and the subscripts for the numbers are 1 .. 8. Finally, the order of the Description and FieldWidth fields also match the sorted positioning of the Form Statement.

The reason that we sort our form statements is so that BR will allow us to read the file into arrays by saying:

Read #pricefile, using form$(pricefile) : mat price$, mat price

Without resorting, the above statement would give a conversion error as BR attempted to put the PR_PRICE field inside mat price$(4). However, because we have reordered the form statement, we are able to read them safely into two arrays, and then we will be able to use the values without caring what position they are in the file, by simply saying PRICE$(PR_DESCRIPTION) when we want the description, and PRICE(PR_PRICE) when we want the pr_Price field.

Another thing you may notice about the above example is that it gives the calculated display length for the numeric fields as 8, when on the disk (and in the file layout) they are listed as BH 3.2. The reason for this is the program looks at the BH 3, and figures that a number that takes up 3 bytes on disk has a potential maximum size of 256**3 or 16,777,216, and therefore will need up to 8 characters of screen display space to view.

Finally, note that any field with a form statement of X is ignored by the library, except that the blank space is used when building the FORM statement.

==== fnCloseFile ====
This function will close the specified file number and all keys that were opened with the file. The purpose of this function is to facilitate the closing of the extra keys that are opened when you open a file for OutIn with the library. There is no need to use this for files opened for input because it is easier to just close the file directly. Secondary keys are not opened by FileIO for files opened for input only.

You must give the function the name of the file layout. It uses this information to determine how many keys were opened, and how many it must therefore close.

Then it basically starts at the file number you gave it, and closes the next X files that were opened with the same file name as this, where X is the number of keys associated with this file.

The syntax is:

''fnCloseFile(filenumber,filelay$;path$)''

*FileNumber – The filenumber of the file you are trying to close.
*FileLay$ - The name of the file layout for this file. This is used to determine how many keys the file would have been opened with and therefore how many we now need to close.
*Path$ - Optional Alternate Path. Use to close files that were opened using the open file's optional alternate path parameter.

==== fnGetFileNumber ====
FnGetFileNumber is a simple function to find a valid unused file handle. If you use this function in all of your programs, they will become much more portable, as you will never have to worry about your file handles fighting with each other. The function will return 0 if no free file number was found (but with 999 of them available now, I have never seen it happen).

''fnGetFileNumber(;X,Count)''

*X – This optional parameter will specify where to start looking.
*Count - This optional parameter will specify how many file numbers to find in a row. If count is 3, then fnGetFileNumber will return the first filenumber in the first gap of three unused file numbers that it finds.

=== File Reading Helper Functions ===

These functions perform various useful calculations to aid in interacting with data files when you're using fileio.

==== fnBuildKey$ ====
This function will return the key for a given record in a data file. It actually reads the file layout and builds the key to match the layout.

''FnBuildKey$(Layout$, Mat F$, Mat F; Keynum)''

*Layout$ - the name of the data file to build the key for.
*Mat F$ - the string array of the file object
*Mat F - the numeric array of the file object
*KeyNum - This optional parameter specifies which of the key files in the given layout the key should be built for.

To use this, you want some code like in the following example:

mat customer$=("") : mat Customer=(0)
let customer$(cu_name)=CustName$
let customer$(cu_phone)=CustPhone$
read #customer, using form$(Customer), key=fnBuildKey$("customer",mat Customer$,mat Customer,2) : mat Customer$, mat Customer nokey KeyNotFound
! The above code assumes that the second key of the Customer file is based on the Name and Phone fields.

By using this logic you are able to avoid directly specifying the key in your code - which means that even if the key changes in the future, as long as your code specifies enough information, it will still find the correct key. In our example, even if we dropped the phone number from the key in the future, or even if we expand the length of the Customer Name field, our code would still work and fnBuildKey$ would still build the correct key without us having to look at or change our code again.

This kind of reasoning is central to the fileio system, which, when implemented properly, ensures that you can change your data files in any way you need to in the future, without breaking your existing programs.

==== fnUniqueKey ====
This function tests to see if a given key is unique to the specified file. This function is very useful for situations where you need to ensure that the user-entered key is unique.

''fnUniqueKey(Fl,key$*255)''

*FL – The file number of the opened file.
*Key$ - This is the key to test. If this key is the key for a preexisting record in the file, the function will return false. If this key can not be found in the file, the function will return true.

==== fnMakeUniqueKey$ ====
This function generates a unique key for a given file. This is useful if you do not care what the key is, but it needs to be unique. I use this function in situations where the user never needs to know what the given key is.

This function reads the key length for the given file. Then it returns a string that is the right length, which is generated by counting in binary until a key is found that does not appear in the file. The first key found for a 4 byte key field would be chr$(0)&chr$(0)&chr$(0)&chr$(0). If that key was already in use in the file, the function would return chr$(0)&chr$(0)&chr$(0)&chr$(1). If that one was also in use, it would then try chr$(0)&chr$(0)&chr$(0)&chr$(2), and so on until it found one that wasn’t in use.

''FnMakeUniqueKey$(fl)''

*FL – This is the file number of the opened file for the desired key.

==== fnKey$ ====
This function formats the key for the given file number. All it does is ensure the key is the correct length. You should use fnBuildKey$ instead to properly build the correct key for the record you want to read.

''FnKey$(FileNumber, Key$)''

*FileNumber - the file number we are formatting the key for
*Key$ - the key we are trying to format.

==== fnNotInFile ====
This function will determine if a non-key element in a line is unique. It works almost exactly like fnUniqueKey specified above, except that it allows you to enter the subscript value of the element you are checking for uniqueness. You can use this to look for uniqueness in any field, not just in the key field. Additionally, the search engine used by this function looks for a partial match, and will only return true if the given string is not found anywhere in the specified element for the given file.

''fnNotInFile(string$*100,filename$,sub)''

*String$ - Value to check for uniqueness in this file.
*Filename$ - This is the name of the file layout of the file you want to check. This file does not have to be open in order for you to search it, because the function will open it for you.
*Sub – This is the subscript value of the element you are checking.

==== fnSortKeys ====
This function takes an array of Primary Keys indicating records in the data file, and resorts it into the order you would have expected using one of the other keys for your data file.

For example: Lets say you had a customer file, and the first key was Customer Code and the second key was Customer Last Name. This function would take an array of Customer Codes and sort it into Last Name order.

This function requires the file to already be opened (which is usually the case when you have an array of keys from that file).

''fnSortKeys(mat Keys$,Layout$,DataFile,mat F$,mat F,mat Form$;KeyNum)''

*mat Keys$ - the array of keys. These keys are based on whatever key the file was opened with in DataFile.
*Layout$ - the file layout for the file.
*DataFile - the open file number matching the key file that matches mat Keys$.
*mat F$ - array sized to hold the strings from the data file. This is the array you get back from fnOpen.
*mat F - array sized to hold the numerics from the data file. This is the array you get back from fnOpen.
*mat Form$ - array of form statements, that you get back from fnOpen.
*KeyNum - This is the key that we'll sort based on. If not given, the first key listed in the layout is assumed.

=== File Reading Functions ===

These functions actually read information from your data file and return it. These functions can be used to simplify the logic in your programs for many common tasks.

==== fnReadAllKeys ====
This function will read through a file, returning the specified element(s) from each record into (a) dynamically dimensioned array(s). For example, I could tell it to give me the Inventory Code for every inventory item in my database in one array, while placing the Inventory Description (name) for each item into the corresponding position in another array.

''fnReadAllKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$;sub2,mat out2$)''

*Fl – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array
*mat out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

For example:

FnReadAllKeys(InventFile,mat Invent$,mat Invent,mat Form$,IN_Code,mat InvtList$,IN_Name,mat InvtNames$)

==== fnReadMatchingKeys ====

This function will read through a file, returning the specified element(s) from each record where the key matches the specified key into (a) dynamically dimensioned array(s). This function is the same as the above function except this one will filter the results, returning only those records where the key matches the specified key.

''fnReadMatchingKeys(Fl,mat f$,mat f,mat fm$,key$,keysub,sub1,mat out1$;sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - Only records where the key field matches key$ will be returned.
*Keysub – This tells the function which element is the key element for this particular file number.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadAllNewKeys ====

This function will read through a file, returning the specified element(s) from each record that isn’t already there into (a) dynamically dimensioned array(s). This function is the same as the above function, except this one will filter the results returning only those records that don’t already exist in the array (eliminating duplicates).

''FnReadAllNewKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$; dont_reset,sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Dont_reset – By default the array will clear the contents of the arrays that are passed in. This Boolean flag will instruct the function to not empty the passed in arrays.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadFilterKeys ====

This function by Mikhail Zheleznov is a modification of the above functions. Like its predecessors, it reads an entire file, populating the specified arrays with data from all or some of the records in the file. The given subscripts specify which fields to return from each record. The key given specifies search criteria for the records. The filter specifies filtering criteria that can be preformed on the data before it is returned.

''FnReadFilterKeys(Fl,Mat F$,Mat F,Mat Fm$,Key$,Keyfld,Sub1,Mat Out1$;Filter$,Filter_Sub,Readlarger,Sub2,Mat Out2$, Sub3, Mat Out3$, Sub4,Mat Out4$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - The key to search for in the read statements
*Keyfld – the subscript of the key field in the data file. This must match the key field specified in the data file otherwise the function won’t work.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Filter$ – This optional parameter identifies matches to search for in the records. It works in conjunction with Filter_Sub
*Filter_Sub – This parameter specifies which field to look for in the records for matches to Filter$. Only records which have Filter$ in the specified field will be returned.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.
*Sub3 – Subscript of the element to return in the third array. This is optional. If it is specified, you must give MAT out3$, or BR will return an error.
*MAT out3$ - Array in which to return the third (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub3 is given (non-zero). This parameter will not be used if Sub3 is not given or is given as 0.
*Sub4 – Subscript of the element to return in the fourth array. This is optional. If it is specified, you must give MAT out4$, or BR will return an error.
*mat out4$ - Array in which to return the fourth (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub4 is given (non-zero). This parameter will not be used if Sub4 is not given or is given as 0.

This function was written by Mikhail Zheleznov for the fileIO library.

==== fnReadDescription$ ====
''fnReadDescription$(Fl,Subscript,key$,mat F$,mat F,mat Form$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout) (RT_NAME, which should equal 2 after opening routefile (unless we change the file layout later)).
*key$ - Item that should match a key in this file somewhere (in this case it is the route code from the farm record).
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading they have to be dimensioned properly, which is why we use our colorcat$ and our colorcat for these parameters.
*mat Form$ - This will need to be our array of form statements, so the function can read the file properly.

Lets take a look at how this function works:

In the example program I used above, I am reading the Color File to get details about each color. The color file contains a colorcat code field, but I want to display the colorcat description. The colorcat file contains a few details about a color category, and it is indexed based on colorcat code:

route.dat, RT_
route.key, CODE
recl=512
===================================================
CODE, Routing Code, C 6
NAME, Routing Name Description, C 30
MOFT, T/A/C (truck/air/courier), C 1
SHIPPINGDAY, Day of Week for Shipping, C 7

Now, as you know, in the above example, we have already opened the ColorCat File, and we have opened and read a Color record.

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
30180 LET ccode$=color$(CO_CODE) !:
LET Name$=color$(CO_NAME)

Now all that’s left to do is to take the Color File’s ColorCat code and use it to look up the ColorCat File’s description.

30190 LET ColorCat$ = fnReadDescription$(ColorCatFile, CC_NAME, Color$(CO_CATEGORY),
mat ColorCat$, mat ColorCat, mat form$)

==== fnReadUnopenedDescription$ ====
This function accomplishes the same thing as fnReadDescription except that it opens the data file for you. It is slower then FnReadDescription$, but it is easier to use.

''FnReadUnopenedDescription$(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the value of the key field in the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2, so sometimes it is a good idea to design your data files so that string field number two is a descriptive field, like Name or Description.

This function only works on the first key file for each data file. This function is a convenience function but it is slow because it opens the file and closes it for each call. Opening a file is one of the most time consuming program operations.

==== fnReadNumber ====

fnReadNumber does the same thing that ReadDescription does except it reads a numeric field instead of a description.

Lets take a look at how this function works:

''fnReadNumber(Fl,subscript,key$,mat F$,mat F,mat fm$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout).
*Key$ - Item that should match a key in this file somewhere.
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading. They have to be dimensioned properly by [[FileIO_Library#fnOpenFile|fnOpen]].
*mat Fm$ - This will need to be our array of form statements, so the function can read the file properly.

==== fnReadUnopenedNumber ====
This function accomplishes the same thing as fnReadNumber except that it opens the data file for you. It is slower then FnReadNumber, but it is easier to use.

''fnReadUnopenedNumber(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the key of the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2.

==== fnReadRelativeDescription$ ====
This function is the same as fnReadDescription$ but for Relative Files.

''fnReadRelativeDescription$(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat F,mat form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedDescription$ ====
This is the same as ReadUnopenedDescription$ but for Relative Files.

''fnReadRelUnopenedDescription(Layout$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRelativeNumber ====
This is the same as fnReadNumber but for Relative Files.

''fnReadRelativeNumber(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat f,mat Form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedNumber ====
This is the same as fnReadUnopenedNumber but for Relative Files.

''fnReadRelUnopenedNumber(LayoutName$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRecordWhere$ ====
This function returns the record where the given element matches the given value. It does not depend on any key files, and it can be used to locate a record based on any element. However, it loops through the entire data file to do this and it could be a bit slow for large data files. This function opens the file for you, so the file does not have to be already opened.

''FnReadRecordWhere$(Layout$,SearchSub,SearchKey$*255,ReturnSub)''

*Layout$ - the layout of the file we are searching
*SearchSub - Subscript of the element to look in
*SearchKey$ - The value we are looking for
*ReturnSub - Subscript of the element to return

=== FileIO Utility Functions ===
==== fnDataCrawler ====
This function launches the Data Crawler as a function, so you can make your own programs link to it. Special thanks to Mikhail Zheleznov for turning the DataCrawler into a library function.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnDataEdit ====
This function is the same as fnDataCrawler only it opens a Grid for editing.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnShowData ====

This function builds a list or a grid in a floating window that is tied to a data file. It uses the same function that the datacrawler uses, but its much more customizable. All other datacrawler functions are just wrappers for this one.

The first parameter is the only required parameter.

''def library fnShowData(FileLay$;Edit,sRow,sCol,Rows,Cols,KeyNumber,Caption$*127,Path$*255,KeyMatch$*255,SearchMatch$*255,CallingProgram$*255,mat Records,mat IncludeCols$,mat IncludeUI$,mat ColumnDescription$,mat ColumnWidths,mat ColumnForms$,DisplayField$*80,mat FilterFields$,mat FilterForm$,mat FilterCompare$,mat FilterCaption$,mat FilterDefaults$,mat FilterKey)''

*FileLay$ - the file layout you want to display
*Edit - 1 for Edit (Grid) and 0 for View (Listview)
*sRow, sCol - the start position. if not given, its centered. If given but out of bounds, they'll be automatically adjusted to fit the grid on the screen.
*Rows, Cols - the size. If not given, defaults to fullscreen. If given but not big enough to fit the UI elements you request, they're automatically adjusted to fit everthing.
*KeyNumber - the Key to use when reading the data, used with other parameters. If not given, the file is read Relative for faster performance. Required if KeyMatch$ is given.
*Caption$ - the Caption to display, defaults to FileIO's Datacrawler
*Path$ - Alternate path to use for data files (Prepended to the name found in the layout)
*KeyMatch$ - Show only records that match this key. You can use Partial Keys. If this parameter is given, you must also give KeyNumber (above).
*SearchMatch$ - Show only records that contain this substring in them anywhere
*CallingProgram$ - used for logging purposes, pass in the system function Program$
*mat Records - Show only these records in the Grid. Use it to control exactly what the user sees.
*mat IncludeCols$ - Show only these columns. These column names must match the subscript names from the file layout.
*mat IncludeUI$ - Which UI Options to show. Build this array with one element for each optional UI element to include. Explanations of UI elements follow:
**"ColumnsButton" - adds a Select Columns button that the user can use to modify which columns appear on the list.
**"ExportButton" - adds an Export to CSV button that exports the data to a CSV file.
**"ImportButton" - adds an Import from CSV button that imports from the CSV file.
**"AddButton" - adds a button that can be used to add records to the data file.
**"SaveButton" - adds a button allowing the user to save changes
**"DeleteButton" - adds a button allowing the user to delete a row
**"KeyButton" - adds a button allowing the user to jump to a specified position by key or by record number (depending on if the file is opened keyed or not)
**"QuitButton" - adds a Quit button to the screen (the Esc key also quits)
**"Search" - adds a case insensitive search box to the screen.
**"Border" - adds a border around the screen
**"Caption" - adds a caption. (If you specify a caption, this is automatically turned on. If you don't specify a caption but turn on caption here, then FileIO uses the default FileIO data crawler caption.
**"Recl" - adds the Recl to the caption
**"Position" - adds the positions to the field descriptions in the column headings.
*mat ColumnDescription$ - Show these captions. If blank, use the descriptions from the layout
*mat ColumnWidths - Use these widths for the data, if not given, calculate from the file layout
*mat ColumnForms$ - Display Format for the data, including DATE and FMT and PIC
*mat DisplayField$ - Counter Field to display on the Loading Window. If its a field with an associated DATE ColumnForms$ value, that column form will be used when displaying the Counter Field. It can be any of the following:
**REC - this will display the current "REC/LREC" data in the loading window.
**READCOUNT - this will display the "Record Count / LREC" in the loading window.
**FINDCOUNT - this will display the number of records that match the current search criteria by itself in the loading window.
**A Field Name - one of your field names will display that field value in the loading window
**A string literal - anything else will display as a string in the loading window, so you could put something like "Loading, please wait" here and it will display.
*mat FilterFields$ - Contains the subscript of the field to compare to
*mat FilterForm$ - Contains the format of the field to compare to
*mat FilterCompare$ - Contains the comparison type ("<>" or ">" or "=" or ">=" or "*") (* means do a substring search)
*mat FilterCaption$ - The caption for the filter box
*mat FilterDefaults$ - The default value for the filter information
*mat FilterKey - The action to use when filtering the data this way (0 means simple exclude, 1 means start here, -1 means stop here)
**The final five arrays can be used to add user filter boxes to the data grid. You need one element in each array for every custom user filter box on the screen.

==== fnBeginAudit ====

The [[AuditBR|FileIO Compare]] routine is available and can be called from within your programs. To do so, call fnBeginAudit to mark the Start of the compare, then do whatever you need, then run fnCompare to compare everything that has changed between when you ran fnBeginAudit and when you ran fnCompare.

See [[AuditBR#fnBeginAudit|the documentation]] for more details.

==== fnCompare ====

See [[AuditBR#fnCompare|the documentation]] for more details.

==== fnCSVImport ====

This function calls the FileIO Import routine, the same one that you get from the Datacrawlers Import Button.

''fnCsvImport(Layout$*64;SuppressDialog,FileName$*300,ImportModeKey)''

*Layout$ - The file layout to import into
*SupressDialog - 1 to Supress the Import Dialog
*FileName$ - the name of the CSV file (Required if Dialog is Suppressed)
*ImportModeKey - the Import Mode Key (Required if Dialog is Suppressed)
**-1 - Add all records to the file
**0 - Update by Record Number (The file must contain a RecNum column and it must be first)
**1+ - Any positive number means Update by that Key (as listed in the layout).

==== fnCSVExport ====

This function exports a data file to a CSV file.

''fnCsvExport(Layout$*64;SuppressDialog,Filename$*300,IncludeRecNums,KeyNumber,StartKey$,KeyMatch$,Startrec,mat Records,SearchMatch$)''

*Layout$ - The File Layout to Export
*SuppressDialog - (1 to Suppress the Export Dialog, 0 to show it)
*Filename$ - the output file name (Required if SuppressDialog is 1)
*IncludeRecNums - Include a column with the Record Numbers in it
*KeyNumber - Use this key when reading the data for export
*StartKey$ - Start with the record that matches StartKey$
*KeyMatch$ - Export only the record(s) that match KeyMatch$
*StartRec - Start with this Record Number
*mat Records - Export only these records
*SearchMatch$ - Export only records containing this search string anywhere in them

==== fnExportListViewCsv ====

Exports the contents of the specified Listview in CSV format.

''fnExportListViewCsv(Window,Spec$;GenFileName,Delim$,FileName$*255)''

*Window - The Window containing the listview.
*Spec$ - The Spec identifying the listview.
*GenFileName - Flag telling weather or not to generate the file name.
*Delim$ - Delimiter to use. Comma is default.
*Filename$ - Filename to use

==== fnGenerateLayout & fnWriteLayout ====

This function calls on the Generate File Layout Wizard to generate and save the layout indicated by the parameters you give it. You must give it the same valid parameters that you would have come up with if you worked through the layout wizard the normal way, by running FileIO directly and choosing "Generate Layout".

You can also bypass the automatic parsing and generate a layout by specifying all the data directly and using fnWriteLayout.

''fnGenerateLayout(mat OpenStrings$, ReadString$*999, FormString$*20000, DimString$*999; DisplayFile)''
''

*mat OpenString$ - array of all the open strings for the given file from one of your old programs.
*mat ReadString$ - solid read statement from one of your old programs reading the entire record, (or at least everything you want in the layout).
*mat FormString$ - the form statement that goes with the ReadString$ (practice using the Generate Layout Wizard the normal way for details)
*mat DimString$ - the string containing Dim statements for each array mentioned in ReadString$. We need this to know how big the arrays are.
*DisplayFile - if True (1), it will Display the new layout in notepad when its done creating it. If false (0), it will simply create the file.

fnGenerateLayout takes all the above information and parses it into a layout, then calls fnWriteLayout to actually write the layout.

If you already know the information you want to put in the layout, its more direct to call fnWriteLayout below.

''fnWriteLayout(Name$,FileName$*127,VER,PRE$,MAT KFNAME$,MAT KDESCRIPTION$,MAT SUBS$,MAT DESCR$,MAT FORM$;RECL,MAT EXTRA$,DISPLAYFILE)''

*Name$ - the name of the new layout
*FileName$*127 - the name of the data file
*Ver - the version of the data file
*Pre$ - the prefix to use for the data file
*mat KfName$ - array of all the keys for the file
*mat Kdescription$ - array of the subscripts that each key is based on
*mat Subs$ - the subscript for each field in the file
*mat Descr$ - the descriptions for each field in the file
*mat Form$ - the form specs for each field in the file
*Recl - (optional) the record length of the file
*mat Extra$ - (optional) Additonal Information for each field in the file, placed in the Comments column of the new layout. This column is ignored by standard fileio processing.
DisplayFile - if True, open the file in Notepad after it has been created.

==== fnSubstituteStringCode ====
A Large Text Field that is searched. Code is run and any resulting variables are set, if they exist inside String enclosed between Substitute Chars (default []), then they will be replaced with the values derived by the code.

''fnSubstituteStringCode(&String$,Code$*2048;SubstituteChar$)''

*String$ - the string to be searched
*Code$ - code to be run. The resulting variables can be substituted into String
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnSubstituteString ====
A Large Text Field that is searched. Any matching fields in the passed in record will be substituted into their places. For example, if the string contained [cu_name] and you ran substitutions on the Customer file, then [cu_name] would be replaced by the name in the actual Customer record.

''fnSubstituteString(&String$,Filelayout$,mat F$,mat F;SubstituteChar$)''

*String$ - the string to be searched
*FileLayout$ - the layout to be searched
*mat F$ - the record to be used for substitution
*mat F - the record to be used for substitution
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnShowMessage ====
Displays a message to the user, in a child window. Returns the child window number, so that you can close it when you're done with the message.

''WindowNumber=fnShowMessage(Message$*54)''

*Message - the Message to display to the user

=== File System Utility Functions ===
These functions perform other tasks that aid with interacting with the file system.

==== fnGetFileDateTime$ ====
This does a directory listing to determine the Last Modified Date and Time of the given file. You pass it a file name, not a file layout, and it can be used on any file. Its not limited to BR internal files.

The syntax is:

''let FileDate$=fnGetFileDateTime$(Filename$*255)''

==== fnProgressBar ====
There's a Progress Bar that FileIO uses when copying or updating data files. You can use it in your own functions by calling fnProgressBar inside the main loop of the process that you want to display the progress bar over, and by calling fnCloseBar when you're done.

''fnProgressBar(Percent;Color$,ProgressAfter,ProgressThreshhold,UpdateThreshhold,Caption$*255,MessageRow$*255)''

*Percent - Percentage Complete expressed as a float between 0 and 1
*Color$ - HTML Color Code of BR Color Attribute to color the Progress Bar. Defaults to Green.
*ProgressAfter - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*ProgressThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*UpdateThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*Caption$ - Optional message to display above the progress bar.
*MessageRow$ - Optional message to display on the progress bar.

==== fnCloseBar ====

''fnCloseBar''

Call this function to close the progress bar window when your task is done running.

==== fnCopyFile ====

''fnCopyFile(FromFile$*255,ToFile$*255)''

*FromFile$ - The file to copy.
*ToFile$ - The destination file name including path.

This function copies any file, by opening it as an external file and reading and writing the data to the destination file. The advantage of this technique, over using the BR copy command, is this routine is more reliable when run on client server where you may be transferring large files from one side to the other over the internet.

This fnCopyFile also has a progress bar that displays as the file is transferred, so the user knows your software is busy.

This function works over Client Server. Under Client Server, specify @: at the beginning of your filename, to specify that the file is on the client. If the file is on the server, simply leave the @: off. See the chapter on [[Copy#Client_Server|using BR's copy command under Client Server]] for more details on the "@:".

This function's parameters and syntax are modeled off of the built in BR copy command, and like that one, this should work for local transfers, LAN transfers, or even internet transfers. This function will work better for internet transfers then the built in BR Copy Command, however.

==== fnCopyDataFiles ====

''fnCopyDataFiles(DestinationFolder$*255)''

*DestinationFolder$ - the folder to copy your data files to.

This function reads your file layouts and makes a copy of every data file (and key file) in your system to the destination folder, utilizing fnCopyFile above, for better performance and reliability when running over the internet, as well as a progress bar for each individual file.

It also displays a listview while its copying so you can watch the progress while its transferring your data files.

This can be used for making backups of your BR data, or for transferring the latest data onto a laptop for access to it while you're on the road away from the internet.

==== fnReIndex ====

This function reindexes a single data file

''fnReIndex(DataFile$*255;CallingProgram$*255,IndexNum,Path$*25)''

*Datafile$ - the file layout of the file to index
*CallingProgram$ - used for logging, pass Program$ in here
*IndexNum - The index to rebuild - if not given, rebuilds all indexes
*Path$ - the optional alternate path to use for rebuilding the data file.

==== fnReIndexAllFiles ====

This function reindexes all your data files. It doesn't require any parameters.

''fnReIndexAllFiles''

==== fnUpdateFile ====
This function checks and Updates a data file if it needs to be updated, by opening and then closing the data file.

''fnUpdateFile(FileLayout$)''

*FileLayout$ - The name of the file to update

==== fnRemoveDeletes ====

This function, written by Susan Smith, removes deleted records by copying the file with the -D option.

''fnRemoveDeletes(LayoutName$*255;Path$*255,CallingProgram$*255)''

*LayoutName$ - the file layout
*Path$ - Optional Alternate Path
*CallingPRogram$ - used for logging, pass Program$ in here

=== Layout Interrogation ===
Layout interrogation functions are provided for convenience and to enable future dictionary changes without disrupting any programs that interrogate it.

==== fnMakeSubProc ====
This function obtains the subscript assignments that were assigned by fnOpen according to the file layout. The fnMakeSubProc$ routine obtains the subscript assignments without actually opening the file. This is useful when a file record is passed as arrays into a library function in another program, or when you chained to another program and you need to know how to reach the data in the arrays without actually reopening the file.

''fnMakeSubProc(filelay$;mat Subscripts$)''

*FileLay$ - The name of the file layout from which to read the subscripts.
*mat Subscripts$ - If you give this optional array, fnMakeSubProc passes the subscripts back in this array rather then in the subs.$$$ file. This is much faster and helps avoid sharing conflicts.

When this routine returns, you can set the subscripts in your program by executing every element of the Subscripts$ array in a for/next loop.

If you did not pass in a subscripts array, then the a procedure file named subs.$$$ is created. If you proc that file, the proper subscripts will be set.

==== fnReadLayoutArrays ====
This function reads the fields in a file layout into arrays. You call it like the following

''fnReadLayoutArrays(filelay$,&prefix$;mat SSubs$, mat NSubs$, mat SSpec$, mat NSpec$,mat SDescription$, mat NDescription$,Mat Spos,Mat Npos)''

*filelay$ - the name of the layout to read
*prefix$ - the return value for the prefix for the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

This function call would read the fields from the layout in filelay$, and it would return the prefix to prefix$. The Subs would be returned in mat SSubs$ and mat NSubs$.

The Spec statements are returned in mat SSpec$ and mat NSpec$ and the Descriptions are returned in mat SDescription$ and mat NDescription$. The start positions on disk of each element are returned in mat SPos and mat NPos.

All the arrays are optional. If you don’t pass them the information they are supposed to record is simply not returned.

==== fnReadLayoutHeader ====
This function reads the header for a given file layout.

''fnReadLayoutHeader(Layoutname$*255;&Filename$,Mat Keys$,Mat KeyDescription$)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file

==== fnReadEntireLayout ====
This function reads the entire layout by calling fnReadLayoutHeader and fnReadLayoutArrays.

''fnReadEntireLayout(Layoutname$*255;&Filename$,&Prefix$,Mat Keys$,Mat KeyDescription$,Mat Ssubs$,Mat Nsubs$,Mat Sspec$,Mat Nspec$,Mat Sdescription$,Mat Ndescription$,Mat Spos,Mat Npos)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*prefix$ - the return value for the prefix for the file
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

==== fnReadSubs ====
This function reads the subscripts from a layout into Subs arrays.

''fnReadSubs(Layout$,mat SSubs$,mat NSubs$,&Prefix$)''

*Layout$ - the file layout name
*mat SSubs$ - the String Subscript Names
*mat NSubs$ - the Number Subscript Names
*Prefix$ - the files Prefix

==== fnReadKeyFiles ====
This function reads the list of key files from the layout.

''fnReadKeyFiles(Layout$,mat Keys$)''

*Layout$ - The file layout
*mat Keys$ - output array, the keys are returned here.

==== fnLayoutExtension$ ====

This function returns the layout extension being used.

==== fnReadLayouts ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''FnReadLayouts(mat Dirlist$)''

*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all the file layouts that FileIO can find.

==== fnDirVersionHistoryFiles ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''fnDirVersionHistoryFiles(Layout$,mat DirList$;BypassExtension$)''
*Layout$ - Which layout to look up version history of
*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all previous versions from history of the requested layout.

==== fnReadLayoutPath$ ====
This function doesn't actually interrogate your layouts. Instead, it interrogates your settings and returns the path specified for your layout files. This would usually be "filelay\" but you can change it in [[#fnSettings|fileio.ini.]]

It has no parameters.

''let Path$=fnReadLayoutPath$''

==== fnDoesLayoutExist ====
This function returns true if the given file layout exists. It returns false if the layout does not exist.

''FnDoesLayoutExist(layout$)''

*Layout$ - Layout to test for

==== fnReadForm$ (uncompiled) ====
Sometimes you need to know the original form statement that fileio is using to read your data file, most often when you're debugging your file layout, and you're getting some problem when reading the file. The form statement that fileio normally returns is compiled using CFORM$ to save space in the array, and to make the execution of your read statements faster. You can use this function to return the original form statement for the file.

The syntax is:

''let FormStatement$=fnReadForm$*10000(FileLayout$)''

Remember to dimension FormStatement to something huge! fnReadForm$ can return up to 10,000 characters.

==== fnReadFormAndSubs ====

This function does the same as above but it also reads the subscripts from the file into an array.

''let fnReadFormAndSubs(Layout$,mat Subs$,&ReadForm$,&StringSize,&NumberSize)''

Note that unlike most of our functions, all the above parameters are required.

The layout is the layout you're interrogating. The Array will be populated with the subscripts after the function. The ReadForm$ variable will be filled with the form statement for the file. Remember to dimension it large enough. StringSize and NumberSize will contain the number of string fields and numeric fields in the file.

Mat Subs$ will be returned, strings first, numbers last, matching the form statement that is returned. So Subs$(1) is the first string subscript and Subs$(StringSize+1) is the first Numeric subscript.

==== fnClearLayoutCache ====

fnClearLayoutCash (v2.3+) clears out the cache of layout name and data to get realtime Updates to File Layouts.

=== Other Useful Functions (non-layout related) ===

==== fnAskCombo ====

Opens a window with a combo box and returns the users selection.

''fnAskCombo$*255(mat Description$;Caption$*60,Default$*255)''

*mat Description$ - contains the combo box choices
*Caption$ - contains the optional caption for the window
*Default$ - the text of the item in mat Description$ that you want to be selected by default

==== fnSendEmail ====

This function sends an email and an optional attachment to the email address specified.

''fnSendEmail(Emailaddress$*255,Message$*10000;Subject$*255,Invoicefile$*255)''

*EmailAddress$ - the Destination Email Address
*Message$ - the Message$ to send
*Subject$ - the subject
*InvoiceFile$ - the filename of a file to attach. This is the BR filename (the function automatically converts it to an OS Filename.)

The function returns 1 when the email was sent successfully, or 0 if it wasn't sent successfully.

In order to use this function, you must have the emailcfg file layout in your layouts folder and you must have a copy of SendEmail.exe which is free and can be downloaded from the internet. Both of these files are included with the latest update of fileio.

You also have to configure fileio with the authentication information for your email server.

To configure your email server, simply run FileIO to get the data crawler, then select the emailcfg file layout and press F5 to edit it. Add a row if the file is empty.

Simply fill in the information the file is asking for in the appropriate fields and save the data, and then test sending an email to make sure it worked.

More information about sendEmail.exe is available from the author's product site here: [http://caspian.dotconf.net/menu/Software/SendEmail/ http://caspian.dotconf.net/menu/Software/SendEmail/]

==== fnClientEnv$ ====

This function returns the value of a Windows Environment Variable on the client under Client Server.

''fnClientEnv$*255(EnvKey$)''

*EnvKey$ is the name of the Windows Environment Variable to check on the client.

The function returns the value of the entered environment variable.

==== fnClientServer ====

This function returns true if you're currently running in Client Server mode, and false if you're running in the old "native" mode.

==== fnEmpty & fnEmptyS ====
These functions test if the passed in array is empty or not..

The syntax is:

''fnEmpty(mat Numeric)''

or

''fnEmptyS(mat String$)''

Example:

def fnSomeFunction(String$,mat Array$; mat OtherArray)
if fnEmpty(mat OtherArray) then
! Arrays were empty.
end if
fnend

==== fnReadScreenSize ====
This function reads the screen size of the given window (or window 0 if a window wasn't passed.) This is useful for centering a window on the screen, or for making sure window 0 is big enough for the child window you're trying to create.

The syntax is:

''fnReadScreenSize(&Rows,&Cols;Window)''

*Rows & Cols - returns the screen size in rows and columns.
*Window - the window to interrogate. If not given, assumes [[Open_Window#Comments_and_Examples|Window 0]].

==== fnBuildProcFile ====
This function builds a proc file to be executed later. This function and the next simplify the process of executing code in a proc file. It can even be used to spawn a new session of BR.

To use it, call fnBuildProcFile one or more times and specify some lines of code to execute.

''fnBuildProcFile(Command$*255)''

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnRunProcFile ====

This function spawns a new copy of BR and in it, runs the proc file that you've previously built using fnBuildProcFile (above).

'' fnRunProcFile(;NoWait) ''

The optional parameter "NoWait" causes the other session to spawn and run in a new thread. If you don't specify NoWait, the current session pauses and waits for the other session to close before proceeding.

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnLog & fnErrLog ====
These next two functions are functions to aid in logging. When you call either of these two functions, you give them a string that you wish to log. They will open the FileIO Log File and add a record to the end of it containing some user information such as login_name and session$, and the string that you specified. FnErrLog does the same thing as fnLog except it also logs the Error Number and the Line.

The syntax is:

''FnLog(string$)''

*String$ - the Log Message

''FnErrLog(String$)''

*String$ - the Log Message

==== fnLogArray ====

This function logs the given arrays to the log file, logging each field in the arrays. Its useful for recording, for example, an entire data record that is about to be written to a data file.

The syntax is:
''fnLogarray(mat F$,mat f;Message$*512,CallingProgram$*255)''
The first two parameters, of course, are the array to log. The third parameter is an optional message to be recorded along with the array, and the fourth optional parameter is the CallingProgram$ to save in the log along with the message. (The CallingProgram$ parameter can usually be passed as the system function Program$)

==== fnSetLogChanges ====
This function works in conjunction with the next function, and they're for recording just what changed in a data file. When the file is read, you call fnSetLogChanges and record the "before" picture of the file record.

After changes have been made and saved back to disk, you can call fnLogChanges below to record the actual changes.

The syntax is:
''fnSetLogChanges(mat F$,mat F)''

==== fnLogChanges ====
This function is the other half of the function above. It compares the given arrays with the ones set previously in the above function and checks for changes. Then it generates a log message recording information about just the items that changed.

The syntax is:
''fnLogChanges(mat F$,mat F;Message$*1024,CallingProgram$*255,Layout$)''

You need to pass in the same two arrays as before, but this time the modified versions of them.

You can also optionally pass a 1024 byte log message to record with the log entry.

CallingProgram$ again should be passed as the system internal function Program$.

The final parameter allows the passing of a Layout$. If you pass a Layout$, that layout is read and the subscripts are used when making the log message of changes, so that its easier to read. If you pass a layout, it will identify the changed fields by name. If you don't it will identify those fields by relative position number.

==== fnViewLogFile ====
All of the above functions store the information by default into a BR internal file defined in the filelay\logfile layout.

The fnViewLog function uses fnShowData to call the Data Crawler to display the FileIO Log File in a searchable listview.

''fnViewLogFile(;ShowQuit,ShowColumns,ShowExport)''

*ShowQuit - Show a quit button on the UI (if off, ESC will quit).
*ShowColumns - Include a button to allow the user to select which columns to view.
*ShowExport - Include a button to export the log file to CSV.

==== fnReadLockedUsers ====

This function returns a list of all users using the locked data file.

''fnReadLockedUsers(mat Users$)''

*mat Users$ - the list of users is returned here

==== fnDisplayLength ====
This function calculates the display length of a field based on its form spec.

''fnDisplayLength(Spec$)''

*Spec - the Form Spec to return the display length of.

==== fnLength ====
This function calculates the length on disk of a field based on its form spec.

''fnLength(Spec$)''

*Spec$ - the Form Spec to return the length of.

==== fnStandardTime$ ====
Converts Military Time to Standard Time. Returns Standard Time$

''fnStandardTime$(MilitaryTime$;Seconds)''

*MilitaryTime$ - Time in 24 hr format.

==== fnMilitaryTime$ ====
''fnMilitaryTime$(StandardTime$;Seconds)''

*StandardTime$ - Time in AM/PM Format

==== fnCalculateHours ====
Calculates the difference between 2 specified times.

''fnCalculateHours(TimeIn$,TOut$,DaysIN,DaysOut)''

*TimeIn$ - From Time
*TimeOut$ - To Time
*DaysIn - Days Start
*DaysOut - Days End

==== fnBuildTime$ ====
Builds a time in the format used by the above functions.

''fnBuildTime$(H,M,S,P;Military,Seconds)''

*H - Hours
*M - Minutes
*S - Seconds
*P - Boolean indicating AM/PM - 0 is AM, 1 is PM
*Military - Flag indicating weather desired result is in Military Time or not
*Seconds - Flag indicating weather to count seconds or ignore them. (1 means count seconds)

==== fnParseTime ====
Takes a time and pulls out the values

''fnParseTime(T$,&H,&M,&S,&P)''

*T$ - the time to parse
*H - Return value for Hours
*M - Return value for Minutes
*S - Return value for Seconds
*P - Return Value for AM/PM

== FileIO fnSettings (Global Settings Code) ==

The FileIO library can be made to implement certain policies across the board. These are established by creating a file called fileio.ini and typing statements like the following into it. This file is "PROCed", so you don't want to put line numbers in it.

Anything you don't specify in fileio.ini will take its default value, shown below. So you only need to specify the items that you want to be different.

Note, for the boolean settings below, 1 denotes TRUE and 0 denotes FALSE.

let EnforceDupkeys=1 ! Enforce that key number 1 is unique key
let Defaultfilelayoutpath$="filelay\" ! Path To Your File Layouts
let Promptonfilecreate=1 ! Ask User Before Creating New Files
let Createlogfile=0 ! Use Logging
let StartFileNumber=1 ! Set above 300 to avoid conflicts with legacy programs.
let CheckIndex=0 ! Automatically Verify Indexes (slow)
let CompressColumns=0 ! Shrink or Expand Columns in Data Crawler by Default
let MaxColWidth=20 ! Max Default Column Width in Data Crawler
let LogLibrary$="" ! Defaut Log Library, defaults to None
let LogLayout$="" ! Log file layout, defaults to Internal File
let AnimateDatacrawler=1 ! Use ScreenIO Animation for Datacrawler
let TemplatePath$="filelay\template\" ! Default Template Path
let IgnoreLayouts$="" ! List any Ignore Layouts here.
let CloseFileSimple=0 ! Use simple comparison for fnCloseFile

==== EnforceDupkeys ====

Turn on the EnforceDupkeys option to force that the first key listed in your file layouts is a unique key. FileIO will generate the standard BR error for Dupkeys when attempting to create indexes if it is not unique.

==== DefaultFileLayoutPath$ ====

Use the DefaultFileLayoutPath option to specify the path from your programs to your file layout folder. The default is "filelay\". Use this setting if you want to place your file layouts in another folder from the default.

==== PromptOnFileCreate ====

Use the PromptOnFileCreate setting to cause FileIO to display a message box whenever it is attempting to create a new file. This happens during the automatic update procedure, as well as during any attempt to access a file that does not exist. This setting should be turned off in your live system, and only turned on for development purposes. If you use the message box to cancel creating of the new file, then the file is not created, and fileIO or your application will most likely give an error when you attempt to actually access the new file.

It can be useful during development to make sure that you don't accidentally create the wrong files, due to an incorrectly specified path or a typeo in the filename in the layout file. However, in a live system, these things have already been tested, and you generally want the default behavior, because you don't want your users to have the ability to cancel the normal operation of FileIO.

==== CreateLogFile ====

Use this option to specify weather or not to use the FileIO log file. If it is turned on, a log file called FileIO.log in the current directory is created with entries listing all attempts to open a file, automatically update one, or automatically update your indexes.

==== StartFileNumber ====

Use this option to set the starting file number that the fnGetFileNumber and the fnOpen functions use to search for available file numbers. This is so that if you have certian reserved file numbers in your code, you can make sure that FileIO will not use those reserved file numbers, causing a conflict with your already existing programs. The default is 1, which is fine if your software does not have any reserved file numbers.

The allowable BR file numbers are 1-200 and 300-999.

==== CheckIndex ====

This function is used for Partial FileIO Implementations. If all of your software uses FileIO then all of your indexes are kept automatically up to date by the FileIO library and BR's internal file processing systems. However, if some of your programs do not use FileIO, and you use the FileIO library to add a new index file that those other programs do not know about, then its possible for the additional index file to become out of date when the master file is updated by your other programs.

Use this setting to cause FileIO to check the DateTime stamp on all your index files when opening a new file, and automatically update any indexes that may have potentially gotten out of date from other programs.

This option slows down the processing of the fnOpen function, particularly when running under client server over the internet. If you know that every program in your application suite uses FileIO, and that any programs that do not use FileIO still properly update all the indexes that your data file uses, then you can safely leave this setting turned off, and optimize your performance when opening several files using the fileIO system.

==== CompressColumns ====
This instructs the datacrawler to use smaller widths for small columns. If CompressColumns is false, the data crawler will make the column the width of the field or the width of the caption, whichever is wider. If CompressColumns is true, it will use the width of the field, not the caption.

==== MaxColWidth ====
This limits the column width to a set amount. This is applied after CompressColumns above.

==== LogLibrary$ ====
If a library is specified here, then fileio looks for a BR library with the specified name, and attempts to call a library function in it called fnFileIOLog that. This function should expect six parameters, which are Logstring$, Login_Name$, Session$, Days of Date$, Time$, and CallingProgram$, if LogLayout is also nonblank.

If you specify a LogLibrary and LogLayout is blank, then it calls your function giving it only 1 parameter.

It will call your function '''''instead of''''' the normal log file. Use this to implement your own logging functions however you want.

==== LogLayout$ ====
Use this setting to specify an alternate file layout for an alternate file to do the logging in. Base the file layout for this file on the logfile we supply for you in the filelay folder. It should have at least those fields, which our log routine will automatically populate, but you can add other fields if you want (though you will need to manage them yourself).

If you don't specify LogLayout, the default filelay\logfile will be used. This will allow you to also use the fnViewLogFile function to access it.

==== AnimateDataCrawler ====
The sister library [[ScreenIO]] has a feature that allows you to use an animation of a clock in your loading screens in your own programs. If you have [[ScreenIO]] then FileIO will automatically detect it and use it to display a loading animation while the data in the data crawler loads.

Set AnimateDataCrawler to false (0) in your fileio.ini file to bypass the animations if you do have screenio but don't want to see the animations anyway.

==== TemplatePath$ ====
This setting points to the folder that contains the code templates used by the Generate Code button on the main page of the Data Crawler.

==== IgnoreLayouts$ ====
This is a comma delimited list of all layouts that you wish to suppress from appearing on the main page of the data crawler. You can still access these layouts with your code, but they won't be listed in the data crawler for you to access.

Whatever you're using for a log layout, is automatically added to this list.
==== CloseFileSimple ====
The fnCloseFile function closes all the individual handles to a data file that was opened for output using multiple keys.

For BR 4.18 and higher, we support a better algorithm for detecting which files are matches for a given opened file number.

Set CloseFileSimple to true (1) to force it to check the old way.

== FileIO Add-on Packages ==

Many FileIO Add-on packages are currently in the works.

=== ScreenIO Library ===

The [[ScreenIO Library]] is a sister library to the FileIO library. The ScreenIO library requires the FileIO library in order to run.

The ScreenIO library is a complete Rapid Application Design tool that enables you to implement custom screen functions anywhere in your exiting programs.

If you call the ScreenIO Library as a function library, you call a function called fnFM and tell it which screen you wish to use. The ScreenIO library loads your user interface, loads your data files, and preforms all the file maintenance operations you have designed into your screens.

You can find out the latest information about the ScreenIO library in the ScreenIO page.

=== Audit BR ===

The [[AuditBR|Audit BR]] developer tool makes a backup copy of your file layouts. Then you run some code you're trying to test, and finally, run Audit BR again, to get a report showing all the changes to any of your data files automatically.

AuditBR is now included directly in FileIO. To use it, select the layout from the list of layouts in the Datacrawler and press the "Compare" button.

== What’s New (also described above) ==
=== 2018 ===
*Support for dates in any storage formats on disk (v2.48)

=== 2015 ===
*Added Rec to display for fnShowData
*Added FormStatement$ for debugging of form statements inside fileio
*Added mat BadRead$ for debugging of 726 errors when making new layouts
*Fixed a bug causing crash when logging things from long program folders
*fnClientEnv$ - reads a Windows Environment variable on the client using the command shell
*fnAskCombo$ - added an optional parameter to set default selection.

=== 2010 - 2014 ===
*FileIO now caches your file layouts in memory to make it much faster then before when opening the same data file in multiple programs.
*Generate Layout Wizard
*fnShowData
*Improved Logging
*fnViewLogFile
*Import/Export
*Import/Export by Function
*Many other speed increases
*if ScreenIO is present, Datacrawler uses the animation routines
*fnBuildProcFile & fnRunProcFile
*fnGenerateLayout & fnWriteLayout
*fnReadForm$
*fnReadFormAndSubs
*fnGetFileDateTime$
*fnReadLayoutPath$
*fnSortKeys
*fnSetLogChanges
*fnLogChanges
*fnLogArray
*fnReadScreenSize
*fnEmpty
*fnEmptyS
*Many other useful functions that were added to the documentation at earlier dates.

=== Spring 2009 ===

'''''New Functions:'''''

The FileIO Library has been updated in Spring 2009 to provide several new functions:

*fnReadRecordWhere
*fnKey$
*fnBuildKey$
*fnReadUnopenedDescription$
*fnUpdateFile
*fnDisplayLength
*fnLength
*fnReadLayoutHeader
*fnReadEntireLayout

'''''Speed Increases:'''''

Thanks to the BR [[Profiler]], we have increased the speed of FileIO fnOpen function by ten times when running over a LAN and by 100 times when running over the internet using Client Server.

In order to get the new Speed Upgrades, you will need to make sure that you use the latest copy of the [[#fnOpen_Function|fnOpen]] function in each one of your programs that use FileIO.

'''''Network FileIO:'''''
This version of FileIO has been optimized to work better in network situations.

'''''FnSettings: '''''
There are more configuration options in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine.

'''''Automatic Update Speed Fix:'''''
The automatic update proceedure has been made to run more then 100 times faster then before according to our benchmarking tests.

=== Fall 2008 ===
'''''DataCrawler Grid:'''''

By popular request we added a read/write version to the data crawler. This version works exactly the same as the datacrawler did before but it displays all the contents of your data files in a grid instead of a listview.

When you run the fileIO library as a program, it launches a tool known as the [[#DataCrawler|DataCrawler]]. The DataCrawler shows a listview displaying all your layout files in it. If you select one, it builds another listview with all the data in your selected data file.

If you are looking at the first list of all your file layouts, and you press F5, a grid will be build displaying all the data in your data files. You can change any of the records you like, and when you're done, your changes will be saved to the data file. Additionally, you can Add or Delete records using the buttons at the bottom. Any changes you make are not written to the disk until you click the "Save" button. If you press ESC (Cancel) the grid is closed and all changes you made sinse the last save are lost.

This tool is for programmers only. Do not give your end users access to the DataCrawler.

Use the DataCrawler at your own risk. Gabriel Bakker and Sage AX are not responsible for any harm that comes to your data files through the use of this or any other tools we offer.

The DataCrawler is not designed to be used to maintain your data files. It can be used carefully to correct small things in your data files.

'''''Support for Nonstandard Paths:'''''

Many BR Vendors keep different versions of the same data files in different locations. For example, sometimes a BR vendor will use a different Data folder to represent data for different Warehouses, or Customers. In cases like this it is necessary for your programs to specify the path to your data files. They may do so by specifying the optional "PATH" parameter to your data files. See the section [[#fnOpenFile]] for more information.

'''''Support for Nonstandard Layout Files Path:'''''

Old versions of the fileIO library required you to place all your file layouts in a subfolder of your program directory called "filelay". We have now changed the Fileio library to allow you to place your file layouts any place you want. The only requirement is that they are all together in one folder by themselves.

If you use a nonstandard path in the fileIO library, it is necessary to make a change to the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code in your copy of fileio.br.

'''''Prompt on Create:'''''

The FileIO library automatically creates any data files that it can't find. This was done to make it easier to deploy your finished programs - if you had any empty data files you could omit them from the packages and they would be created when they were needed, on the fly.

The current version of the FileIO library contains the same ability. However, it prompts you before creating any data files. This helps to avoid bugs that happen from incorrectly specifying the path to your data files.

However, if you do intend for your data files to be autocreated, then you probably don't want your end users to modify them. Therefore, you can use the PromptOnCreate setting in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code to specify. If this value is set to true, then the fileIO library will prompt you whenever it attempts to Autocreate a data file. If it is set to false, then the fileIO library will create the data files without prompting you, like it always did before.

'''''fnSettings:'''''

The newest version of the FileIO library supports some features that require you to specify Global Settings values. These are done by modifying the contents of the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine at the beginning of the fileIO library.

=== Fall 2006 ===
Many improvements have been made in the FileIO library over the summer. This section is intended to acquaint you with the highlights of those changes. Most of these improvements were built from ideas generated during the discussion at the April conference.

'''''Intermixed String and Numeric Specs:'''''
The File Library has been expanded to allow the reading of data files that contain mixed string and numeric specs. This is to aid those of you who are planning on implementing the FileIO Library on existing data files which may not be organized with strings first and numbers second.

The central idea of the FileIO Library is based upon the reading of your data files into a String and Numeric array. This will enable you to refer to the fields in your file by using a named subscript, saying F$(FM_NAME) to refer, for example, to the farm file’s name field. The advantage to this is that when you change the file layout, all your existing programs will not have to be modified, because they will only be looking at F$(FM_NAME). If the name field changes from the third string field to the fourth, the value of FM_NAME will also change, and you won’t have to worry about updating your data files.

However, in order to support the reading of a data file with intermixed string and numeric specs, the generated form statement will actually calculate the position of any fields that are not in order, so that the file read statement will still return all string fields first (into your string array) and the numeric fields second (into your numeric array). You do not need to worry about this; the library does it for you. All you have to do is read your file and use the data values.

The only thing that is required is making sure that all your string subscript names end with a “$”. This will tell the library that they are strings. Thank you, George, for this suggestion.

'''''Versioning / Automatic Updates:'''''
The file layouts have been expanded to contain a version number. This version number will be used to determine when a file needs to be updated. The version number is the third parameter in the file layout.

Any time you wish to change your file layouts, simply increment this version number. Each time the library attempts to open a data file, the file’s version is checked and compared with the version in the file layout. If the file layout has been changed (if the version in the file layout is greater then the version in the file) then the file will be updated to the latest version. Depending on the file size this may take a couple of moments. A simple progress bar will be displayed on screen while this is happening. The progress bar will be displayed in its own window, so it should not affect anything your programs may have had on screen.

The library uses the following procedure for updating a file. First, the file is copied to a backup file (prefixed by the letter ‘o’ for old). So color.dat would become ocolor.dat, and color.key would become ocolor.key. Then the new file is created and marked with the proper version number. (color.dat, color.key). The old file is opened in read-only mode, and the new file is opened for OutIn. The update routine actually reads through the old file layout, and one record at a time creates a new record, using the new file layout, with the same data, saving it to the new data file.

When it is done upgrading, the progress bar window is closed, and the file is reopened in the fashion you described in your call to fnOpen, and flow returns to your program as though nothing unusual has happened.

If an error occurs during processing, the routine will do what it can to roll your data files back to the previous version, but please make frequent backups of your data files anyway, just to be safe.

'''''Error Checking – If there is a mistake in the file layout:'''''
The routine attempts to discover the cause of the error in the case that one is encountered due to a missing file, a file sharing violation, or an invalid or corrupt file layout. If this should happen, the program is paused, and a text message is printed out explaining the most likely source for the error, including what part of the file layout, if any, may have caused the error.

You may then examine the printed text, and the contents of the BR system variables ERR and LINE to determine the problem. If you type “GO”, the next line will be execute “system”, ending your program.

If the file was in the middle of an upgrade when the error happened, it will be automatically rolled back to the previous version, so that when you fix the problem and try to run your program again, the file will again attempt to update from the beginning, and you won’t have to worry about corrupted data.

However, please backup your data before upgrading your data files anyway, just to be safe.

'''''Implementation of Keys / Creation of New Data Files:'''''
The library has been expanded to automatically create all new data files, and to automatically update any existing files. This means that in the file layout header, two new fields that were previously ignored are no longer ignored. The RECL value that you specify in your file layout will be used, along with the description/definition of your keys file. When you open a new file (or update an existing one), the library will calculate the proper kps and kln by evaluating the key description. This key description must match up with subscript values from the data elements in your file, and more then one may be specified, but they must be separated with slashes (/). If I wanted my Farm File to be keyed based on CODE and NAME, the proper key description would be:

farm.key, CODE/NAME

The library will then look up the position and length on disk of the CODE and NAME fields and put them together to create the proper keys during an update or creation of a new file.

'''''DataCrawler:'''''
Perhaps the most exciting new addition to the library is the addition of a programming tool I like to call a DataCrawler. If you run the FileIO Library directly as a program, instead of using it as a library, it will function as a DataCrawler. The DataCrawler requires a New Gui version of BR, as it requires a ListView to be able to properly and easily display the data in your files.

If you run it in an older version of BR you will get a message, telling you to run it in a newer copy. If you run it in a New Gui version of BR with CONFIG GUI OFF, then GUI will be turned temporarily on for the use of the DataCrawler and then turned off again when you are finished. If you run it in a New Gui version of BR with GUI ON, it will just run normally.

When you run the DataCrawler, first you will see a ListView displaying every file layout it can find in the filelay folder. If you select a file, the DataCrawler will open a large ListView with as many columns as there are fields in the file. The Column Headings will come from the element descriptions in your data files, and the column widths will come from the displayed width of the fields. There will be a row for every record in your data file, and you can resize the column widths, and scroll around the data file to view the raw data of your BR data files on disk.

If you are dealing with a particularly enormous data file (50,000+ records) it can take a moment to populate the ListView with the data in your data file. You may hit ESC to stop loading if you like, and view only the already loaded records.

If you would like to look up a particular record (based only upon the primary key for the data file), you may press F4. This will give you a window which asks you to input the key or partial key. When you press enter, the file will be reloaded, starting at the key you specified and continuing on to the end of the file, or until you press ESC. The records you are looking for should appear at the top of the ListView.

To reset the ListView and look at the contents of the entire file again, simply press F4, and enter a blank (“”) key.

Finally, as with any ListView, you may resort your data by clicking on any of the column headings. Then you can use the slider bar at the right to scroll down to the record you desire.

This is a programming tool and is not designed to be used by an end user. This tool will open your file in read-only mode. It will not allow you to modify the data; I leave that as an exercise for the reader. However, it will update any datafiles you view to the latest version (if they need to be updated) when it opens them, just as any other program that uses the library will do.

== Appendix (Examples)==

=== Example.br ===
00010 ! example.br - This program is an example of for the data reading simplification
00020 ! Copyright April 2006 by Gabriel Bakker
00030 ! Distributed open source as a Christmas gift to brag members
00040 !
00100 execute "config gui off"
01020 DIM form$(1)*255
01030 DIM color$(1)*255,color(1)
01040 DIM colorcat$(1)*255,colorcat(1)
02020 library "fileio": fnopenfile, fnreaddescription$
04000 !
04010 Openfiles: ! Open your files here
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)
06000 ! gosub WriteFiles ! If you want to test this line, make sure to drop flag from 4030
07000 !
07010 MainBit: ! This'un here's tha Main Bit
07030 RESTORE #ColorFile:
07100 ReadNextcolor: ! Read next record
07120 read #ColorFile, using form$(ColorFile) : mat Color$, mat Color eof EndReadColor
07180 PRINT Color$(co_name)&" ("&Color$(co_html)&") is a member of the '";
07190 PRINT trim$(fnReadDescription$(ColorcatFile,cc_Name,Color$(co_category),mat Colorcat$,mat Colorcat,mat form$))&"' category."
07290 goto ReadNextColor
07300 EndReadcolor: ! Finished with Color File
08000 STOP
25000 !
25010 WriteFiles: ! Uncalled routine to demonstrate writing files
25105 let color$(co_code)="GD" !:
let color$(co_Name)="Gold" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFD700"
25110 write #colorfile, using form$(colorfile): mat color$, mat color
25115 let color$(co_code)="LV" !:
let color$(co_Name)="Lavender" !:
let color$(co_Category)="BL" !:
let color$(co_html)="E6E6FA"
25120 write #colorfile, using form$(colorfile): mat color$, mat color
25125 let color$(co_Code)="OR" !:
let color$(co_Name)="Orange" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFA500"
25130 write #colorfile, using form$(colorfile): mat color$, mat color
25205 let colorcat$(cc_Code)="YL" !:
let colorcat$(cc_Name)="Yellows" !:
let colorcat$(cc_html)="FFFF00"
25210 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25215 let colorcat$(cc_Code)="BL" !:
let colorcat$(cc_Name)="Blues" !:
let colorcat$(cc_html)="0000FF"
25220 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25300 return
40000 !
40010 Open: ! ***** Function to call library openfile and proc subs
40020 def fnOpen(FILENAME$, MAT F$, MAT F, MAT FORM$;INPUTONLY,KEYNUM,___,INDEX)
40025 dim _FileIOSubs$(1)*50
40030 let fnopen=fnopenfile(FILENAME$, MAT F$, MAT F, MAT FORM$,INPUTONLY,KEYNUM,MAT _FileIOSubs$)
40040 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
40090 fnend
50000 !
60000 Ignore: Continue

Color File Layout
color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

ColorCat File Layout
colorcat.dat, CC_, 0
colorcat.key, CODE
recl=127
===================================================
CODE$, Category Code, C 6
NAME$, English Name for Color, V 30
HTML$, HTML Code for the Color, C 6

Example Layout showing multiple keys (price)
price.dat, PR_, 0
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2

[[Category:Utilities_Third_Party]]

FileIO Library

2024-09-11T15:34:46Z

Gordon.dye: /* fnOpen Function */

The '''FileIO''' Library began as a project to find a way to reduce the effort associated with making changes to data file layouts. Thanks to the Fileio library, when I have to make a change to a data file layout for my customers today, I can complete the task in under 1 minute, and not a single program needs to be changed in order to continue working with the new file layout. In fact, I don’t even have to update my customer’s data files, as the FileIO library takes care of this for me as well.

The trick is to define each of your file layouts in an ASCII text file layout file that is described below. The FileIO Library will parse through your file layouts, and it will instruct your programs how to access the file data after it has been read. It will also automatically detect when you make changes to the file layout, and it will update your customer’s data files on the fly to make sure they have the latest version. Finally, it contains a DataCrawler that you can use to examine the contents of any of your BR data files in a raw format.

For more information about the FileIO Library visit the [http://www.sageax.com/products/fileio-library/ Sage AX Website]

To download the latest copy of FileIO, click [http://www.sageax.com/downloads/FileIO.zip here.]

== Method of Operation ==
The file IO library parses a formatted text file layout and uses this information to structure the opening and the reading of a file “object”. The word object here is used to refer to all the data in a given record layout in one of your files. This library is easy to use, and provided you follow some simple standards, it will simplify your life immensely.

Your programs will need to define one array for all [[Form|BR data file form statements]] and add a snippet of code (given below) to the program for interfacing with with the library. For each file you will need to define a couple of arrays and use the library to open them. From that point on access to data is simple and direct.

=== File Object Arrays ===

First, in your program you must create two arrays to store the file information. If we are dealing with the Color File these would be MAT COLOR$ and MAT COLOR. One will store all the string information about a color, and the other will store the related numeric data. Our working example will involve two files: a Color File and a Color Category File. You should dimension these as follows:

01030 DIM color$(1)*1000,color(1)
01040 DIM colorcat$(1)*1000,colorcat(1)

We're dimensioning the string array elements to 1000 bytes each. This is the length of one field in the color file. The array element length needs to be at least as big as the largest string field in the data file.

However, it is recommended to make sure the length is long enough to handle any field you might eventually add to the file at any point in the future. BR supports multi-line textboxes, so I sometimes add long memo fields to my data files that might be 400 or 800 or even 1000 characters long, therefore 1000 is the length I use now in all my new development.

But anything will work as long as its long enough to handle the largest data field in your file.

=== Forms Array ===

Your programs will need a string variable array to store the form statements associated with reading files. This form statements array will be dynamically generated or expanded whenever the a file is opened. It will say:

01020 DIM form$(1)*255

This form statement will be compiled by the FileIO open statement. BR limits all compiloed form statements to 255 bytes, so 255 is sufficient to hold the compiled Forms$ statements.

=== Library Linkage ===

You will also need the library statement:

02020 library "fileio.br": fnopenfile, fnreaddescription$

=== fnOpen Function ===

Now, add the following snippet of code to interface with the library. Note that this snippet can be copied in exactly as provided and no customization of it is needed.

Because BR libraries do not share global variables with the programs they are called from, we will need to execute a procedure file whenever we open a file - to set the names of all of our variables. Add the following snippet of code into your program. It will create an FnOpen function that calls the library and runs the proc file. The $$$ at the end of the procfile name tells the procfile to self-destruct after execution. Since this procfile is used simply to return variable information back from the library to the main program, we don’t need it sitting around collecting dust.

99010 OPEN: ! ***** Function To Call Library Openfile And Proc Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
99030 dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
99050 if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
99060 fnend

Or, for those with [[Lexi]]: (same but without line numbers)
OPEN: ! ***** Function To Call Library Openfile And Proc Subs
def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
fnend

=== Using FileIO in Your Programs ===
Now you are ready to process files. 
'''''You simply open the files by saying:'''''

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

'''''read each file as follows:'''''

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
'''''and access the data:'''''

30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name)

=== How it Works ===
The above statements tell the File Library to look in the filelay folder to find the file layout for the Color File, and read it to find out what the Color File looks like. Then it OPENs the Color File, and sets MAT COLOR$ and MAT COLOR to the correct number of elements to hold an entire color record. Finally, it will define several variables that we can use as pointers (subscripts) into these arrays to access the data read into the 2 arrays, and it will assign the file handle to a variable called "colorfile".

The second open above will do the same thing to the color category file, except the 1 parameter value tells the function to open readonly. The array subscripts populate procedure (passed back from Fileio) will be executed, thereby assigning values to the subscript names in the calling program. So, if I had a file layout such as the following:

color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

Then the functions would do the same thing as the following individual lines of code (assuming the next available file handle was 5):

DIM FORM$(5)*255
DIM COLOR$(9)*1023, COLOR(1)
OPEN #5: “Name=color.dat, kfname=color.key”,internal,outin,keyed
LET FORM$(5)=”form C 6,V 30,V 6,C 6”
LET FORM$(5)=CFORM$(FORM$(5))
LET COLORFILE=5
CO_CODE=1
CO_NAME=2
CO_CATEGORY=3
CO_HTML=4

The data is used by referencing the file array, with the subscript name, so the color’s description becomes color$(co_Name).

In the old days, if we wanted to change the file layout of our file, all of the programs that used that file would have to be changed one at a time to use the new file layout. Also, if the order of the fields changed, then all the programs would have to also be changed to use the new fields.

But now, using this function, we can change the file layout all we want. If we later want to insert a field into the file layout before color name, I won’t have to look at this program again; this program will just work fine, because the library maps the subscripts to the actual fields.

Also, the code is easier to read and maintain.

=== Example ===
The whole thing looks like this:

01025 ! Dimension the Arrays
01030 DIM color$(1)*1023,color(1)
01040 DIM colorcat$(1)*1023,colorcat(1)
01050 DIM form$(1)*255
02000 !
02020 library "fileio.br": fnopenfile, fnreaddescription$
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$) ! Open the file
05000 !
30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore ! Read the file
30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name) ! Use the data by referincing it in the file arrays
80000 !
90000 ! Every program using fileio needs the following code
99010 OPEN: ! ***** Function To Call Library Openfile And Generate Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths)
99030 dim _FileIOSubs$(1)*800
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$)
99050 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
99060 fnend

== File Layouts ==
Now lets inspect the anatomy of a properly formatted file layout. These should be placed in a subdirectory called filelay.

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...
<hr>
price.dat, PR_, 1

The first line contains the name of the Farm File, a unique string to prefix all of your subscript pointers, and the file version number. The subscript value is to ensure that the program knows the difference between the Farm File’s Farm Code, and the Route File’s Route Code. (One will be RT_CODE and the other is FM_CODE). These are separated by a comma. Spacing does not matter, so adjust your spacing so that it looks nice.

The Version number is used to determine when the data has changed, and an update needs to be made to your data file. Your file layouts should all start at version 0, and each time you want to make a change, you may increment this value by 1.

Each time you open a file with the FILEIO library, it reads the file version number of the file on disk (using the BR version() function), and then it compares it to the version number in your file layout. If your file layout has a higher version number then your existing data file, then the library opens the backup of the file layout for the version of the data file that exists on disk. It makes a backup copy of the existing data file, and creates a new file with the proper version number. Then it reads your records one at a time, and copies all the data from the old file into the new file one field at a time. If a field is dropped from the file layout, that data gets lost. If fields are rearranged, the data is copied and saved in the new file in the new positions. If a new field is added, it starts out blank (or 0).

If you look in the filelay folder, you will notice a version folder. This contains several files ending with a number. For example you may see a color.0, and a color.1 file.

If you run the fnopen function and it can not find your data file (usually because this is a new file and it hasn’t been created yet), ''the library will automatically create your file,'' based on the information you give in the first part of the file layout.

Also, whenever you make changes to your file layout, the function library will automatically update the data files on disk for you. It does this by renaming the old file, creating a new one with the new version number, and then copying the data from the old one to the new one a record at a time.

Any time it creates a file, or updates the file on disk, it creates a backup of the file ''layout''. The first time you run a program that tries to read your new data file, it will create the data file for you and make a backup of the layout, and if the number in your file layout is 0, then it will create, for example, a filelay\version\price.0 file, a backup of your file layout that the library uses to figure out what has changed the next time you try to update the file.

If you wish to make any changes to this data file, first you increment the version number, (in this case make the 0 into a 1). Then change the file layout all you want. You may rearrange fields, add new fields, add or remove keys, or change the record length.

The only step necessary for having your data files updated is to increment the version number every time you make a change to the file layout.

You may make any changes you like to the file layouts, but do not change the names of your existing subscripts. If you change the subscript name, not only will all the programs that reference that subscript be broken, but additionally, the routine will not understand that you are changing the name. It will think you are dropping the old field and adding a new field and any data stored in this location will be lost when the file is updated.

price.key, FARM

The second line contains the name of the first key, and a definition telling what the key is based on. These are separated by a comma. The key definition is made up of each of the subscript names in this file that form the keyfields for the file. When the library is called to open a file, if the file does not exist, or if it needs to be updated, a new one will be created. The function will read these subscript names that form your key definitions, and it will calculate the proper key position (KPS=) and length (KLN=) values. Then the create routine will use this information with the Index command to create the new key files.

price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127

Notice that the third key is based on three different fields. These are separated by a “/”. It is important that you use a “/” to separate your keys when you are building a key out of more then one field, because the function uses this “/” to help it make the proper BR syntax for defining complex key fields.

Also, note the "-U" at the end of the fieldname in the 4th key. This indicates that the "Description" part of that key is case insensitive. This translates to using the "U" on part of your key spec in Business Rules.

The file can have as many keys as you want. The function will keep parsing key file names until it reaches the next part of the layout. It opens any OutIn files with all keys so that any changes you may make to the data stored on disk will be properly reflected in all the key files.

The optional RECL= Parameter is read and used whenever a new file is created or an old one is updated. If it is not specified, the record length is calculated from the fields in the layout.

===================================================

The next line in the file is skipped by the parsing routine, and its purpose is to make the file layouts more readable to a programmer.

 
FARM$, Farm Code (or blank), C 4

Following the file and key structure, the fields are defined. There are three parameters on each field definition line, and you make one line for each field in your file layout. The first parameter is the subscript name that you will use in your program to refer to this data element. Place a $ at the end of the subscript name for all string elements. Don’t place anything at the end of the subscript name for numeric elements. Note that each of these names will be prefixed by the second parameter of the very first line of this layout.

The second parameter is the description. This description is for the benefit of the programmer, so when the programmer is reading the file layouts, (s)he can tell which field does what. The spaces are ignored, so you may include as many spaces as you wish to make the layout look good. It does seem like good general guidelines would be to limit your layout lines to 255 characters and your descriptions to 80.

The description is also used by the built in DataCrawler, a program that reads any of your data files and displays the entire contents in raw form in a listview. The Descriptions become the headings for each column in the listview.

Those descriptions are also used for the default captions for your fields if you use ScreenIO, a library for building GUI programs that itself builds off of fileio.

The third parameter is the form statement, which is pretty straightforward. Any items with a form statement of type “X” will be ignored, except that the length will still be used to calculate the position on disk of all remaining fields in the record. The library will take X fields into consideration when building the form statement, but not at any other time.

The fourth parameter is optionally a [[#Support for Dates|Disk Date Format]]. You can specify DATE(Julian) if you're storing your dates in Julian format on disk. Or you can specify DATE(cymd) or DATE(ymd) or DATE(mdy) or any other valid date spec here, and FileIO will treat this field like a date.

Your programs will still have to unpack it for you, fileio can't do that because fileio doesn't read the file for you.

However, the data crawler, the automatic updates, and screenIO, are all compatible with these dates specified in your file layout.

If the fourth parameter is anything other then DATE(format), then its treated as a comment and ignored.

The fifth and all later columns, if any, are treated as comments and ignored.

! default cost is normally zero
Comment line text must begin with an exclamation point, but it may be indented. Comment lines may appear anywhere (vertically) and are ignored. 
Blank lines are ignored as well.

#eof#
additional comments...
After the last field definition, an ''optional'' #eof# line may be specified, in which case any lines after that will be ignored.

 
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...

And that’s all there is to it.

=== Support for Dates ===
As of V2.48, file layouts support dates in any storage formats on disk. Whether you store your dates in Julian or in YMD or MDY or any other format, specify so in the 4th column of your file layouts, using the FileIO Date Keyword. ex: DATE(Julian) or DATE(YMD) or any other valid BR Date Format.

[[File:Dates0.png]]

When this is specified, it enables the FileIO data exploration tool (Data Crawler) to display the dates in human readable format. This works for both Viewing, and for Editing.

The new Date functionality also supports the File Layout Upgrade facility, allowing you to change the format of your dates on disk and FileIO will handle it automatically, upgrading the field to use the new date format for you.

It works also for Exporting your data files to CSV, and is supported automatically in the FileIO functions that do those exports. It converts the dates on export to a standard format (Default: m/d/cy) that you can specify in your FileIO.Ini File.

And it extends ScreenIO's date features to all date fields, no matter what format they're stored in. (Previously, ScreenIO's advanced date features only worked for dates stored in Julian on disk.)

This update adds two new ini file options:
CODE: SELECT ALL
DateFormatExport$='m/d/cy' ! Format of Dates when Exporting to CSV
DateFormatDisplay$='m/d/cy' ! Format of Dates when displaying in Data Crawler

You can use these to specify your preferred Date format for Viewing/Editing, and your preferred Date format for Exporting.

Remember, you can see the full list of FileIO ini file options, by looking in the source code at the top of FileIO.

There is a new optional parameter for all layout reading functions, mat NDateSpec$ and mat SDateSpec$ which correspond with the other arrays, to let you know which fields are date fields, so that you can develop routines in your programs to automatically pack and unpack the dates.

Important Note: Using FileIO, the reading of the data file is still done directly in your programs. So this does not change how your existing programs work. It does not unpack the dates for you in your programs. You still have to do all that.

For this reason, upgrading to the new Date processing will not break any of your current code.

=== Debugging Tips ===

When you're making new layouts, a missing comma can cause FileIO to parse the layout wrong and give you errors. Here are a couple tips to help ensure your layouts are error free before using them in your programs.

*Use the Data Crawler to test your layout. The data crawler is the simplest way to test your new layout without writing any code. It opens it and accesses the file in a very simple and straight forward manor to help identify any errors in the layout that you might have.

*If you have trouble with the form statement, you can't see whats in it because FileIO uses CForm$ to compile your form statement to make your programs run faster. But here's a way to tell what the original form statement was that FileIO generated when it put the strings first and numbers last in your program: Open the file in the Data Crawler. When you get an error, type "Print FormStatement$" to see the original form statement.

This works even if your file is working fine. Any time the file is opened with the data crawler, you can press CTRL-A and then type PRINT FormStatement$ and it will print out the uncompiled form statement for the file.

== Utilities ==

Now that you have your file layouts defined, you have access to several powerful utilities right out of the box using Fileio. Additionally, several more utilities are available as [[#FileIO_Add-on_Packages|Add-Ons]], including our most popular development tool [[Screenio|ScreenIO]]. You can read more about them in their section below.

But for now, lets take a look at some of the wonderful free utilities that come built into Fileio.

Some of these utilities are accessible from your code via library functions, but the primary way you access any of them is by simply loading the FileIO Library and running it directly.

=== DataCrawler ===
The data crawler is the original utility of FileIO. This utility shows you first a list of all data files allowing you to select one.

Select a data file and press enter, and FileIO will then display a listview containing all the data in the data file. This list is sized based on the size of your main BR window (window 0) automatically to take up the full size available to it, so if you want to see more, try [[Open Window|opening window 0]] larger before running FileIO.

At the top of the window is a filter box, and you can type anything you want in there and click "Refresh" and it will reread the data file, shortening the list to show only those records that match (case insensitive) what you have typed.

If you have ScreenIO installed, then FileIO's data crawler will take advantage of the included Animation Engine in ScreenIO to animate a loading window while the listview is displaying. If you don't have ScreenIO then FileIO will simply load the listview.

If you don't want to wait for the entire file to load, press ESC to stop the load process.

If the file is empty, FileIO will display a message box letting you know.

This tool is very useful for sorting out data errors. It will allow you to look inside any data file you have a layout for and directly view the data there.

At the bottom of the Data Crawler are several buttons. There's a Jump button that repositions the file by a key you specify and then loads the list with the data from that key on down to the end of the file.

There is a "Columns" button which you can use to decide which columns should show up on the listview. Fewer columns means faster loading so sometimes for large files I press ESC immediately when the file first starts loading to cancel the load. Then I click "Columns" and check only the columns I want to see. Finally I press the "Refresh" button to trigger it to read the file again and this time it loads much faster then before.

Next you'll find an Export button which starts the process for exporting a file to CSV. You can read more on that in the next section. And next to that is a Quit button.

In this example, we loaded the file "Read Only" so it put everything in a listview. But there are times when its useful to fix data errors this way too, especially during development. So if you want to directly edit your data file, on the first page select the file you want to edit and instead of pressing "Enter" or clicking "View", this time press "F5". F5 is the secret Edit button that loads a data file into a grid instead.

You can use the grid to change records, delete them or add them, and in addition to the buttons listed above, it also has an "Import" button for importing a CSV file into this data file.

Any changes you make to the data file are not saved until you click the "Save" button (which also only appears when you're in Edit mode).

In the 01/2015 release of FileIO, each records rec # is displayed in the listview, to aid in debugging bad data problems.

==== Debugging Tip ====
Any time you're viewing a file layout in the Data Crawler, you can see the Uncompiled Form Statement by pressing CTRL-A to get to an ATTN prompt, and then entering the command:

print FormStatement$

and it will print out the original form statement.

==== Another Debugging Tip ====

The FileIO Datacrawler ignores records that it cannot read. This is to allow for data files that have multiple record layouts in one data file. You make a custom layout for each record type and the data crawler shows just the records that match that type in the file.

However that becomes a problem when you're making a layout to work with an existing data file. Error 726 indicates that something minor in the file layout doesn't match the data on the disk, but these errors are ignored so you might see either an empty data file, or a data file with some records missing. If that happens, you need to see the missing records in order to figure out what is wrong with your layout. '''''It's very important that you don't try to use a file layout that isn't quite working right. Make sure your layout works and can read every record of a file that it should read before using it.'''''

To see the records that could not be read in a file, run the data crawler on the layout, then press CTRL-A to get an ATTN prompt. From there, enter the command

print mat BadRead$

and it will print all the records that were ignored because the file layout didn't match them. It prints out the raw data from the file.

==== Function Access to use Data Crawler in your programs ====
You can use the data crawler in your own programs by using one of the following functions:
* [[#fnDataCrawler|fnDataCrawler]] - Open a Listview showing the data file
* [[#fnDataEdit|fnDataEdit]] - Display the data in an editable grid
* [[#fnShowData|fnShowData]] - This function does the same thing as the above two, but with many many more options allowing you to customize exactly what appears and exactly what they're allowed to change.

Note: its not recommended to allow your customers to use the data crawler to access your data files directly. There's no way to specify validations or do anything complicated, so unless you're careful, there are lots of ways your customers could use this tool to do damage to your data files. It is a programmer tool only.

If you do decide to use it for your end users, be careful how you implement it.

=== Import/Export to CSV ===

You can use FileIO to export your data files to CSV or import from CSV into your data file. To do this, you want to run the data crawler and select the file layout you're looking for. Then, view it (or press F5 to edit if you want to import something). Click on the Export button and it will ask you to select a file. Once that is selected it will ask a couple other simple questions, and when you've specified the options to your satisfaction, click the Export! button. A new CSV file will be created.

Import is even more simple. To import, you must be in Edit mode (press F5 to select the file instead of the enter key) and then simply select the Import button. It will ask you again to choose the file, and then it will ask you if it should update all files by Record Number (if record number is recorded in the CSV file) or by Key (if the file has keys) or to just Add all information to the file. Select what you want and press Import and the CSV file is added to the BR data file.

==== Function Access to Import/Export from your programs ====

You can use the following functions to call the Import and Export functionality from your code.

*[[#fnCSVImport|fnCSVImport]]
*[[#fnCSVExport|fnCSVExport]]

These functions are intended to give you the ability to use our functionality to write your own import and export routines for your customers, because its not a good idea to let your customers run the Data Crawler.

=== Generate Layout Wizard ===

There is also a Generate Layout Wizard utility in FileIO. This utility is there to help you build your file layouts. It is designed to work with a certain style of BR programming that was common in the 80s and 90s. So if your software is written in a style that opens the file directly, and reads/writes the data to a long series of individual variables, the Generate Layout Wizard is for you.

To use it, start by running FileIO. Then, don't select a layout - instead, click on the "Generate Layout" button.

You'll see a screen with a bunch of large text boxes, a small grid, and some buttons.

The first thing you want to do is select the "Browse" button and then select a .wb or .br file that contains a program that reads or writes Most of the File.

When you select one, press the Scan All button and it fileio will search the whole program looking first for all the open strings. It will take the file that is opened the most times and then search for all read statements to that file. It will look for the longest read statement and then find the Form statement associated with that Read statement, and any DIM statements for any variables used.

If you don't like the file its chosen, click the "Open Scratch Pad" button to open the temp work file it uses into the program of your choice (I use myEdit for BRS files). Simply select all the open statements for the file you DO want to build off of, then click the Paste button to paste those open statements into the "Open String" list. After that click "Clear All" to erase what it did on the first search and then click "Scan All" again to rescan the program using this new data file.

You may have to help it a bit, but once it has a proper matching open statement, read statement, form statement and dim statements for any arrays used, press the "Generate Layout" button and it will build a layout for that file.

Finally, load the layout it built and clean up anything if you want, and consider adding better descriptions for each of the fields that you know (as it will use the variable names for both the subscripts AND descriptions in the layout).

When you're all done, click "Done".

==== Functions to Generate Layouts from your code ====

* [[#fnGenerateLayout_.26_fnWriteLayout|fnGenerateLayout]]
* [[#fnGenerateLayout_.26_fnWriteLayout|fnWriteLayout]]

=== Code Templates ===

One more tool FileIO has to help is the ability to generate code based on your file layouts.

Run FileIO and this time select a file layout and press "Generate Code". A window will pop up listing all the "Code Templates" that are available. Select one (and then select a key if it asks you - some templates require extra info). It looks like nothing happened, but the code you generated is now in your clip board. Paste it somewhere and take a look at it!

Code Templates help us to standardize our ways of doing things, which eventually leads to more and more powerful tools we can use. Code Templates also help ensure we use cleaner code by doing some of the busy-work of writing clean code for us.

==== Writing Code Templates ====
FileIO ships with several basic code templates. If you want to add your own, take a look in the filelay\templates folder (configurable in fileio.ini) and look at basic.brs. Copy it to your own program and then modify it to have your own code templates in it. Write me at gabriel.bakker@gmail.com with any questions. I want to help.

And if you write good code templates, its easy to share them with the BR community. Anyone can download your templates and place them in this folder and they'll instantly be available for use.

== FileIO Function Reference ==
''The FileIO Library contains a number of other useful functions.'' The following functions are available and you are welcome to use them:

=== Primary Functions ===

==== fnOpen ====
fnOpen is the primary function that opens a file, and it’s used like so:

''def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, DontSortSubs, Path$*255, Mat Descr$, Mat FieldWidths, SupressPrompt, IgnoreErrors, SuppressLog)''

Note that all of the parameters after MAT Form$ are optional. If you need to specify a parameter in the middle of the optional parameter group, just list zeroes and empty strings for the intervening unused parameters.

*FileName$ - The filename of the file layout for the file you’re reading.
*MAT F$ - The array that will be used to hold the string data for the file.
*MAT F – The array that will hold the numeric data for the file.
*MAT Form$ - An array of form statements.
*InputOnly – 1 means open for input only. 0 means open for OutIn and open every key file associated with the given data file (this is because all key files need to be open for the keys to be updated on an output) (defaults to 0). Files opened for input process considerably faster than files opened for output. Furthermore when files are opened for input only, alternate key files are ''not'' opened.
*KeyNum – This tells the function of which key to return the file handle (defaults to 1). Specify -1 to force the file to open Relative, without using its keys. If a file has no keys, it will always be opened Relative.
*DontSortSubs – The function by default, when compiling the Form statement, will sort the string and numeric subs in order to allow for reading the data into an array, and this parameter would turn this functionality off. However, if you are trying to read your data without reading it into an array, you are missing out on some serious efficiencies. You should normally leave this option turned off (0). This is a totally unsupported feature, and should always be set to 0, if it is specified at all.
*Path$ - The path to your data files. This optional parameter can be passed in by the calling function. It is prefixed to the beginning of the paths given in the file layout files. It is useful when your data files can be in different locations depending on the state of your program.
*mat Description$ - This optional parameter provides a way to read the description for each field from the original file layout. If the parameter is not provided, no description data will be returned.
*mat Fieldwidths – This optional parameter will return an array of the calculated display field widths. This number will always be at least large enough to contain the data for this field.
*SuppressPrompt - This optional parameter can be used to suppress the prompt normally given when fileIO creates a file. It can have three values. A value of 0, the default, uses the setting stored in your FileIO fnSettings routine to determine weather or not to prompt on Creation of a new file. A nonzero value always suppresses the prompt. A value of 1 indicates never to create a file if the file doesn't exist. A value of 2 automatically creates the file if the file doesn't exist.
*IgnoreErrors - Normally when fileio opens a data file, if there are errors trying to open the file, it prints them out to the debug console and pauses so that you can try to find out whats going wrong. If you specify 1 for "IgnoreErrors" it will cause Fileio to log those errors instead, and continue loading your program. This will result in the fnOpen file function returning Zero instead of the opened file number, so if you use IgnoreErrors, you need to test to make sure that fnOpen returned a file number before you try to access the file.
*SuppressLog - this optional parameter can be used to suppress writing to the log file for this one specific open statement. I use it for files that will be opened all the time, for example, the menu data file on one of my customers systems. Without this boolean parameter, his log file is quickly filled up with useless information any time his employees look at his menu. I specify this optional parameter to suppress logging anything about the menu file so that I can more easily find the actual programs they've used when looking in the logfile.

'''''Note: When using fnOpenFile, you really want to call your local function fnOpen, which in turn calls fnOpenFile for you.''''' FnOpenFile is for internal use only.

Example:

Let FFILE=FNOPEN(“FARM”,MAT FARM$,MAT FARM,MAT FORM$,0,2)
Let RFILE=FNOPEN(“ROUTE”,MAT ROUTE$,MAT ROUTE,MAT FORM$,1,3)
Let CFILE=FNOPEN(“CUSTOMER”,MAT CUSTOMER$,MAT CUSTOMER,MAT FORM$)

assuming:
farm.dat has 3 keys: farm.ky1, farm.ky2, farm.ky3
route.dat has 4 keys: route.ky1 … route.ky4
customer.dat has 2 keys: customer.ky1, customer.ky2

This will perform the following opens and set the following variables:

OPEN #1: “Name=Farm.Dat, kfname=farm.ky2”,internal,outin,keyed
OPEN #2: “Name=Farm.Dat, kfname=farm.ky1”,internal,outin,keyed
OPEN #3: “Name=Farm.Dat, kfname=farm.ky3”,internal,outin,keyed
OPEN #4: “Name=Route.Dat, kfname=route.ky3”,internal,input,keyed
OPEN #5: “Name=Customer.Dat,kfname=customer.ky1”,internal,outin,keyed
OPEN #6: “Name=Customer.Dat,kfname=customer.ky2”,internal,outin,keyed
LET FFILE=1
LET RFILE=4
LET CFILE=5

This will also resize the arrays, set the form statement, and create all the subscripts to make accessing the data clear and simple, as in the above example. The KEYNUM parameter is where you list the key file you would like to use for reading and writing. The extra keys are opened to ensure that all keys get updated properly when the file is changed.

Example:
DIM FORM$(1),PRICE$(1)*255,PRICE(1),
DIM DESCRIPTION$(1)*80,FIELDWIDTHS(1)

Let PRICEFILE=FNOPEN(“PRICE”,MAT PRICE$,MAT PRICE,MAT FORM$,0,2,0,"",MAT DESCRIPTION$)

Assuming the Price File layout (filelay\price) contains:

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30

This will perform the following opens and set the following variables:

OPEN #1: “Name=Price.Dat, kfname=Price.ky2”,internal,outin,keyed
OPEN #2: “Name=Price.Dat, kfname=Price.ky1”,internal,outin,keyed
OPEN #3: “Name=Price.Dat, kfname=Price.ky3”,internal,outin,keyed
let PRICEFILE=1
let PR_FARM=1
let PR_ITEM=2
let PR_GRADE=3
let PR_DESCR=4
let PR_PRICE=1
let PR_COST=2
let PR_XOPRICE=3
let PR_XOCOST=4
let PR_MOPRICE=5
let PR_MOCOST=6
let PR_VOPRICE=7
let PR_VOCOST=8
MAT FORM$(1)
MAT PRICE$(4)
MAT PRICE(8)
MAT DESCRIPTION$(12)
MAT FIELDWIDTHS(12)
let FORM$(1)=CFORM$(”form C 4,C 4,C 4,POS 74,C 30,POS 50,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2”)
let Description$(1)= “Farm Code (or blank)”
let Description$(2) = “Item Code”
let Description$(3) = “Quality”
let Description$(4) = “Description of Price Rule”
let Description$(5) = “Default Price”
let Description$(6) = “Default Cost”
let Description$(7) = “Default Christmas Price”
let Description$(8) = “Default Christmas Cost”
let Description$(9) = “Default Mothers D Price”
let Description$(10) = “Default Mothers D Cost”
let Description$(11) = “Default Valentine Price”
let Description$(12) = “Default Valentine Cost”
let FieldWidths(1) = 4
let FieldWidths(2) = 4
let FieldWidths(3) = 4
let FieldWidths(4) = 30
let FieldWidths(5) = 8
let FieldWidths(6) = 8
let FieldWidths(7) = 8
let FieldWidths(8) = 8
let FieldWidths(9) = 8
let FieldWidths(10) = 8
let FieldWidths(11) = 8
let FieldWidths(12) = 8

There are a few things I’d like to point out about the example above. First, you will notice that the form statement jumps around to put all the strings first, and then the numbers last. This is why it has a “POS 74, C 30,POS 50”. Then notice that the subscripts for the string variables are 1 .. 4, and the subscripts for the numbers are 1 .. 8. Finally, the order of the Description and FieldWidth fields also match the sorted positioning of the Form Statement.

The reason that we sort our form statements is so that BR will allow us to read the file into arrays by saying:

Read #pricefile, using form$(pricefile) : mat price$, mat price

Without resorting, the above statement would give a conversion error as BR attempted to put the PR_PRICE field inside mat price$(4). However, because we have reordered the form statement, we are able to read them safely into two arrays, and then we will be able to use the values without caring what position they are in the file, by simply saying PRICE$(PR_DESCRIPTION) when we want the description, and PRICE(PR_PRICE) when we want the pr_Price field.

Another thing you may notice about the above example is that it gives the calculated display length for the numeric fields as 8, when on the disk (and in the file layout) they are listed as BH 3.2. The reason for this is the program looks at the BH 3, and figures that a number that takes up 3 bytes on disk has a potential maximum size of 256**3 or 16,777,216, and therefore will need up to 8 characters of screen display space to view.

Finally, note that any field with a form statement of X is ignored by the library, except that the blank space is used when building the FORM statement.

==== fnCloseFile ====
This function will close the specified file number and all keys that were opened with the file. The purpose of this function is to facilitate the closing of the extra keys that are opened when you open a file for OutIn with the library. There is no need to use this for files opened for input because it is easier to just close the file directly. Secondary keys are not opened by FileIO for files opened for input only.

You must give the function the name of the file layout. It uses this information to determine how many keys were opened, and how many it must therefore close.

Then it basically starts at the file number you gave it, and closes the next X files that were opened with the same file name as this, where X is the number of keys associated with this file.

The syntax is:

''fnCloseFile(filenumber,filelay$;path$)''

*FileNumber – The filenumber of the file you are trying to close.
*FileLay$ - The name of the file layout for this file. This is used to determine how many keys the file would have been opened with and therefore how many we now need to close.
*Path$ - Optional Alternate Path. Use to close files that were opened using the open file's optional alternate path parameter.

==== fnGetFileNumber ====
FnGetFileNumber is a simple function to find a valid unused file handle. If you use this function in all of your programs, they will become much more portable, as you will never have to worry about your file handles fighting with each other. The function will return 0 if no free file number was found (but with 999 of them available now, I have never seen it happen).

''fnGetFileNumber(;X,Count)''

*X – This optional parameter will specify where to start looking.
*Count - This optional parameter will specify how many file numbers to find in a row. If count is 3, then fnGetFileNumber will return the first filenumber in the first gap of three unused file numbers that it finds.

=== File Reading Helper Functions ===

These functions perform various useful calculations to aid in interacting with data files when you're using fileio.

==== fnBuildKey$ ====
This function will return the key for a given record in a data file. It actually reads the file layout and builds the key to match the layout.

''FnBuildKey$(Layout$, Mat F$, Mat F; Keynum)''

*Layout$ - the name of the data file to build the key for.
*Mat F$ - the string array of the file object
*Mat F - the numeric array of the file object
*KeyNum - This optional parameter specifies which of the key files in the given layout the key should be built for.

To use this, you want some code like in the following example:

mat customer$=("") : mat Customer=(0)
let customer$(cu_name)=CustName$
let customer$(cu_phone)=CustPhone$
read #customer, using form$(Customer), key=fnBuildKey$("customer",mat Customer$,mat Customer,2) : mat Customer$, mat Customer nokey KeyNotFound
! The above code assumes that the second key of the Customer file is based on the Name and Phone fields.

By using this logic you are able to avoid directly specifying the key in your code - which means that even if the key changes in the future, as long as your code specifies enough information, it will still find the correct key. In our example, even if we dropped the phone number from the key in the future, or even if we expand the length of the Customer Name field, our code would still work and fnBuildKey$ would still build the correct key without us having to look at or change our code again.

This kind of reasoning is central to the fileio system, which, when implemented properly, ensures that you can change your data files in any way you need to in the future, without breaking your existing programs.

==== fnUniqueKey ====
This function tests to see if a given key is unique to the specified file. This function is very useful for situations where you need to ensure that the user-entered key is unique.

''fnUniqueKey(Fl,key$*255)''

*FL – The file number of the opened file.
*Key$ - This is the key to test. If this key is the key for a preexisting record in the file, the function will return false. If this key can not be found in the file, the function will return true.

==== fnMakeUniqueKey$ ====
This function generates a unique key for a given file. This is useful if you do not care what the key is, but it needs to be unique. I use this function in situations where the user never needs to know what the given key is.

This function reads the key length for the given file. Then it returns a string that is the right length, which is generated by counting in binary until a key is found that does not appear in the file. The first key found for a 4 byte key field would be chr$(0)&chr$(0)&chr$(0)&chr$(0). If that key was already in use in the file, the function would return chr$(0)&chr$(0)&chr$(0)&chr$(1). If that one was also in use, it would then try chr$(0)&chr$(0)&chr$(0)&chr$(2), and so on until it found one that wasn’t in use.

''FnMakeUniqueKey$(fl)''

*FL – This is the file number of the opened file for the desired key.

==== fnKey$ ====
This function formats the key for the given file number. All it does is ensure the key is the correct length. You should use fnBuildKey$ instead to properly build the correct key for the record you want to read.

''FnKey$(FileNumber, Key$)''

*FileNumber - the file number we are formatting the key for
*Key$ - the key we are trying to format.

==== fnNotInFile ====
This function will determine if a non-key element in a line is unique. It works almost exactly like fnUniqueKey specified above, except that it allows you to enter the subscript value of the element you are checking for uniqueness. You can use this to look for uniqueness in any field, not just in the key field. Additionally, the search engine used by this function looks for a partial match, and will only return true if the given string is not found anywhere in the specified element for the given file.

''fnNotInFile(string$*100,filename$,sub)''

*String$ - Value to check for uniqueness in this file.
*Filename$ - This is the name of the file layout of the file you want to check. This file does not have to be open in order for you to search it, because the function will open it for you.
*Sub – This is the subscript value of the element you are checking.

==== fnSortKeys ====
This function takes an array of Primary Keys indicating records in the data file, and resorts it into the order you would have expected using one of the other keys for your data file.

For example: Lets say you had a customer file, and the first key was Customer Code and the second key was Customer Last Name. This function would take an array of Customer Codes and sort it into Last Name order.

This function requires the file to already be opened (which is usually the case when you have an array of keys from that file).

''fnSortKeys(mat Keys$,Layout$,DataFile,mat F$,mat F,mat Form$;KeyNum)''

*mat Keys$ - the array of keys. These keys are based on whatever key the file was opened with in DataFile.
*Layout$ - the file layout for the file.
*DataFile - the open file number matching the key file that matches mat Keys$.
*mat F$ - array sized to hold the strings from the data file. This is the array you get back from fnOpen.
*mat F - array sized to hold the numerics from the data file. This is the array you get back from fnOpen.
*mat Form$ - array of form statements, that you get back from fnOpen.
*KeyNum - This is the key that we'll sort based on. If not given, the first key listed in the layout is assumed.

=== File Reading Functions ===

These functions actually read information from your data file and return it. These functions can be used to simplify the logic in your programs for many common tasks.

==== fnReadAllKeys ====
This function will read through a file, returning the specified element(s) from each record into (a) dynamically dimensioned array(s). For example, I could tell it to give me the Inventory Code for every inventory item in my database in one array, while placing the Inventory Description (name) for each item into the corresponding position in another array.

''fnReadAllKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$;sub2,mat out2$)''

*Fl – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array
*mat out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

For example:

FnReadAllKeys(InventFile,mat Invent$,mat Invent,mat Form$,IN_Code,mat InvtList$,IN_Name,mat InvtNames$)

==== fnReadMatchingKeys ====

This function will read through a file, returning the specified element(s) from each record where the key matches the specified key into (a) dynamically dimensioned array(s). This function is the same as the above function except this one will filter the results, returning only those records where the key matches the specified key.

''fnReadMatchingKeys(Fl,mat f$,mat f,mat fm$,key$,keysub,sub1,mat out1$;sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - Only records where the key field matches key$ will be returned.
*Keysub – This tells the function which element is the key element for this particular file number.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadAllNewKeys ====

This function will read through a file, returning the specified element(s) from each record that isn’t already there into (a) dynamically dimensioned array(s). This function is the same as the above function, except this one will filter the results returning only those records that don’t already exist in the array (eliminating duplicates).

''FnReadAllNewKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$; dont_reset,sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Dont_reset – By default the array will clear the contents of the arrays that are passed in. This Boolean flag will instruct the function to not empty the passed in arrays.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadFilterKeys ====

This function by Mikhail Zheleznov is a modification of the above functions. Like its predecessors, it reads an entire file, populating the specified arrays with data from all or some of the records in the file. The given subscripts specify which fields to return from each record. The key given specifies search criteria for the records. The filter specifies filtering criteria that can be preformed on the data before it is returned.

''FnReadFilterKeys(Fl,Mat F$,Mat F,Mat Fm$,Key$,Keyfld,Sub1,Mat Out1$;Filter$,Filter_Sub,Readlarger,Sub2,Mat Out2$, Sub3, Mat Out3$, Sub4,Mat Out4$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - The key to search for in the read statements
*Keyfld – the subscript of the key field in the data file. This must match the key field specified in the data file otherwise the function won’t work.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Filter$ – This optional parameter identifies matches to search for in the records. It works in conjunction with Filter_Sub
*Filter_Sub – This parameter specifies which field to look for in the records for matches to Filter$. Only records which have Filter$ in the specified field will be returned.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.
*Sub3 – Subscript of the element to return in the third array. This is optional. If it is specified, you must give MAT out3$, or BR will return an error.
*MAT out3$ - Array in which to return the third (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub3 is given (non-zero). This parameter will not be used if Sub3 is not given or is given as 0.
*Sub4 – Subscript of the element to return in the fourth array. This is optional. If it is specified, you must give MAT out4$, or BR will return an error.
*mat out4$ - Array in which to return the fourth (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub4 is given (non-zero). This parameter will not be used if Sub4 is not given or is given as 0.

This function was written by Mikhail Zheleznov for the fileIO library.

==== fnReadDescription$ ====
''fnReadDescription$(Fl,Subscript,key$,mat F$,mat F,mat Form$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout) (RT_NAME, which should equal 2 after opening routefile (unless we change the file layout later)).
*key$ - Item that should match a key in this file somewhere (in this case it is the route code from the farm record).
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading they have to be dimensioned properly, which is why we use our colorcat$ and our colorcat for these parameters.
*mat Form$ - This will need to be our array of form statements, so the function can read the file properly.

Lets take a look at how this function works:

In the example program I used above, I am reading the Color File to get details about each color. The color file contains a colorcat code field, but I want to display the colorcat description. The colorcat file contains a few details about a color category, and it is indexed based on colorcat code:

route.dat, RT_
route.key, CODE
recl=512
===================================================
CODE, Routing Code, C 6
NAME, Routing Name Description, C 30
MOFT, T/A/C (truck/air/courier), C 1
SHIPPINGDAY, Day of Week for Shipping, C 7

Now, as you know, in the above example, we have already opened the ColorCat File, and we have opened and read a Color record.

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
30180 LET ccode$=color$(CO_CODE) !:
LET Name$=color$(CO_NAME)

Now all that’s left to do is to take the Color File’s ColorCat code and use it to look up the ColorCat File’s description.

30190 LET ColorCat$ = fnReadDescription$(ColorCatFile, CC_NAME, Color$(CO_CATEGORY),
mat ColorCat$, mat ColorCat, mat form$)

==== fnReadUnopenedDescription$ ====
This function accomplishes the same thing as fnReadDescription except that it opens the data file for you. It is slower then FnReadDescription$, but it is easier to use.

''FnReadUnopenedDescription$(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the value of the key field in the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2, so sometimes it is a good idea to design your data files so that string field number two is a descriptive field, like Name or Description.

This function only works on the first key file for each data file. This function is a convenience function but it is slow because it opens the file and closes it for each call. Opening a file is one of the most time consuming program operations.

==== fnReadNumber ====

fnReadNumber does the same thing that ReadDescription does except it reads a numeric field instead of a description.

Lets take a look at how this function works:

''fnReadNumber(Fl,subscript,key$,mat F$,mat F,mat fm$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout).
*Key$ - Item that should match a key in this file somewhere.
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading. They have to be dimensioned properly by [[FileIO_Library#fnOpenFile|fnOpen]].
*mat Fm$ - This will need to be our array of form statements, so the function can read the file properly.

==== fnReadUnopenedNumber ====
This function accomplishes the same thing as fnReadNumber except that it opens the data file for you. It is slower then FnReadNumber, but it is easier to use.

''fnReadUnopenedNumber(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the key of the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2.

==== fnReadRelativeDescription$ ====
This function is the same as fnReadDescription$ but for Relative Files.

''fnReadRelativeDescription$(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat F,mat form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedDescription$ ====
This is the same as ReadUnopenedDescription$ but for Relative Files.

''fnReadRelUnopenedDescription(Layout$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRelativeNumber ====
This is the same as fnReadNumber but for Relative Files.

''fnReadRelativeNumber(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat f,mat Form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedNumber ====
This is the same as fnReadUnopenedNumber but for Relative Files.

''fnReadRelUnopenedNumber(LayoutName$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRecordWhere$ ====
This function returns the record where the given element matches the given value. It does not depend on any key files, and it can be used to locate a record based on any element. However, it loops through the entire data file to do this and it could be a bit slow for large data files. This function opens the file for you, so the file does not have to be already opened.

''FnReadRecordWhere$(Layout$,SearchSub,SearchKey$*255,ReturnSub)''

*Layout$ - the layout of the file we are searching
*SearchSub - Subscript of the element to look in
*SearchKey$ - The value we are looking for
*ReturnSub - Subscript of the element to return

=== FileIO Utility Functions ===
==== fnDataCrawler ====
This function launches the Data Crawler as a function, so you can make your own programs link to it. Special thanks to Mikhail Zheleznov for turning the DataCrawler into a library function.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnDataEdit ====
This function is the same as fnDataCrawler only it opens a Grid for editing.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnShowData ====

This function builds a list or a grid in a floating window that is tied to a data file. It uses the same function that the datacrawler uses, but its much more customizable. All other datacrawler functions are just wrappers for this one.

The first parameter is the only required parameter.

''def library fnShowData(FileLay$;Edit,sRow,sCol,Rows,Cols,KeyNumber,Caption$*127,Path$*255,KeyMatch$*255,SearchMatch$*255,CallingProgram$*255,mat Records,mat IncludeCols$,mat IncludeUI$,mat ColumnDescription$,mat ColumnWidths,mat ColumnForms$,DisplayField$*80,mat FilterFields$,mat FilterForm$,mat FilterCompare$,mat FilterCaption$,mat FilterDefaults$,mat FilterKey)''

*FileLay$ - the file layout you want to display
*Edit - 1 for Edit (Grid) and 0 for View (Listview)
*sRow, sCol - the start position. if not given, its centered. If given but out of bounds, they'll be automatically adjusted to fit the grid on the screen.
*Rows, Cols - the size. If not given, defaults to fullscreen. If given but not big enough to fit the UI elements you request, they're automatically adjusted to fit everthing.
*KeyNumber - the Key to use when reading the data, used with other parameters. If not given, the file is read Relative for faster performance. Required if KeyMatch$ is given.
*Caption$ - the Caption to display, defaults to FileIO's Datacrawler
*Path$ - Alternate path to use for data files (Prepended to the name found in the layout)
*KeyMatch$ - Show only records that match this key. You can use Partial Keys. If this parameter is given, you must also give KeyNumber (above).
*SearchMatch$ - Show only records that contain this substring in them anywhere
*CallingProgram$ - used for logging purposes, pass in the system function Program$
*mat Records - Show only these records in the Grid. Use it to control exactly what the user sees.
*mat IncludeCols$ - Show only these columns. These column names must match the subscript names from the file layout.
*mat IncludeUI$ - Which UI Options to show. Build this array with one element for each optional UI element to include. Explanations of UI elements follow:
**"ColumnsButton" - adds a Select Columns button that the user can use to modify which columns appear on the list.
**"ExportButton" - adds an Export to CSV button that exports the data to a CSV file.
**"ImportButton" - adds an Import from CSV button that imports from the CSV file.
**"AddButton" - adds a button that can be used to add records to the data file.
**"SaveButton" - adds a button allowing the user to save changes
**"DeleteButton" - adds a button allowing the user to delete a row
**"KeyButton" - adds a button allowing the user to jump to a specified position by key or by record number (depending on if the file is opened keyed or not)
**"QuitButton" - adds a Quit button to the screen (the Esc key also quits)
**"Search" - adds a case insensitive search box to the screen.
**"Border" - adds a border around the screen
**"Caption" - adds a caption. (If you specify a caption, this is automatically turned on. If you don't specify a caption but turn on caption here, then FileIO uses the default FileIO data crawler caption.
**"Recl" - adds the Recl to the caption
**"Position" - adds the positions to the field descriptions in the column headings.
*mat ColumnDescription$ - Show these captions. If blank, use the descriptions from the layout
*mat ColumnWidths - Use these widths for the data, if not given, calculate from the file layout
*mat ColumnForms$ - Display Format for the data, including DATE and FMT and PIC
*mat DisplayField$ - Counter Field to display on the Loading Window. If its a field with an associated DATE ColumnForms$ value, that column form will be used when displaying the Counter Field. It can be any of the following:
**REC - this will display the current "REC/LREC" data in the loading window.
**READCOUNT - this will display the "Record Count / LREC" in the loading window.
**FINDCOUNT - this will display the number of records that match the current search criteria by itself in the loading window.
**A Field Name - one of your field names will display that field value in the loading window
**A string literal - anything else will display as a string in the loading window, so you could put something like "Loading, please wait" here and it will display.
*mat FilterFields$ - Contains the subscript of the field to compare to
*mat FilterForm$ - Contains the format of the field to compare to
*mat FilterCompare$ - Contains the comparison type ("<>" or ">" or "=" or ">=" or "*") (* means do a substring search)
*mat FilterCaption$ - The caption for the filter box
*mat FilterDefaults$ - The default value for the filter information
*mat FilterKey - The action to use when filtering the data this way (0 means simple exclude, 1 means start here, -1 means stop here)
**The final five arrays can be used to add user filter boxes to the data grid. You need one element in each array for every custom user filter box on the screen.

==== fnBeginAudit ====

The [[AuditBR|FileIO Compare]] routine is available and can be called from within your programs. To do so, call fnBeginAudit to mark the Start of the compare, then do whatever you need, then run fnCompare to compare everything that has changed between when you ran fnBeginAudit and when you ran fnCompare.

See [[AuditBR#fnBeginAudit|the documentation]] for more details.

==== fnCompare ====

See [[AuditBR#fnCompare|the documentation]] for more details.

==== fnCSVImport ====

This function calls the FileIO Import routine, the same one that you get from the Datacrawlers Import Button.

''fnCsvImport(Layout$*64;SuppressDialog,FileName$*300,ImportModeKey)''

*Layout$ - The file layout to import into
*SupressDialog - 1 to Supress the Import Dialog
*FileName$ - the name of the CSV file (Required if Dialog is Suppressed)
*ImportModeKey - the Import Mode Key (Required if Dialog is Suppressed)
**-1 - Add all records to the file
**0 - Update by Record Number (The file must contain a RecNum column and it must be first)
**1+ - Any positive number means Update by that Key (as listed in the layout).

==== fnCSVExport ====

This function exports a data file to a CSV file.

''fnCsvExport(Layout$*64;SuppressDialog,Filename$*300,IncludeRecNums,KeyNumber,StartKey$,KeyMatch$,Startrec,mat Records,SearchMatch$)''

*Layout$ - The File Layout to Export
*SuppressDialog - (1 to Suppress the Export Dialog, 0 to show it)
*Filename$ - the output file name (Required if SuppressDialog is 1)
*IncludeRecNums - Include a column with the Record Numbers in it
*KeyNumber - Use this key when reading the data for export
*StartKey$ - Start with the record that matches StartKey$
*KeyMatch$ - Export only the record(s) that match KeyMatch$
*StartRec - Start with this Record Number
*mat Records - Export only these records
*SearchMatch$ - Export only records containing this search string anywhere in them

==== fnExportListViewCsv ====

Exports the contents of the specified Listview in CSV format.

''fnExportListViewCsv(Window,Spec$;GenFileName,Delim$,FileName$*255)''

*Window - The Window containing the listview.
*Spec$ - The Spec identifying the listview.
*GenFileName - Flag telling weather or not to generate the file name.
*Delim$ - Delimiter to use. Comma is default.
*Filename$ - Filename to use

==== fnGenerateLayout & fnWriteLayout ====

This function calls on the Generate File Layout Wizard to generate and save the layout indicated by the parameters you give it. You must give it the same valid parameters that you would have come up with if you worked through the layout wizard the normal way, by running FileIO directly and choosing "Generate Layout".

You can also bypass the automatic parsing and generate a layout by specifying all the data directly and using fnWriteLayout.

''fnGenerateLayout(mat OpenStrings$, ReadString$*999, FormString$*20000, DimString$*999; DisplayFile)''
''

*mat OpenString$ - array of all the open strings for the given file from one of your old programs.
*mat ReadString$ - solid read statement from one of your old programs reading the entire record, (or at least everything you want in the layout).
*mat FormString$ - the form statement that goes with the ReadString$ (practice using the Generate Layout Wizard the normal way for details)
*mat DimString$ - the string containing Dim statements for each array mentioned in ReadString$. We need this to know how big the arrays are.
*DisplayFile - if True (1), it will Display the new layout in notepad when its done creating it. If false (0), it will simply create the file.

fnGenerateLayout takes all the above information and parses it into a layout, then calls fnWriteLayout to actually write the layout.

If you already know the information you want to put in the layout, its more direct to call fnWriteLayout below.

''fnWriteLayout(Name$,FileName$*127,VER,PRE$,MAT KFNAME$,MAT KDESCRIPTION$,MAT SUBS$,MAT DESCR$,MAT FORM$;RECL,MAT EXTRA$,DISPLAYFILE)''

*Name$ - the name of the new layout
*FileName$*127 - the name of the data file
*Ver - the version of the data file
*Pre$ - the prefix to use for the data file
*mat KfName$ - array of all the keys for the file
*mat Kdescription$ - array of the subscripts that each key is based on
*mat Subs$ - the subscript for each field in the file
*mat Descr$ - the descriptions for each field in the file
*mat Form$ - the form specs for each field in the file
*Recl - (optional) the record length of the file
*mat Extra$ - (optional) Additonal Information for each field in the file, placed in the Comments column of the new layout. This column is ignored by standard fileio processing.
DisplayFile - if True, open the file in Notepad after it has been created.

==== fnSubstituteStringCode ====
A Large Text Field that is searched. Code is run and any resulting variables are set, if they exist inside String enclosed between Substitute Chars (default []), then they will be replaced with the values derived by the code.

''fnSubstituteStringCode(&String$,Code$*2048;SubstituteChar$)''

*String$ - the string to be searched
*Code$ - code to be run. The resulting variables can be substituted into String
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnSubstituteString ====
A Large Text Field that is searched. Any matching fields in the passed in record will be substituted into their places. For example, if the string contained [cu_name] and you ran substitutions on the Customer file, then [cu_name] would be replaced by the name in the actual Customer record.

''fnSubstituteString(&String$,Filelayout$,mat F$,mat F;SubstituteChar$)''

*String$ - the string to be searched
*FileLayout$ - the layout to be searched
*mat F$ - the record to be used for substitution
*mat F - the record to be used for substitution
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnShowMessage ====
Displays a message to the user, in a child window. Returns the child window number, so that you can close it when you're done with the message.

''WindowNumber=fnShowMessage(Message$*54)''

*Message - the Message to display to the user

=== File System Utility Functions ===
These functions perform other tasks that aid with interacting with the file system.

==== fnGetFileDateTime$ ====
This does a directory listing to determine the Last Modified Date and Time of the given file. You pass it a file name, not a file layout, and it can be used on any file. Its not limited to BR internal files.

The syntax is:

''let FileDate$=fnGetFileDateTime$(Filename$*255)''

==== fnProgressBar ====
There's a Progress Bar that FileIO uses when copying or updating data files. You can use it in your own functions by calling fnProgressBar inside the main loop of the process that you want to display the progress bar over, and by calling fnCloseBar when you're done.

''fnProgressBar(Percent;Color$,ProgressAfter,ProgressThreshhold,UpdateThreshhold,Caption$*255,MessageRow$*255)''

*Percent - Percentage Complete expressed as a float between 0 and 1
*Color$ - HTML Color Code of BR Color Attribute to color the Progress Bar. Defaults to Green.
*ProgressAfter - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*ProgressThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*UpdateThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*Caption$ - Optional message to display above the progress bar.
*MessageRow$ - Optional message to display on the progress bar.

==== fnCloseBar ====

''fnCloseBar''

Call this function to close the progress bar window when your task is done running.

==== fnCopyFile ====

''fnCopyFile(FromFile$*255,ToFile$*255)''

*FromFile$ - The file to copy.
*ToFile$ - The destination file name including path.

This function copies any file, by opening it as an external file and reading and writing the data to the destination file. The advantage of this technique, over using the BR copy command, is this routine is more reliable when run on client server where you may be transferring large files from one side to the other over the internet.

This fnCopyFile also has a progress bar that displays as the file is transferred, so the user knows your software is busy.

This function works over Client Server. Under Client Server, specify @: at the beginning of your filename, to specify that the file is on the client. If the file is on the server, simply leave the @: off. See the chapter on [[Copy#Client_Server|using BR's copy command under Client Server]] for more details on the "@:".

This function's parameters and syntax are modeled off of the built in BR copy command, and like that one, this should work for local transfers, LAN transfers, or even internet transfers. This function will work better for internet transfers then the built in BR Copy Command, however.

==== fnCopyDataFiles ====

''fnCopyDataFiles(DestinationFolder$*255)''

*DestinationFolder$ - the folder to copy your data files to.

This function reads your file layouts and makes a copy of every data file (and key file) in your system to the destination folder, utilizing fnCopyFile above, for better performance and reliability when running over the internet, as well as a progress bar for each individual file.

It also displays a listview while its copying so you can watch the progress while its transferring your data files.

This can be used for making backups of your BR data, or for transferring the latest data onto a laptop for access to it while you're on the road away from the internet.

==== fnReIndex ====

This function reindexes a single data file

''fnReIndex(DataFile$*255;CallingProgram$*255,IndexNum,Path$*25)''

*Datafile$ - the file layout of the file to index
*CallingProgram$ - used for logging, pass Program$ in here
*IndexNum - The index to rebuild - if not given, rebuilds all indexes
*Path$ - the optional alternate path to use for rebuilding the data file.

==== fnReIndexAllFiles ====

This function reindexes all your data files. It doesn't require any parameters.

''fnReIndexAllFiles''

==== fnUpdateFile ====
This function checks and Updates a data file if it needs to be updated, by opening and then closing the data file.

''fnUpdateFile(FileLayout$)''

*FileLayout$ - The name of the file to update

==== fnRemoveDeletes ====

This function, written by Susan Smith, removes deleted records by copying the file with the -D option.

''fnRemoveDeletes(LayoutName$*255;Path$*255,CallingProgram$*255)''

*LayoutName$ - the file layout
*Path$ - Optional Alternate Path
*CallingPRogram$ - used for logging, pass Program$ in here

=== Layout Interrogation ===
Layout interrogation functions are provided for convenience and to enable future dictionary changes without disrupting any programs that interrogate it.

==== fnMakeSubProc ====
This function obtains the subscript assignments that were assigned by fnOpen according to the file layout. The fnMakeSubProc$ routine obtains the subscript assignments without actually opening the file. This is useful when a file record is passed as arrays into a library function in another program, or when you chained to another program and you need to know how to reach the data in the arrays without actually reopening the file.

''fnMakeSubProc(filelay$;mat Subscripts$)''

*FileLay$ - The name of the file layout from which to read the subscripts.
*mat Subscripts$ - If you give this optional array, fnMakeSubProc passes the subscripts back in this array rather then in the subs.$$$ file. This is much faster and helps avoid sharing conflicts.

When this routine returns, you can set the subscripts in your program by executing every element of the Subscripts$ array in a for/next loop.

If you did not pass in a subscripts array, then the a procedure file named subs.$$$ is created. If you proc that file, the proper subscripts will be set.

==== fnReadLayoutArrays ====
This function reads the fields in a file layout into arrays. You call it like the following

''fnReadLayoutArrays(filelay$,&prefix$;mat SSubs$, mat NSubs$, mat SSpec$, mat NSpec$,mat SDescription$, mat NDescription$,Mat Spos,Mat Npos)''

*filelay$ - the name of the layout to read
*prefix$ - the return value for the prefix for the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

This function call would read the fields from the layout in filelay$, and it would return the prefix to prefix$. The Subs would be returned in mat SSubs$ and mat NSubs$.

The Spec statements are returned in mat SSpec$ and mat NSpec$ and the Descriptions are returned in mat SDescription$ and mat NDescription$. The start positions on disk of each element are returned in mat SPos and mat NPos.

All the arrays are optional. If you don’t pass them the information they are supposed to record is simply not returned.

==== fnReadLayoutHeader ====
This function reads the header for a given file layout.

''fnReadLayoutHeader(Layoutname$*255;&Filename$,Mat Keys$,Mat KeyDescription$)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file

==== fnReadEntireLayout ====
This function reads the entire layout by calling fnReadLayoutHeader and fnReadLayoutArrays.

''fnReadEntireLayout(Layoutname$*255;&Filename$,&Prefix$,Mat Keys$,Mat KeyDescription$,Mat Ssubs$,Mat Nsubs$,Mat Sspec$,Mat Nspec$,Mat Sdescription$,Mat Ndescription$,Mat Spos,Mat Npos)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*prefix$ - the return value for the prefix for the file
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

==== fnReadSubs ====
This function reads the subscripts from a layout into Subs arrays.

''fnReadSubs(Layout$,mat SSubs$,mat NSubs$,&Prefix$)''

*Layout$ - the file layout name
*mat SSubs$ - the String Subscript Names
*mat NSubs$ - the Number Subscript Names
*Prefix$ - the files Prefix

==== fnReadKeyFiles ====
This function reads the list of key files from the layout.

''fnReadKeyFiles(Layout$,mat Keys$)''

*Layout$ - The file layout
*mat Keys$ - output array, the keys are returned here.

==== fnLayoutExtension$ ====

This function returns the layout extension being used.

==== fnReadLayouts ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''FnReadLayouts(mat Dirlist$)''

*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all the file layouts that FileIO can find.

==== fnDirVersionHistoryFiles ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''fnDirVersionHistoryFiles(Layout$,mat DirList$;BypassExtension$)''
*Layout$ - Which layout to look up version history of
*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all previous versions from history of the requested layout.

==== fnReadLayoutPath$ ====
This function doesn't actually interrogate your layouts. Instead, it interrogates your settings and returns the path specified for your layout files. This would usually be "filelay\" but you can change it in [[#fnSettings|fileio.ini.]]

It has no parameters.

''let Path$=fnReadLayoutPath$''

==== fnDoesLayoutExist ====
This function returns true if the given file layout exists. It returns false if the layout does not exist.

''FnDoesLayoutExist(layout$)''

*Layout$ - Layout to test for

==== fnReadForm$ (uncompiled) ====
Sometimes you need to know the original form statement that fileio is using to read your data file, most often when you're debugging your file layout, and you're getting some problem when reading the file. The form statement that fileio normally returns is compiled using CFORM$ to save space in the array, and to make the execution of your read statements faster. You can use this function to return the original form statement for the file.

The syntax is:

''let FormStatement$=fnReadForm$*10000(FileLayout$)''

Remember to dimension FormStatement to something huge! fnReadForm$ can return up to 10,000 characters.

==== fnReadFormAndSubs ====

This function does the same as above but it also reads the subscripts from the file into an array.

''let fnReadFormAndSubs(Layout$,mat Subs$,&ReadForm$,&StringSize,&NumberSize)''

Note that unlike most of our functions, all the above parameters are required.

The layout is the layout you're interrogating. The Array will be populated with the subscripts after the function. The ReadForm$ variable will be filled with the form statement for the file. Remember to dimension it large enough. StringSize and NumberSize will contain the number of string fields and numeric fields in the file.

Mat Subs$ will be returned, strings first, numbers last, matching the form statement that is returned. So Subs$(1) is the first string subscript and Subs$(StringSize+1) is the first Numeric subscript.

==== fnClearLayoutCache ====

fnClearLayoutCash (v2.3+) clears out the cache of layout name and data to get realtime Updates to File Layouts.

=== Other Useful Functions (non-layout related) ===

==== fnAskCombo ====

Opens a window with a combo box and returns the users selection.

''fnAskCombo$*255(mat Description$;Caption$*60,Default$*255)''

*mat Description$ - contains the combo box choices
*Caption$ - contains the optional caption for the window
*Default$ - the text of the item in mat Description$ that you want to be selected by default

==== fnSendEmail ====

This function sends an email and an optional attachment to the email address specified.

''fnSendEmail(Emailaddress$*255,Message$*10000;Subject$*255,Invoicefile$*255)''

*EmailAddress$ - the Destination Email Address
*Message$ - the Message$ to send
*Subject$ - the subject
*InvoiceFile$ - the filename of a file to attach. This is the BR filename (the function automatically converts it to an OS Filename.)

The function returns 1 when the email was sent successfully, or 0 if it wasn't sent successfully.

In order to use this function, you must have the emailcfg file layout in your layouts folder and you must have a copy of SendEmail.exe which is free and can be downloaded from the internet. Both of these files are included with the latest update of fileio.

You also have to configure fileio with the authentication information for your email server.

To configure your email server, simply run FileIO to get the data crawler, then select the emailcfg file layout and press F5 to edit it. Add a row if the file is empty.

Simply fill in the information the file is asking for in the appropriate fields and save the data, and then test sending an email to make sure it worked.

More information about sendEmail.exe is available from the author's product site here: [http://caspian.dotconf.net/menu/Software/SendEmail/ http://caspian.dotconf.net/menu/Software/SendEmail/]

==== fnClientEnv$ ====

This function returns the value of a Windows Environment Variable on the client under Client Server.

''fnClientEnv$*255(EnvKey$)''

*EnvKey$ is the name of the Windows Environment Variable to check on the client.

The function returns the value of the entered environment variable.

==== fnClientServer ====

This function returns true if you're currently running in Client Server mode, and false if you're running in the old "native" mode.

==== fnEmpty & fnEmptyS ====
These functions test if the passed in array is empty or not..

The syntax is:

''fnEmpty(mat Numeric)''

or

''fnEmptyS(mat String$)''

Example:

def fnSomeFunction(String$,mat Array$; mat OtherArray)
if fnEmpty(mat OtherArray) then
! Arrays were empty.
end if
fnend

==== fnReadScreenSize ====
This function reads the screen size of the given window (or window 0 if a window wasn't passed.) This is useful for centering a window on the screen, or for making sure window 0 is big enough for the child window you're trying to create.

The syntax is:

''fnReadScreenSize(&Rows,&Cols;Window)''

*Rows & Cols - returns the screen size in rows and columns.
*Window - the window to interrogate. If not given, assumes [[Open_Window#Comments_and_Examples|Window 0]].

==== fnBuildProcFile ====
This function builds a proc file to be executed later. This function and the next simplify the process of executing code in a proc file. It can even be used to spawn a new session of BR.

To use it, call fnBuildProcFile one or more times and specify some lines of code to execute.

''fnBuildProcFile(Command$*255)''

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnRunProcFile ====

This function spawns a new copy of BR and in it, runs the proc file that you've previously built using fnBuildProcFile (above).

'' fnRunProcFile(;NoWait) ''

The optional parameter "NoWait" causes the other session to spawn and run in a new thread. If you don't specify NoWait, the current session pauses and waits for the other session to close before proceeding.

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnLog & fnErrLog ====
These next two functions are functions to aid in logging. When you call either of these two functions, you give them a string that you wish to log. They will open the FileIO Log File and add a record to the end of it containing some user information such as login_name and session$, and the string that you specified. FnErrLog does the same thing as fnLog except it also logs the Error Number and the Line.

The syntax is:

''FnLog(string$)''

*String$ - the Log Message

''FnErrLog(String$)''

*String$ - the Log Message

==== fnLogArray ====

This function logs the given arrays to the log file, logging each field in the arrays. Its useful for recording, for example, an entire data record that is about to be written to a data file.

The syntax is:
''fnLogarray(mat F$,mat f;Message$*512,CallingProgram$*255)''
The first two parameters, of course, are the array to log. The third parameter is an optional message to be recorded along with the array, and the fourth optional parameter is the CallingProgram$ to save in the log along with the message. (The CallingProgram$ parameter can usually be passed as the system function Program$)

==== fnSetLogChanges ====
This function works in conjunction with the next function, and they're for recording just what changed in a data file. When the file is read, you call fnSetLogChanges and record the "before" picture of the file record.

After changes have been made and saved back to disk, you can call fnLogChanges below to record the actual changes.

The syntax is:
''fnSetLogChanges(mat F$,mat F)''

==== fnLogChanges ====
This function is the other half of the function above. It compares the given arrays with the ones set previously in the above function and checks for changes. Then it generates a log message recording information about just the items that changed.

The syntax is:
''fnLogChanges(mat F$,mat F;Message$*1024,CallingProgram$*255,Layout$)''

You need to pass in the same two arrays as before, but this time the modified versions of them.

You can also optionally pass a 1024 byte log message to record with the log entry.

CallingProgram$ again should be passed as the system internal function Program$.

The final parameter allows the passing of a Layout$. If you pass a Layout$, that layout is read and the subscripts are used when making the log message of changes, so that its easier to read. If you pass a layout, it will identify the changed fields by name. If you don't it will identify those fields by relative position number.

==== fnViewLogFile ====
All of the above functions store the information by default into a BR internal file defined in the filelay\logfile layout.

The fnViewLog function uses fnShowData to call the Data Crawler to display the FileIO Log File in a searchable listview.

''fnViewLogFile(;ShowQuit,ShowColumns,ShowExport)''

*ShowQuit - Show a quit button on the UI (if off, ESC will quit).
*ShowColumns - Include a button to allow the user to select which columns to view.
*ShowExport - Include a button to export the log file to CSV.

==== fnReadLockedUsers ====

This function returns a list of all users using the locked data file.

''fnReadLockedUsers(mat Users$)''

*mat Users$ - the list of users is returned here

==== fnDisplayLength ====
This function calculates the display length of a field based on its form spec.

''fnDisplayLength(Spec$)''

*Spec - the Form Spec to return the display length of.

==== fnLength ====
This function calculates the length on disk of a field based on its form spec.

''fnLength(Spec$)''

*Spec$ - the Form Spec to return the length of.

==== fnStandardTime$ ====
Converts Military Time to Standard Time. Returns Standard Time$

''fnStandardTime$(MilitaryTime$;Seconds)''

*MilitaryTime$ - Time in 24 hr format.

==== fnMilitaryTime$ ====
''fnMilitaryTime$(StandardTime$;Seconds)''

*StandardTime$ - Time in AM/PM Format

==== fnCalculateHours ====
Calculates the difference between 2 specified times.

''fnCalculateHours(TimeIn$,TOut$,DaysIN,DaysOut)''

*TimeIn$ - From Time
*TimeOut$ - To Time
*DaysIn - Days Start
*DaysOut - Days End

==== fnBuildTime$ ====
Builds a time in the format used by the above functions.

''fnBuildTime$(H,M,S,P;Military,Seconds)''

*H - Hours
*M - Minutes
*S - Seconds
*P - Boolean indicating AM/PM - 0 is AM, 1 is PM
*Military - Flag indicating weather desired result is in Military Time or not
*Seconds - Flag indicating weather to count seconds or ignore them. (1 means count seconds)

==== fnParseTime ====
Takes a time and pulls out the values

''fnParseTime(T$,&H,&M,&S,&P)''

*T$ - the time to parse
*H - Return value for Hours
*M - Return value for Minutes
*S - Return value for Seconds
*P - Return Value for AM/PM

== FileIO fnSettings (Global Settings Code) ==

The FileIO library can be made to implement certain policies across the board. These are established by creating a file called fileio.ini and typing statements like the following into it. This file is "PROCed", so you don't want to put line numbers in it.

Anything you don't specify in fileio.ini will take its default value, shown below. So you only need to specify the items that you want to be different.

Note, for the boolean settings below, 1 denotes TRUE and 0 denotes FALSE.

let EnforceDupkeys=1 ! Enforce that key number 1 is unique key
let Defaultfilelayoutpath$="filelay\" ! Path To Your File Layouts
let Promptonfilecreate=1 ! Ask User Before Creating New Files
let Createlogfile=0 ! Use Logging
let StartFileNumber=1 ! Set above 300 to avoid conflicts with legacy programs.
let CheckIndex=0 ! Automatically Verify Indexes (slow)
let CompressColumns=0 ! Shrink or Expand Columns in Data Crawler by Default
let MaxColWidth=20 ! Max Default Column Width in Data Crawler
let LogLibrary$="" ! Defaut Log Library, defaults to None
let LogLayout$="" ! Log file layout, defaults to Internal File
let AnimateDatacrawler=1 ! Use ScreenIO Animation for Datacrawler
let TemplatePath$="filelay\template\" ! Default Template Path
let IgnoreLayouts$="" ! List any Ignore Layouts here.
let CloseFileSimple=0 ! Use simple comparison for fnCloseFile

==== EnforceDupkeys ====

Turn on the EnforceDupkeys option to force that the first key listed in your file layouts is a unique key. FileIO will generate the standard BR error for Dupkeys when attempting to create indexes if it is not unique.

==== DefaultFileLayoutPath$ ====

Use the DefaultFileLayoutPath option to specify the path from your programs to your file layout folder. The default is "filelay\". Use this setting if you want to place your file layouts in another folder from the default.

==== PromptOnFileCreate ====

Use the PromptOnFileCreate setting to cause FileIO to display a message box whenever it is attempting to create a new file. This happens during the automatic update procedure, as well as during any attempt to access a file that does not exist. This setting should be turned off in your live system, and only turned on for development purposes. If you use the message box to cancel creating of the new file, then the file is not created, and fileIO or your application will most likely give an error when you attempt to actually access the new file.

It can be useful during development to make sure that you don't accidentally create the wrong files, due to an incorrectly specified path or a typeo in the filename in the layout file. However, in a live system, these things have already been tested, and you generally want the default behavior, because you don't want your users to have the ability to cancel the normal operation of FileIO.

==== CreateLogFile ====

Use this option to specify weather or not to use the FileIO log file. If it is turned on, a log file called FileIO.log in the current directory is created with entries listing all attempts to open a file, automatically update one, or automatically update your indexes.

==== StartFileNumber ====

Use this option to set the starting file number that the fnGetFileNumber and the fnOpen functions use to search for available file numbers. This is so that if you have certian reserved file numbers in your code, you can make sure that FileIO will not use those reserved file numbers, causing a conflict with your already existing programs. The default is 1, which is fine if your software does not have any reserved file numbers.

The allowable BR file numbers are 1-200 and 300-999.

==== CheckIndex ====

This function is used for Partial FileIO Implementations. If all of your software uses FileIO then all of your indexes are kept automatically up to date by the FileIO library and BR's internal file processing systems. However, if some of your programs do not use FileIO, and you use the FileIO library to add a new index file that those other programs do not know about, then its possible for the additional index file to become out of date when the master file is updated by your other programs.

Use this setting to cause FileIO to check the DateTime stamp on all your index files when opening a new file, and automatically update any indexes that may have potentially gotten out of date from other programs.

This option slows down the processing of the fnOpen function, particularly when running under client server over the internet. If you know that every program in your application suite uses FileIO, and that any programs that do not use FileIO still properly update all the indexes that your data file uses, then you can safely leave this setting turned off, and optimize your performance when opening several files using the fileIO system.

==== CompressColumns ====
This instructs the datacrawler to use smaller widths for small columns. If CompressColumns is false, the data crawler will make the column the width of the field or the width of the caption, whichever is wider. If CompressColumns is true, it will use the width of the field, not the caption.

==== MaxColWidth ====
This limits the column width to a set amount. This is applied after CompressColumns above.

==== LogLibrary$ ====
If a library is specified here, then fileio looks for a BR library with the specified name, and attempts to call a library function in it called fnFileIOLog that. This function should expect six parameters, which are Logstring$, Login_Name$, Session$, Days of Date$, Time$, and CallingProgram$, if LogLayout is also nonblank.

If you specify a LogLibrary and LogLayout is blank, then it calls your function giving it only 1 parameter.

It will call your function '''''instead of''''' the normal log file. Use this to implement your own logging functions however you want.

==== LogLayout$ ====
Use this setting to specify an alternate file layout for an alternate file to do the logging in. Base the file layout for this file on the logfile we supply for you in the filelay folder. It should have at least those fields, which our log routine will automatically populate, but you can add other fields if you want (though you will need to manage them yourself).

If you don't specify LogLayout, the default filelay\logfile will be used. This will allow you to also use the fnViewLogFile function to access it.

==== AnimateDataCrawler ====
The sister library [[ScreenIO]] has a feature that allows you to use an animation of a clock in your loading screens in your own programs. If you have [[ScreenIO]] then FileIO will automatically detect it and use it to display a loading animation while the data in the data crawler loads.

Set AnimateDataCrawler to false (0) in your fileio.ini file to bypass the animations if you do have screenio but don't want to see the animations anyway.

==== TemplatePath$ ====
This setting points to the folder that contains the code templates used by the Generate Code button on the main page of the Data Crawler.

==== IgnoreLayouts$ ====
This is a comma delimited list of all layouts that you wish to suppress from appearing on the main page of the data crawler. You can still access these layouts with your code, but they won't be listed in the data crawler for you to access.

Whatever you're using for a log layout, is automatically added to this list.
==== CloseFileSimple ====
The fnCloseFile function closes all the individual handles to a data file that was opened for output using multiple keys.

For BR 4.18 and higher, we support a better algorithm for detecting which files are matches for a given opened file number.

Set CloseFileSimple to true (1) to force it to check the old way.

== FileIO Add-on Packages ==

Many FileIO Add-on packages are currently in the works.

=== ScreenIO Library ===

The [[ScreenIO Library]] is a sister library to the FileIO library. The ScreenIO library requires the FileIO library in order to run.

The ScreenIO library is a complete Rapid Application Design tool that enables you to implement custom screen functions anywhere in your exiting programs.

If you call the ScreenIO Library as a function library, you call a function called fnFM and tell it which screen you wish to use. The ScreenIO library loads your user interface, loads your data files, and preforms all the file maintenance operations you have designed into your screens.

You can find out the latest information about the ScreenIO library in the ScreenIO page.

=== Audit BR ===

The [[AuditBR|Audit BR]] developer tool makes a backup copy of your file layouts. Then you run some code you're trying to test, and finally, run Audit BR again, to get a report showing all the changes to any of your data files automatically.

AuditBR is now included directly in FileIO. To use it, select the layout from the list of layouts in the Datacrawler and press the "Compare" button.

== What’s New (also described above) ==
=== 2018 ===
*Support for dates in any storage formats on disk (v2.48)

=== 2015 ===
*Added Rec to display for fnShowData
*Added FormStatement$ for debugging of form statements inside fileio
*Added mat BadRead$ for debugging of 726 errors when making new layouts
*Fixed a bug causing crash when logging things from long program folders
*fnClientEnv$ - reads a Windows Environment variable on the client using the command shell
*fnAskCombo$ - added an optional parameter to set default selection.

=== 2010 - 2014 ===
*FileIO now caches your file layouts in memory to make it much faster then before when opening the same data file in multiple programs.
*Generate Layout Wizard
*fnShowData
*Improved Logging
*fnViewLogFile
*Import/Export
*Import/Export by Function
*Many other speed increases
*if ScreenIO is present, Datacrawler uses the animation routines
*fnBuildProcFile & fnRunProcFile
*fnGenerateLayout & fnWriteLayout
*fnReadForm$
*fnReadFormAndSubs
*fnGetFileDateTime$
*fnReadLayoutPath$
*fnSortKeys
*fnSetLogChanges
*fnLogChanges
*fnLogArray
*fnReadScreenSize
*fnEmpty
*fnEmptyS
*Many other useful functions that were added to the documentation at earlier dates.

=== Spring 2009 ===

'''''New Functions:'''''

The FileIO Library has been updated in Spring 2009 to provide several new functions:

*fnReadRecordWhere
*fnKey$
*fnBuildKey$
*fnReadUnopenedDescription$
*fnUpdateFile
*fnDisplayLength
*fnLength
*fnReadLayoutHeader
*fnReadEntireLayout

'''''Speed Increases:'''''

Thanks to the BR [[Profiler]], we have increased the speed of FileIO fnOpen function by ten times when running over a LAN and by 100 times when running over the internet using Client Server.

In order to get the new Speed Upgrades, you will need to make sure that you use the latest copy of the [[#fnOpen_Function|fnOpen]] function in each one of your programs that use FileIO.

'''''Network FileIO:'''''
This version of FileIO has been optimized to work better in network situations.

'''''FnSettings: '''''
There are more configuration options in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine.

'''''Automatic Update Speed Fix:'''''
The automatic update proceedure has been made to run more then 100 times faster then before according to our benchmarking tests.

=== Fall 2008 ===
'''''DataCrawler Grid:'''''

By popular request we added a read/write version to the data crawler. This version works exactly the same as the datacrawler did before but it displays all the contents of your data files in a grid instead of a listview.

When you run the fileIO library as a program, it launches a tool known as the [[#DataCrawler|DataCrawler]]. The DataCrawler shows a listview displaying all your layout files in it. If you select one, it builds another listview with all the data in your selected data file.

If you are looking at the first list of all your file layouts, and you press F5, a grid will be build displaying all the data in your data files. You can change any of the records you like, and when you're done, your changes will be saved to the data file. Additionally, you can Add or Delete records using the buttons at the bottom. Any changes you make are not written to the disk until you click the "Save" button. If you press ESC (Cancel) the grid is closed and all changes you made sinse the last save are lost.

This tool is for programmers only. Do not give your end users access to the DataCrawler.

Use the DataCrawler at your own risk. Gabriel Bakker and Sage AX are not responsible for any harm that comes to your data files through the use of this or any other tools we offer.

The DataCrawler is not designed to be used to maintain your data files. It can be used carefully to correct small things in your data files.

'''''Support for Nonstandard Paths:'''''

Many BR Vendors keep different versions of the same data files in different locations. For example, sometimes a BR vendor will use a different Data folder to represent data for different Warehouses, or Customers. In cases like this it is necessary for your programs to specify the path to your data files. They may do so by specifying the optional "PATH" parameter to your data files. See the section [[#fnOpenFile]] for more information.

'''''Support for Nonstandard Layout Files Path:'''''

Old versions of the fileIO library required you to place all your file layouts in a subfolder of your program directory called "filelay". We have now changed the Fileio library to allow you to place your file layouts any place you want. The only requirement is that they are all together in one folder by themselves.

If you use a nonstandard path in the fileIO library, it is necessary to make a change to the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code in your copy of fileio.br.

'''''Prompt on Create:'''''

The FileIO library automatically creates any data files that it can't find. This was done to make it easier to deploy your finished programs - if you had any empty data files you could omit them from the packages and they would be created when they were needed, on the fly.

The current version of the FileIO library contains the same ability. However, it prompts you before creating any data files. This helps to avoid bugs that happen from incorrectly specifying the path to your data files.

However, if you do intend for your data files to be autocreated, then you probably don't want your end users to modify them. Therefore, you can use the PromptOnCreate setting in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code to specify. If this value is set to true, then the fileIO library will prompt you whenever it attempts to Autocreate a data file. If it is set to false, then the fileIO library will create the data files without prompting you, like it always did before.

'''''fnSettings:'''''

The newest version of the FileIO library supports some features that require you to specify Global Settings values. These are done by modifying the contents of the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine at the beginning of the fileIO library.

=== Fall 2006 ===
Many improvements have been made in the FileIO library over the summer. This section is intended to acquaint you with the highlights of those changes. Most of these improvements were built from ideas generated during the discussion at the April conference.

'''''Intermixed String and Numeric Specs:'''''
The File Library has been expanded to allow the reading of data files that contain mixed string and numeric specs. This is to aid those of you who are planning on implementing the FileIO Library on existing data files which may not be organized with strings first and numbers second.

The central idea of the FileIO Library is based upon the reading of your data files into a String and Numeric array. This will enable you to refer to the fields in your file by using a named subscript, saying F$(FM_NAME) to refer, for example, to the farm file’s name field. The advantage to this is that when you change the file layout, all your existing programs will not have to be modified, because they will only be looking at F$(FM_NAME). If the name field changes from the third string field to the fourth, the value of FM_NAME will also change, and you won’t have to worry about updating your data files.

However, in order to support the reading of a data file with intermixed string and numeric specs, the generated form statement will actually calculate the position of any fields that are not in order, so that the file read statement will still return all string fields first (into your string array) and the numeric fields second (into your numeric array). You do not need to worry about this; the library does it for you. All you have to do is read your file and use the data values.

The only thing that is required is making sure that all your string subscript names end with a “$”. This will tell the library that they are strings. Thank you, George, for this suggestion.

'''''Versioning / Automatic Updates:'''''
The file layouts have been expanded to contain a version number. This version number will be used to determine when a file needs to be updated. The version number is the third parameter in the file layout.

Any time you wish to change your file layouts, simply increment this version number. Each time the library attempts to open a data file, the file’s version is checked and compared with the version in the file layout. If the file layout has been changed (if the version in the file layout is greater then the version in the file) then the file will be updated to the latest version. Depending on the file size this may take a couple of moments. A simple progress bar will be displayed on screen while this is happening. The progress bar will be displayed in its own window, so it should not affect anything your programs may have had on screen.

The library uses the following procedure for updating a file. First, the file is copied to a backup file (prefixed by the letter ‘o’ for old). So color.dat would become ocolor.dat, and color.key would become ocolor.key. Then the new file is created and marked with the proper version number. (color.dat, color.key). The old file is opened in read-only mode, and the new file is opened for OutIn. The update routine actually reads through the old file layout, and one record at a time creates a new record, using the new file layout, with the same data, saving it to the new data file.

When it is done upgrading, the progress bar window is closed, and the file is reopened in the fashion you described in your call to fnOpen, and flow returns to your program as though nothing unusual has happened.

If an error occurs during processing, the routine will do what it can to roll your data files back to the previous version, but please make frequent backups of your data files anyway, just to be safe.

'''''Error Checking – If there is a mistake in the file layout:'''''
The routine attempts to discover the cause of the error in the case that one is encountered due to a missing file, a file sharing violation, or an invalid or corrupt file layout. If this should happen, the program is paused, and a text message is printed out explaining the most likely source for the error, including what part of the file layout, if any, may have caused the error.

You may then examine the printed text, and the contents of the BR system variables ERR and LINE to determine the problem. If you type “GO”, the next line will be execute “system”, ending your program.

If the file was in the middle of an upgrade when the error happened, it will be automatically rolled back to the previous version, so that when you fix the problem and try to run your program again, the file will again attempt to update from the beginning, and you won’t have to worry about corrupted data.

However, please backup your data before upgrading your data files anyway, just to be safe.

'''''Implementation of Keys / Creation of New Data Files:'''''
The library has been expanded to automatically create all new data files, and to automatically update any existing files. This means that in the file layout header, two new fields that were previously ignored are no longer ignored. The RECL value that you specify in your file layout will be used, along with the description/definition of your keys file. When you open a new file (or update an existing one), the library will calculate the proper kps and kln by evaluating the key description. This key description must match up with subscript values from the data elements in your file, and more then one may be specified, but they must be separated with slashes (/). If I wanted my Farm File to be keyed based on CODE and NAME, the proper key description would be:

farm.key, CODE/NAME

The library will then look up the position and length on disk of the CODE and NAME fields and put them together to create the proper keys during an update or creation of a new file.

'''''DataCrawler:'''''
Perhaps the most exciting new addition to the library is the addition of a programming tool I like to call a DataCrawler. If you run the FileIO Library directly as a program, instead of using it as a library, it will function as a DataCrawler. The DataCrawler requires a New Gui version of BR, as it requires a ListView to be able to properly and easily display the data in your files.

If you run it in an older version of BR you will get a message, telling you to run it in a newer copy. If you run it in a New Gui version of BR with CONFIG GUI OFF, then GUI will be turned temporarily on for the use of the DataCrawler and then turned off again when you are finished. If you run it in a New Gui version of BR with GUI ON, it will just run normally.

When you run the DataCrawler, first you will see a ListView displaying every file layout it can find in the filelay folder. If you select a file, the DataCrawler will open a large ListView with as many columns as there are fields in the file. The Column Headings will come from the element descriptions in your data files, and the column widths will come from the displayed width of the fields. There will be a row for every record in your data file, and you can resize the column widths, and scroll around the data file to view the raw data of your BR data files on disk.

If you are dealing with a particularly enormous data file (50,000+ records) it can take a moment to populate the ListView with the data in your data file. You may hit ESC to stop loading if you like, and view only the already loaded records.

If you would like to look up a particular record (based only upon the primary key for the data file), you may press F4. This will give you a window which asks you to input the key or partial key. When you press enter, the file will be reloaded, starting at the key you specified and continuing on to the end of the file, or until you press ESC. The records you are looking for should appear at the top of the ListView.

To reset the ListView and look at the contents of the entire file again, simply press F4, and enter a blank (“”) key.

Finally, as with any ListView, you may resort your data by clicking on any of the column headings. Then you can use the slider bar at the right to scroll down to the record you desire.

This is a programming tool and is not designed to be used by an end user. This tool will open your file in read-only mode. It will not allow you to modify the data; I leave that as an exercise for the reader. However, it will update any datafiles you view to the latest version (if they need to be updated) when it opens them, just as any other program that uses the library will do.

== Appendix (Examples)==

=== Example.br ===
00010 ! example.br - This program is an example of for the data reading simplification
00020 ! Copyright April 2006 by Gabriel Bakker
00030 ! Distributed open source as a Christmas gift to brag members
00040 !
00100 execute "config gui off"
01020 DIM form$(1)*255
01030 DIM color$(1)*255,color(1)
01040 DIM colorcat$(1)*255,colorcat(1)
02020 library "fileio": fnopenfile, fnreaddescription$
04000 !
04010 Openfiles: ! Open your files here
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)
06000 ! gosub WriteFiles ! If you want to test this line, make sure to drop flag from 4030
07000 !
07010 MainBit: ! This'un here's tha Main Bit
07030 RESTORE #ColorFile:
07100 ReadNextcolor: ! Read next record
07120 read #ColorFile, using form$(ColorFile) : mat Color$, mat Color eof EndReadColor
07180 PRINT Color$(co_name)&" ("&Color$(co_html)&") is a member of the '";
07190 PRINT trim$(fnReadDescription$(ColorcatFile,cc_Name,Color$(co_category),mat Colorcat$,mat Colorcat,mat form$))&"' category."
07290 goto ReadNextColor
07300 EndReadcolor: ! Finished with Color File
08000 STOP
25000 !
25010 WriteFiles: ! Uncalled routine to demonstrate writing files
25105 let color$(co_code)="GD" !:
let color$(co_Name)="Gold" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFD700"
25110 write #colorfile, using form$(colorfile): mat color$, mat color
25115 let color$(co_code)="LV" !:
let color$(co_Name)="Lavender" !:
let color$(co_Category)="BL" !:
let color$(co_html)="E6E6FA"
25120 write #colorfile, using form$(colorfile): mat color$, mat color
25125 let color$(co_Code)="OR" !:
let color$(co_Name)="Orange" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFA500"
25130 write #colorfile, using form$(colorfile): mat color$, mat color
25205 let colorcat$(cc_Code)="YL" !:
let colorcat$(cc_Name)="Yellows" !:
let colorcat$(cc_html)="FFFF00"
25210 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25215 let colorcat$(cc_Code)="BL" !:
let colorcat$(cc_Name)="Blues" !:
let colorcat$(cc_html)="0000FF"
25220 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25300 return
40000 !
40010 Open: ! ***** Function to call library openfile and proc subs
40020 def fnOpen(FILENAME$, MAT F$, MAT F, MAT FORM$;INPUTONLY,KEYNUM,___,INDEX)
40025 dim _FileIOSubs$(1)*50
40030 let fnopen=fnopenfile(FILENAME$, MAT F$, MAT F, MAT FORM$,INPUTONLY,KEYNUM,MAT _FileIOSubs$)
40040 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
40090 fnend
50000 !
60000 Ignore: Continue

Color File Layout
color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

ColorCat File Layout
colorcat.dat, CC_, 0
colorcat.key, CODE
recl=127
===================================================
CODE$, Category Code, C 6
NAME$, English Name for Color, V 30
HTML$, HTML Code for the Color, C 6

Example Layout showing multiple keys (price)
price.dat, PR_, 0
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2

[[Category:Utilities_Third_Party]]

FileIO Library

2024-09-11T14:36:29Z

Gordon.dye:

The '''FileIO''' Library began as a project to find a way to reduce the effort associated with making changes to data file layouts. Thanks to the Fileio library, when I have to make a change to a data file layout for my customers today, I can complete the task in under 1 minute, and not a single program needs to be changed in order to continue working with the new file layout. In fact, I don’t even have to update my customer’s data files, as the FileIO library takes care of this for me as well.

The trick is to define each of your file layouts in an ASCII text file layout file that is described below. The FileIO Library will parse through your file layouts, and it will instruct your programs how to access the file data after it has been read. It will also automatically detect when you make changes to the file layout, and it will update your customer’s data files on the fly to make sure they have the latest version. Finally, it contains a DataCrawler that you can use to examine the contents of any of your BR data files in a raw format.

For more information about the FileIO Library visit the [http://www.sageax.com/products/fileio-library/ Sage AX Website]

To download the latest copy of FileIO, click [http://www.sageax.com/downloads/FileIO.zip here.]

== Method of Operation ==
The file IO library parses a formatted text file layout and uses this information to structure the opening and the reading of a file “object”. The word object here is used to refer to all the data in a given record layout in one of your files. This library is easy to use, and provided you follow some simple standards, it will simplify your life immensely.

Your programs will need to define one array for all [[Form|BR data file form statements]] and add a snippet of code (given below) to the program for interfacing with with the library. For each file you will need to define a couple of arrays and use the library to open them. From that point on access to data is simple and direct.

=== File Object Arrays ===

First, in your program you must create two arrays to store the file information. If we are dealing with the Color File these would be MAT COLOR$ and MAT COLOR. One will store all the string information about a color, and the other will store the related numeric data. Our working example will involve two files: a Color File and a Color Category File. You should dimension these as follows:

01030 DIM color$(1)*1000,color(1)
01040 DIM colorcat$(1)*1000,colorcat(1)

We're dimensioning the string array elements to 1000 bytes each. This is the length of one field in the color file. The array element length needs to be at least as big as the largest string field in the data file.

However, it is recommended to make sure the length is long enough to handle any field you might eventually add to the file at any point in the future. BR supports multi-line textboxes, so I sometimes add long memo fields to my data files that might be 400 or 800 or even 1000 characters long, therefore 1000 is the length I use now in all my new development.

But anything will work as long as its long enough to handle the largest data field in your file.

=== Forms Array ===

Your programs will need a string variable array to store the form statements associated with reading files. This form statements array will be dynamically generated or expanded whenever the a file is opened. It will say:

01020 DIM form$(1)*255

This form statement will be compiled by the FileIO open statement. BR limits all compiloed form statements to 255 bytes, so 255 is sufficient to hold the compiled Forms$ statements.

=== Library Linkage ===

You will also need the library statement:

02020 library "fileio.br": fnopenfile, fnreaddescription$

=== fnOpen Function ===

Now, add a snippet of code to interface with the library.

Because BR libraries do not share global variables with the programs they are called from, we will need to execute a procedure file whenever we open a file - to set the names of all of our variables. Add the following snippet of code into your program. It will create an FnOpen function that calls the library and runs the proc file. The $$$ at the end of the procfile name tells the procfile to self-destruct after execution. Since this procfile is used simply to return variable information back from the library to the main program, we don’t need it sitting around collecting dust.

99010 OPEN: ! ***** Function To Call Library Openfile And Proc Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
99030 dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
99050 if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
99060 fnend

Or, for those with [[Lexi]]:
OPEN: ! ***** Function To Call Library Openfile And Proc Subs
def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
fnend

=== Using FileIO in Your Programs ===
Now you are ready to process files. 
'''''You simply open the files by saying:'''''

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

'''''read each file as follows:'''''

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
'''''and access the data:'''''

30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name)

=== How it Works ===
The above statements tell the File Library to look in the filelay folder to find the file layout for the Color File, and read it to find out what the Color File looks like. Then it OPENs the Color File, and sets MAT COLOR$ and MAT COLOR to the correct number of elements to hold an entire color record. Finally, it will define several variables that we can use as pointers (subscripts) into these arrays to access the data read into the 2 arrays, and it will assign the file handle to a variable called "colorfile".

The second open above will do the same thing to the color category file, except the 1 parameter value tells the function to open readonly. The array subscripts populate procedure (passed back from Fileio) will be executed, thereby assigning values to the subscript names in the calling program. So, if I had a file layout such as the following:

color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

Then the functions would do the same thing as the following individual lines of code (assuming the next available file handle was 5):

DIM FORM$(5)*255
DIM COLOR$(9)*1023, COLOR(1)
OPEN #5: “Name=color.dat, kfname=color.key”,internal,outin,keyed
LET FORM$(5)=”form C 6,V 30,V 6,C 6”
LET FORM$(5)=CFORM$(FORM$(5))
LET COLORFILE=5
CO_CODE=1
CO_NAME=2
CO_CATEGORY=3
CO_HTML=4

The data is used by referencing the file array, with the subscript name, so the color’s description becomes color$(co_Name).

In the old days, if we wanted to change the file layout of our file, all of the programs that used that file would have to be changed one at a time to use the new file layout. Also, if the order of the fields changed, then all the programs would have to also be changed to use the new fields.

But now, using this function, we can change the file layout all we want. If we later want to insert a field into the file layout before color name, I won’t have to look at this program again; this program will just work fine, because the library maps the subscripts to the actual fields.

Also, the code is easier to read and maintain.

=== Example ===
The whole thing looks like this:

01025 ! Dimension the Arrays
01030 DIM color$(1)*1023,color(1)
01040 DIM colorcat$(1)*1023,colorcat(1)
01050 DIM form$(1)*255
02000 !
02020 library "fileio.br": fnopenfile, fnreaddescription$
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$) ! Open the file
05000 !
30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore ! Read the file
30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name) ! Use the data by referincing it in the file arrays
80000 !
90000 ! Every program using fileio needs the following code
99010 OPEN: ! ***** Function To Call Library Openfile And Generate Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths)
99030 dim _FileIOSubs$(1)*800
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$)
99050 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
99060 fnend

== File Layouts ==
Now lets inspect the anatomy of a properly formatted file layout. These should be placed in a subdirectory called filelay.

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...
<hr>
price.dat, PR_, 1

The first line contains the name of the Farm File, a unique string to prefix all of your subscript pointers, and the file version number. The subscript value is to ensure that the program knows the difference between the Farm File’s Farm Code, and the Route File’s Route Code. (One will be RT_CODE and the other is FM_CODE). These are separated by a comma. Spacing does not matter, so adjust your spacing so that it looks nice.

The Version number is used to determine when the data has changed, and an update needs to be made to your data file. Your file layouts should all start at version 0, and each time you want to make a change, you may increment this value by 1.

Each time you open a file with the FILEIO library, it reads the file version number of the file on disk (using the BR version() function), and then it compares it to the version number in your file layout. If your file layout has a higher version number then your existing data file, then the library opens the backup of the file layout for the version of the data file that exists on disk. It makes a backup copy of the existing data file, and creates a new file with the proper version number. Then it reads your records one at a time, and copies all the data from the old file into the new file one field at a time. If a field is dropped from the file layout, that data gets lost. If fields are rearranged, the data is copied and saved in the new file in the new positions. If a new field is added, it starts out blank (or 0).

If you look in the filelay folder, you will notice a version folder. This contains several files ending with a number. For example you may see a color.0, and a color.1 file.

If you run the fnopen function and it can not find your data file (usually because this is a new file and it hasn’t been created yet), ''the library will automatically create your file,'' based on the information you give in the first part of the file layout.

Also, whenever you make changes to your file layout, the function library will automatically update the data files on disk for you. It does this by renaming the old file, creating a new one with the new version number, and then copying the data from the old one to the new one a record at a time.

Any time it creates a file, or updates the file on disk, it creates a backup of the file ''layout''. The first time you run a program that tries to read your new data file, it will create the data file for you and make a backup of the layout, and if the number in your file layout is 0, then it will create, for example, a filelay\version\price.0 file, a backup of your file layout that the library uses to figure out what has changed the next time you try to update the file.

If you wish to make any changes to this data file, first you increment the version number, (in this case make the 0 into a 1). Then change the file layout all you want. You may rearrange fields, add new fields, add or remove keys, or change the record length.

The only step necessary for having your data files updated is to increment the version number every time you make a change to the file layout.

You may make any changes you like to the file layouts, but do not change the names of your existing subscripts. If you change the subscript name, not only will all the programs that reference that subscript be broken, but additionally, the routine will not understand that you are changing the name. It will think you are dropping the old field and adding a new field and any data stored in this location will be lost when the file is updated.

price.key, FARM

The second line contains the name of the first key, and a definition telling what the key is based on. These are separated by a comma. The key definition is made up of each of the subscript names in this file that form the keyfields for the file. When the library is called to open a file, if the file does not exist, or if it needs to be updated, a new one will be created. The function will read these subscript names that form your key definitions, and it will calculate the proper key position (KPS=) and length (KLN=) values. Then the create routine will use this information with the Index command to create the new key files.

price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127

Notice that the third key is based on three different fields. These are separated by a “/”. It is important that you use a “/” to separate your keys when you are building a key out of more then one field, because the function uses this “/” to help it make the proper BR syntax for defining complex key fields.

Also, note the "-U" at the end of the fieldname in the 4th key. This indicates that the "Description" part of that key is case insensitive. This translates to using the "U" on part of your key spec in Business Rules.

The file can have as many keys as you want. The function will keep parsing key file names until it reaches the next part of the layout. It opens any OutIn files with all keys so that any changes you may make to the data stored on disk will be properly reflected in all the key files.

The optional RECL= Parameter is read and used whenever a new file is created or an old one is updated. If it is not specified, the record length is calculated from the fields in the layout.

===================================================

The next line in the file is skipped by the parsing routine, and its purpose is to make the file layouts more readable to a programmer.

 
FARM$, Farm Code (or blank), C 4

Following the file and key structure, the fields are defined. There are three parameters on each field definition line, and you make one line for each field in your file layout. The first parameter is the subscript name that you will use in your program to refer to this data element. Place a $ at the end of the subscript name for all string elements. Don’t place anything at the end of the subscript name for numeric elements. Note that each of these names will be prefixed by the second parameter of the very first line of this layout.

The second parameter is the description. This description is for the benefit of the programmer, so when the programmer is reading the file layouts, (s)he can tell which field does what. The spaces are ignored, so you may include as many spaces as you wish to make the layout look good. It does seem like good general guidelines would be to limit your layout lines to 255 characters and your descriptions to 80.

The description is also used by the built in DataCrawler, a program that reads any of your data files and displays the entire contents in raw form in a listview. The Descriptions become the headings for each column in the listview.

Those descriptions are also used for the default captions for your fields if you use ScreenIO, a library for building GUI programs that itself builds off of fileio.

The third parameter is the form statement, which is pretty straightforward. Any items with a form statement of type “X” will be ignored, except that the length will still be used to calculate the position on disk of all remaining fields in the record. The library will take X fields into consideration when building the form statement, but not at any other time.

The fourth parameter is optionally a [[#Support for Dates|Disk Date Format]]. You can specify DATE(Julian) if you're storing your dates in Julian format on disk. Or you can specify DATE(cymd) or DATE(ymd) or DATE(mdy) or any other valid date spec here, and FileIO will treat this field like a date.

Your programs will still have to unpack it for you, fileio can't do that because fileio doesn't read the file for you.

However, the data crawler, the automatic updates, and screenIO, are all compatible with these dates specified in your file layout.

If the fourth parameter is anything other then DATE(format), then its treated as a comment and ignored.

The fifth and all later columns, if any, are treated as comments and ignored.

! default cost is normally zero
Comment line text must begin with an exclamation point, but it may be indented. Comment lines may appear anywhere (vertically) and are ignored. 
Blank lines are ignored as well.

#eof#
additional comments...
After the last field definition, an ''optional'' #eof# line may be specified, in which case any lines after that will be ignored.

 
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...

And that’s all there is to it.

=== Support for Dates ===
As of V2.48, file layouts support dates in any storage formats on disk. Whether you store your dates in Julian or in YMD or MDY or any other format, specify so in the 4th column of your file layouts, using the FileIO Date Keyword. ex: DATE(Julian) or DATE(YMD) or any other valid BR Date Format.

[[File:Dates0.png]]

When this is specified, it enables the FileIO data exploration tool (Data Crawler) to display the dates in human readable format. This works for both Viewing, and for Editing.

The new Date functionality also supports the File Layout Upgrade facility, allowing you to change the format of your dates on disk and FileIO will handle it automatically, upgrading the field to use the new date format for you.

It works also for Exporting your data files to CSV, and is supported automatically in the FileIO functions that do those exports. It converts the dates on export to a standard format (Default: m/d/cy) that you can specify in your FileIO.Ini File.

And it extends ScreenIO's date features to all date fields, no matter what format they're stored in. (Previously, ScreenIO's advanced date features only worked for dates stored in Julian on disk.)

This update adds two new ini file options:
CODE: SELECT ALL
DateFormatExport$='m/d/cy' ! Format of Dates when Exporting to CSV
DateFormatDisplay$='m/d/cy' ! Format of Dates when displaying in Data Crawler

You can use these to specify your preferred Date format for Viewing/Editing, and your preferred Date format for Exporting.

Remember, you can see the full list of FileIO ini file options, by looking in the source code at the top of FileIO.

There is a new optional parameter for all layout reading functions, mat NDateSpec$ and mat SDateSpec$ which correspond with the other arrays, to let you know which fields are date fields, so that you can develop routines in your programs to automatically pack and unpack the dates.

Important Note: Using FileIO, the reading of the data file is still done directly in your programs. So this does not change how your existing programs work. It does not unpack the dates for you in your programs. You still have to do all that.

For this reason, upgrading to the new Date processing will not break any of your current code.

=== Debugging Tips ===

When you're making new layouts, a missing comma can cause FileIO to parse the layout wrong and give you errors. Here are a couple tips to help ensure your layouts are error free before using them in your programs.

*Use the Data Crawler to test your layout. The data crawler is the simplest way to test your new layout without writing any code. It opens it and accesses the file in a very simple and straight forward manor to help identify any errors in the layout that you might have.

*If you have trouble with the form statement, you can't see whats in it because FileIO uses CForm$ to compile your form statement to make your programs run faster. But here's a way to tell what the original form statement was that FileIO generated when it put the strings first and numbers last in your program: Open the file in the Data Crawler. When you get an error, type "Print FormStatement$" to see the original form statement.

This works even if your file is working fine. Any time the file is opened with the data crawler, you can press CTRL-A and then type PRINT FormStatement$ and it will print out the uncompiled form statement for the file.

== Utilities ==

Now that you have your file layouts defined, you have access to several powerful utilities right out of the box using Fileio. Additionally, several more utilities are available as [[#FileIO_Add-on_Packages|Add-Ons]], including our most popular development tool [[Screenio|ScreenIO]]. You can read more about them in their section below.

But for now, lets take a look at some of the wonderful free utilities that come built into Fileio.

Some of these utilities are accessible from your code via library functions, but the primary way you access any of them is by simply loading the FileIO Library and running it directly.

=== DataCrawler ===
The data crawler is the original utility of FileIO. This utility shows you first a list of all data files allowing you to select one.

Select a data file and press enter, and FileIO will then display a listview containing all the data in the data file. This list is sized based on the size of your main BR window (window 0) automatically to take up the full size available to it, so if you want to see more, try [[Open Window|opening window 0]] larger before running FileIO.

At the top of the window is a filter box, and you can type anything you want in there and click "Refresh" and it will reread the data file, shortening the list to show only those records that match (case insensitive) what you have typed.

If you have ScreenIO installed, then FileIO's data crawler will take advantage of the included Animation Engine in ScreenIO to animate a loading window while the listview is displaying. If you don't have ScreenIO then FileIO will simply load the listview.

If you don't want to wait for the entire file to load, press ESC to stop the load process.

If the file is empty, FileIO will display a message box letting you know.

This tool is very useful for sorting out data errors. It will allow you to look inside any data file you have a layout for and directly view the data there.

At the bottom of the Data Crawler are several buttons. There's a Jump button that repositions the file by a key you specify and then loads the list with the data from that key on down to the end of the file.

There is a "Columns" button which you can use to decide which columns should show up on the listview. Fewer columns means faster loading so sometimes for large files I press ESC immediately when the file first starts loading to cancel the load. Then I click "Columns" and check only the columns I want to see. Finally I press the "Refresh" button to trigger it to read the file again and this time it loads much faster then before.

Next you'll find an Export button which starts the process for exporting a file to CSV. You can read more on that in the next section. And next to that is a Quit button.

In this example, we loaded the file "Read Only" so it put everything in a listview. But there are times when its useful to fix data errors this way too, especially during development. So if you want to directly edit your data file, on the first page select the file you want to edit and instead of pressing "Enter" or clicking "View", this time press "F5". F5 is the secret Edit button that loads a data file into a grid instead.

You can use the grid to change records, delete them or add them, and in addition to the buttons listed above, it also has an "Import" button for importing a CSV file into this data file.

Any changes you make to the data file are not saved until you click the "Save" button (which also only appears when you're in Edit mode).

In the 01/2015 release of FileIO, each records rec # is displayed in the listview, to aid in debugging bad data problems.

==== Debugging Tip ====
Any time you're viewing a file layout in the Data Crawler, you can see the Uncompiled Form Statement by pressing CTRL-A to get to an ATTN prompt, and then entering the command:

print FormStatement$

and it will print out the original form statement.

==== Another Debugging Tip ====

The FileIO Datacrawler ignores records that it cannot read. This is to allow for data files that have multiple record layouts in one data file. You make a custom layout for each record type and the data crawler shows just the records that match that type in the file.

However that becomes a problem when you're making a layout to work with an existing data file. Error 726 indicates that something minor in the file layout doesn't match the data on the disk, but these errors are ignored so you might see either an empty data file, or a data file with some records missing. If that happens, you need to see the missing records in order to figure out what is wrong with your layout. '''''It's very important that you don't try to use a file layout that isn't quite working right. Make sure your layout works and can read every record of a file that it should read before using it.'''''

To see the records that could not be read in a file, run the data crawler on the layout, then press CTRL-A to get an ATTN prompt. From there, enter the command

print mat BadRead$

and it will print all the records that were ignored because the file layout didn't match them. It prints out the raw data from the file.

==== Function Access to use Data Crawler in your programs ====
You can use the data crawler in your own programs by using one of the following functions:
* [[#fnDataCrawler|fnDataCrawler]] - Open a Listview showing the data file
* [[#fnDataEdit|fnDataEdit]] - Display the data in an editable grid
* [[#fnShowData|fnShowData]] - This function does the same thing as the above two, but with many many more options allowing you to customize exactly what appears and exactly what they're allowed to change.

Note: its not recommended to allow your customers to use the data crawler to access your data files directly. There's no way to specify validations or do anything complicated, so unless you're careful, there are lots of ways your customers could use this tool to do damage to your data files. It is a programmer tool only.

If you do decide to use it for your end users, be careful how you implement it.

=== Import/Export to CSV ===

You can use FileIO to export your data files to CSV or import from CSV into your data file. To do this, you want to run the data crawler and select the file layout you're looking for. Then, view it (or press F5 to edit if you want to import something). Click on the Export button and it will ask you to select a file. Once that is selected it will ask a couple other simple questions, and when you've specified the options to your satisfaction, click the Export! button. A new CSV file will be created.

Import is even more simple. To import, you must be in Edit mode (press F5 to select the file instead of the enter key) and then simply select the Import button. It will ask you again to choose the file, and then it will ask you if it should update all files by Record Number (if record number is recorded in the CSV file) or by Key (if the file has keys) or to just Add all information to the file. Select what you want and press Import and the CSV file is added to the BR data file.

==== Function Access to Import/Export from your programs ====

You can use the following functions to call the Import and Export functionality from your code.

*[[#fnCSVImport|fnCSVImport]]
*[[#fnCSVExport|fnCSVExport]]

These functions are intended to give you the ability to use our functionality to write your own import and export routines for your customers, because its not a good idea to let your customers run the Data Crawler.

=== Generate Layout Wizard ===

There is also a Generate Layout Wizard utility in FileIO. This utility is there to help you build your file layouts. It is designed to work with a certain style of BR programming that was common in the 80s and 90s. So if your software is written in a style that opens the file directly, and reads/writes the data to a long series of individual variables, the Generate Layout Wizard is for you.

To use it, start by running FileIO. Then, don't select a layout - instead, click on the "Generate Layout" button.

You'll see a screen with a bunch of large text boxes, a small grid, and some buttons.

The first thing you want to do is select the "Browse" button and then select a .wb or .br file that contains a program that reads or writes Most of the File.

When you select one, press the Scan All button and it fileio will search the whole program looking first for all the open strings. It will take the file that is opened the most times and then search for all read statements to that file. It will look for the longest read statement and then find the Form statement associated with that Read statement, and any DIM statements for any variables used.

If you don't like the file its chosen, click the "Open Scratch Pad" button to open the temp work file it uses into the program of your choice (I use myEdit for BRS files). Simply select all the open statements for the file you DO want to build off of, then click the Paste button to paste those open statements into the "Open String" list. After that click "Clear All" to erase what it did on the first search and then click "Scan All" again to rescan the program using this new data file.

You may have to help it a bit, but once it has a proper matching open statement, read statement, form statement and dim statements for any arrays used, press the "Generate Layout" button and it will build a layout for that file.

Finally, load the layout it built and clean up anything if you want, and consider adding better descriptions for each of the fields that you know (as it will use the variable names for both the subscripts AND descriptions in the layout).

When you're all done, click "Done".

==== Functions to Generate Layouts from your code ====

* [[#fnGenerateLayout_.26_fnWriteLayout|fnGenerateLayout]]
* [[#fnGenerateLayout_.26_fnWriteLayout|fnWriteLayout]]

=== Code Templates ===

One more tool FileIO has to help is the ability to generate code based on your file layouts.

Run FileIO and this time select a file layout and press "Generate Code". A window will pop up listing all the "Code Templates" that are available. Select one (and then select a key if it asks you - some templates require extra info). It looks like nothing happened, but the code you generated is now in your clip board. Paste it somewhere and take a look at it!

Code Templates help us to standardize our ways of doing things, which eventually leads to more and more powerful tools we can use. Code Templates also help ensure we use cleaner code by doing some of the busy-work of writing clean code for us.

==== Writing Code Templates ====
FileIO ships with several basic code templates. If you want to add your own, take a look in the filelay\templates folder (configurable in fileio.ini) and look at basic.brs. Copy it to your own program and then modify it to have your own code templates in it. Write me at gabriel.bakker@gmail.com with any questions. I want to help.

And if you write good code templates, its easy to share them with the BR community. Anyone can download your templates and place them in this folder and they'll instantly be available for use.

== FileIO Function Reference ==
''The FileIO Library contains a number of other useful functions.'' The following functions are available and you are welcome to use them:

=== Primary Functions ===

==== fnOpen ====
fnOpen is the primary function that opens a file, and it’s used like so:

''def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, DontSortSubs, Path$*255, Mat Descr$, Mat FieldWidths, SupressPrompt, IgnoreErrors, SuppressLog)''

Note that all of the parameters after MAT Form$ are optional. If you need to specify a parameter in the middle of the optional parameter group, just list zeroes and empty strings for the intervening unused parameters.

*FileName$ - The filename of the file layout for the file you’re reading.
*MAT F$ - The array that will be used to hold the string data for the file.
*MAT F – The array that will hold the numeric data for the file.
*MAT Form$ - An array of form statements.
*InputOnly – 1 means open for input only. 0 means open for OutIn and open every key file associated with the given data file (this is because all key files need to be open for the keys to be updated on an output) (defaults to 0). Files opened for input process considerably faster than files opened for output. Furthermore when files are opened for input only, alternate key files are ''not'' opened.
*KeyNum – This tells the function of which key to return the file handle (defaults to 1). Specify -1 to force the file to open Relative, without using its keys. If a file has no keys, it will always be opened Relative.
*DontSortSubs – The function by default, when compiling the Form statement, will sort the string and numeric subs in order to allow for reading the data into an array, and this parameter would turn this functionality off. However, if you are trying to read your data without reading it into an array, you are missing out on some serious efficiencies. You should normally leave this option turned off (0). This is a totally unsupported feature, and should always be set to 0, if it is specified at all.
*Path$ - The path to your data files. This optional parameter can be passed in by the calling function. It is prefixed to the beginning of the paths given in the file layout files. It is useful when your data files can be in different locations depending on the state of your program.
*mat Description$ - This optional parameter provides a way to read the description for each field from the original file layout. If the parameter is not provided, no description data will be returned.
*mat Fieldwidths – This optional parameter will return an array of the calculated display field widths. This number will always be at least large enough to contain the data for this field.
*SuppressPrompt - This optional parameter can be used to suppress the prompt normally given when fileIO creates a file. It can have three values. A value of 0, the default, uses the setting stored in your FileIO fnSettings routine to determine weather or not to prompt on Creation of a new file. A nonzero value always suppresses the prompt. A value of 1 indicates never to create a file if the file doesn't exist. A value of 2 automatically creates the file if the file doesn't exist.
*IgnoreErrors - Normally when fileio opens a data file, if there are errors trying to open the file, it prints them out to the debug console and pauses so that you can try to find out whats going wrong. If you specify 1 for "IgnoreErrors" it will cause Fileio to log those errors instead, and continue loading your program. This will result in the fnOpen file function returning Zero instead of the opened file number, so if you use IgnoreErrors, you need to test to make sure that fnOpen returned a file number before you try to access the file.
*SuppressLog - this optional parameter can be used to suppress writing to the log file for this one specific open statement. I use it for files that will be opened all the time, for example, the menu data file on one of my customers systems. Without this boolean parameter, his log file is quickly filled up with useless information any time his employees look at his menu. I specify this optional parameter to suppress logging anything about the menu file so that I can more easily find the actual programs they've used when looking in the logfile.

'''''Note: When using fnOpenFile, you really want to call your local function fnOpen, which in turn calls fnOpenFile for you.''''' FnOpenFile is for internal use only.

Example:

Let FFILE=FNOPEN(“FARM”,MAT FARM$,MAT FARM,MAT FORM$,0,2)
Let RFILE=FNOPEN(“ROUTE”,MAT ROUTE$,MAT ROUTE,MAT FORM$,1,3)
Let CFILE=FNOPEN(“CUSTOMER”,MAT CUSTOMER$,MAT CUSTOMER,MAT FORM$)

assuming:
farm.dat has 3 keys: farm.ky1, farm.ky2, farm.ky3
route.dat has 4 keys: route.ky1 … route.ky4
customer.dat has 2 keys: customer.ky1, customer.ky2

This will perform the following opens and set the following variables:

OPEN #1: “Name=Farm.Dat, kfname=farm.ky2”,internal,outin,keyed
OPEN #2: “Name=Farm.Dat, kfname=farm.ky1”,internal,outin,keyed
OPEN #3: “Name=Farm.Dat, kfname=farm.ky3”,internal,outin,keyed
OPEN #4: “Name=Route.Dat, kfname=route.ky3”,internal,input,keyed
OPEN #5: “Name=Customer.Dat,kfname=customer.ky1”,internal,outin,keyed
OPEN #6: “Name=Customer.Dat,kfname=customer.ky2”,internal,outin,keyed
LET FFILE=1
LET RFILE=4
LET CFILE=5

This will also resize the arrays, set the form statement, and create all the subscripts to make accessing the data clear and simple, as in the above example. The KEYNUM parameter is where you list the key file you would like to use for reading and writing. The extra keys are opened to ensure that all keys get updated properly when the file is changed.

Example:
DIM FORM$(1),PRICE$(1)*255,PRICE(1),
DIM DESCRIPTION$(1)*80,FIELDWIDTHS(1)

Let PRICEFILE=FNOPEN(“PRICE”,MAT PRICE$,MAT PRICE,MAT FORM$,0,2,0,"",MAT DESCRIPTION$)

Assuming the Price File layout (filelay\price) contains:

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30

This will perform the following opens and set the following variables:

OPEN #1: “Name=Price.Dat, kfname=Price.ky2”,internal,outin,keyed
OPEN #2: “Name=Price.Dat, kfname=Price.ky1”,internal,outin,keyed
OPEN #3: “Name=Price.Dat, kfname=Price.ky3”,internal,outin,keyed
let PRICEFILE=1
let PR_FARM=1
let PR_ITEM=2
let PR_GRADE=3
let PR_DESCR=4
let PR_PRICE=1
let PR_COST=2
let PR_XOPRICE=3
let PR_XOCOST=4
let PR_MOPRICE=5
let PR_MOCOST=6
let PR_VOPRICE=7
let PR_VOCOST=8
MAT FORM$(1)
MAT PRICE$(4)
MAT PRICE(8)
MAT DESCRIPTION$(12)
MAT FIELDWIDTHS(12)
let FORM$(1)=CFORM$(”form C 4,C 4,C 4,POS 74,C 30,POS 50,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2”)
let Description$(1)= “Farm Code (or blank)”
let Description$(2) = “Item Code”
let Description$(3) = “Quality”
let Description$(4) = “Description of Price Rule”
let Description$(5) = “Default Price”
let Description$(6) = “Default Cost”
let Description$(7) = “Default Christmas Price”
let Description$(8) = “Default Christmas Cost”
let Description$(9) = “Default Mothers D Price”
let Description$(10) = “Default Mothers D Cost”
let Description$(11) = “Default Valentine Price”
let Description$(12) = “Default Valentine Cost”
let FieldWidths(1) = 4
let FieldWidths(2) = 4
let FieldWidths(3) = 4
let FieldWidths(4) = 30
let FieldWidths(5) = 8
let FieldWidths(6) = 8
let FieldWidths(7) = 8
let FieldWidths(8) = 8
let FieldWidths(9) = 8
let FieldWidths(10) = 8
let FieldWidths(11) = 8
let FieldWidths(12) = 8

There are a few things I’d like to point out about the example above. First, you will notice that the form statement jumps around to put all the strings first, and then the numbers last. This is why it has a “POS 74, C 30,POS 50”. Then notice that the subscripts for the string variables are 1 .. 4, and the subscripts for the numbers are 1 .. 8. Finally, the order of the Description and FieldWidth fields also match the sorted positioning of the Form Statement.

The reason that we sort our form statements is so that BR will allow us to read the file into arrays by saying:

Read #pricefile, using form$(pricefile) : mat price$, mat price

Without resorting, the above statement would give a conversion error as BR attempted to put the PR_PRICE field inside mat price$(4). However, because we have reordered the form statement, we are able to read them safely into two arrays, and then we will be able to use the values without caring what position they are in the file, by simply saying PRICE$(PR_DESCRIPTION) when we want the description, and PRICE(PR_PRICE) when we want the pr_Price field.

Another thing you may notice about the above example is that it gives the calculated display length for the numeric fields as 8, when on the disk (and in the file layout) they are listed as BH 3.2. The reason for this is the program looks at the BH 3, and figures that a number that takes up 3 bytes on disk has a potential maximum size of 256**3 or 16,777,216, and therefore will need up to 8 characters of screen display space to view.

Finally, note that any field with a form statement of X is ignored by the library, except that the blank space is used when building the FORM statement.

==== fnCloseFile ====
This function will close the specified file number and all keys that were opened with the file. The purpose of this function is to facilitate the closing of the extra keys that are opened when you open a file for OutIn with the library. There is no need to use this for files opened for input because it is easier to just close the file directly. Secondary keys are not opened by FileIO for files opened for input only.

You must give the function the name of the file layout. It uses this information to determine how many keys were opened, and how many it must therefore close.

Then it basically starts at the file number you gave it, and closes the next X files that were opened with the same file name as this, where X is the number of keys associated with this file.

The syntax is:

''fnCloseFile(filenumber,filelay$;path$)''

*FileNumber – The filenumber of the file you are trying to close.
*FileLay$ - The name of the file layout for this file. This is used to determine how many keys the file would have been opened with and therefore how many we now need to close.
*Path$ - Optional Alternate Path. Use to close files that were opened using the open file's optional alternate path parameter.

==== fnGetFileNumber ====
FnGetFileNumber is a simple function to find a valid unused file handle. If you use this function in all of your programs, they will become much more portable, as you will never have to worry about your file handles fighting with each other. The function will return 0 if no free file number was found (but with 999 of them available now, I have never seen it happen).

''fnGetFileNumber(;X,Count)''

*X – This optional parameter will specify where to start looking.
*Count - This optional parameter will specify how many file numbers to find in a row. If count is 3, then fnGetFileNumber will return the first filenumber in the first gap of three unused file numbers that it finds.

=== File Reading Helper Functions ===

These functions perform various useful calculations to aid in interacting with data files when you're using fileio.

==== fnBuildKey$ ====
This function will return the key for a given record in a data file. It actually reads the file layout and builds the key to match the layout.

''FnBuildKey$(Layout$, Mat F$, Mat F; Keynum)''

*Layout$ - the name of the data file to build the key for.
*Mat F$ - the string array of the file object
*Mat F - the numeric array of the file object
*KeyNum - This optional parameter specifies which of the key files in the given layout the key should be built for.

To use this, you want some code like in the following example:

mat customer$=("") : mat Customer=(0)
let customer$(cu_name)=CustName$
let customer$(cu_phone)=CustPhone$
read #customer, using form$(Customer), key=fnBuildKey$("customer",mat Customer$,mat Customer,2) : mat Customer$, mat Customer nokey KeyNotFound
! The above code assumes that the second key of the Customer file is based on the Name and Phone fields.

By using this logic you are able to avoid directly specifying the key in your code - which means that even if the key changes in the future, as long as your code specifies enough information, it will still find the correct key. In our example, even if we dropped the phone number from the key in the future, or even if we expand the length of the Customer Name field, our code would still work and fnBuildKey$ would still build the correct key without us having to look at or change our code again.

This kind of reasoning is central to the fileio system, which, when implemented properly, ensures that you can change your data files in any way you need to in the future, without breaking your existing programs.

==== fnUniqueKey ====
This function tests to see if a given key is unique to the specified file. This function is very useful for situations where you need to ensure that the user-entered key is unique.

''fnUniqueKey(Fl,key$*255)''

*FL – The file number of the opened file.
*Key$ - This is the key to test. If this key is the key for a preexisting record in the file, the function will return false. If this key can not be found in the file, the function will return true.

==== fnMakeUniqueKey$ ====
This function generates a unique key for a given file. This is useful if you do not care what the key is, but it needs to be unique. I use this function in situations where the user never needs to know what the given key is.

This function reads the key length for the given file. Then it returns a string that is the right length, which is generated by counting in binary until a key is found that does not appear in the file. The first key found for a 4 byte key field would be chr$(0)&chr$(0)&chr$(0)&chr$(0). If that key was already in use in the file, the function would return chr$(0)&chr$(0)&chr$(0)&chr$(1). If that one was also in use, it would then try chr$(0)&chr$(0)&chr$(0)&chr$(2), and so on until it found one that wasn’t in use.

''FnMakeUniqueKey$(fl)''

*FL – This is the file number of the opened file for the desired key.

==== fnKey$ ====
This function formats the key for the given file number. All it does is ensure the key is the correct length. You should use fnBuildKey$ instead to properly build the correct key for the record you want to read.

''FnKey$(FileNumber, Key$)''

*FileNumber - the file number we are formatting the key for
*Key$ - the key we are trying to format.

==== fnNotInFile ====
This function will determine if a non-key element in a line is unique. It works almost exactly like fnUniqueKey specified above, except that it allows you to enter the subscript value of the element you are checking for uniqueness. You can use this to look for uniqueness in any field, not just in the key field. Additionally, the search engine used by this function looks for a partial match, and will only return true if the given string is not found anywhere in the specified element for the given file.

''fnNotInFile(string$*100,filename$,sub)''

*String$ - Value to check for uniqueness in this file.
*Filename$ - This is the name of the file layout of the file you want to check. This file does not have to be open in order for you to search it, because the function will open it for you.
*Sub – This is the subscript value of the element you are checking.

==== fnSortKeys ====
This function takes an array of Primary Keys indicating records in the data file, and resorts it into the order you would have expected using one of the other keys for your data file.

For example: Lets say you had a customer file, and the first key was Customer Code and the second key was Customer Last Name. This function would take an array of Customer Codes and sort it into Last Name order.

This function requires the file to already be opened (which is usually the case when you have an array of keys from that file).

''fnSortKeys(mat Keys$,Layout$,DataFile,mat F$,mat F,mat Form$;KeyNum)''

*mat Keys$ - the array of keys. These keys are based on whatever key the file was opened with in DataFile.
*Layout$ - the file layout for the file.
*DataFile - the open file number matching the key file that matches mat Keys$.
*mat F$ - array sized to hold the strings from the data file. This is the array you get back from fnOpen.
*mat F - array sized to hold the numerics from the data file. This is the array you get back from fnOpen.
*mat Form$ - array of form statements, that you get back from fnOpen.
*KeyNum - This is the key that we'll sort based on. If not given, the first key listed in the layout is assumed.

=== File Reading Functions ===

These functions actually read information from your data file and return it. These functions can be used to simplify the logic in your programs for many common tasks.

==== fnReadAllKeys ====
This function will read through a file, returning the specified element(s) from each record into (a) dynamically dimensioned array(s). For example, I could tell it to give me the Inventory Code for every inventory item in my database in one array, while placing the Inventory Description (name) for each item into the corresponding position in another array.

''fnReadAllKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$;sub2,mat out2$)''

*Fl – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array
*mat out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

For example:

FnReadAllKeys(InventFile,mat Invent$,mat Invent,mat Form$,IN_Code,mat InvtList$,IN_Name,mat InvtNames$)

==== fnReadMatchingKeys ====

This function will read through a file, returning the specified element(s) from each record where the key matches the specified key into (a) dynamically dimensioned array(s). This function is the same as the above function except this one will filter the results, returning only those records where the key matches the specified key.

''fnReadMatchingKeys(Fl,mat f$,mat f,mat fm$,key$,keysub,sub1,mat out1$;sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - Only records where the key field matches key$ will be returned.
*Keysub – This tells the function which element is the key element for this particular file number.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadAllNewKeys ====

This function will read through a file, returning the specified element(s) from each record that isn’t already there into (a) dynamically dimensioned array(s). This function is the same as the above function, except this one will filter the results returning only those records that don’t already exist in the array (eliminating duplicates).

''FnReadAllNewKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$; dont_reset,sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Dont_reset – By default the array will clear the contents of the arrays that are passed in. This Boolean flag will instruct the function to not empty the passed in arrays.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadFilterKeys ====

This function by Mikhail Zheleznov is a modification of the above functions. Like its predecessors, it reads an entire file, populating the specified arrays with data from all or some of the records in the file. The given subscripts specify which fields to return from each record. The key given specifies search criteria for the records. The filter specifies filtering criteria that can be preformed on the data before it is returned.

''FnReadFilterKeys(Fl,Mat F$,Mat F,Mat Fm$,Key$,Keyfld,Sub1,Mat Out1$;Filter$,Filter_Sub,Readlarger,Sub2,Mat Out2$, Sub3, Mat Out3$, Sub4,Mat Out4$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - The key to search for in the read statements
*Keyfld – the subscript of the key field in the data file. This must match the key field specified in the data file otherwise the function won’t work.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Filter$ – This optional parameter identifies matches to search for in the records. It works in conjunction with Filter_Sub
*Filter_Sub – This parameter specifies which field to look for in the records for matches to Filter$. Only records which have Filter$ in the specified field will be returned.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.
*Sub3 – Subscript of the element to return in the third array. This is optional. If it is specified, you must give MAT out3$, or BR will return an error.
*MAT out3$ - Array in which to return the third (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub3 is given (non-zero). This parameter will not be used if Sub3 is not given or is given as 0.
*Sub4 – Subscript of the element to return in the fourth array. This is optional. If it is specified, you must give MAT out4$, or BR will return an error.
*mat out4$ - Array in which to return the fourth (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub4 is given (non-zero). This parameter will not be used if Sub4 is not given or is given as 0.

This function was written by Mikhail Zheleznov for the fileIO library.

==== fnReadDescription$ ====
''fnReadDescription$(Fl,Subscript,key$,mat F$,mat F,mat Form$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout) (RT_NAME, which should equal 2 after opening routefile (unless we change the file layout later)).
*key$ - Item that should match a key in this file somewhere (in this case it is the route code from the farm record).
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading they have to be dimensioned properly, which is why we use our colorcat$ and our colorcat for these parameters.
*mat Form$ - This will need to be our array of form statements, so the function can read the file properly.

Lets take a look at how this function works:

In the example program I used above, I am reading the Color File to get details about each color. The color file contains a colorcat code field, but I want to display the colorcat description. The colorcat file contains a few details about a color category, and it is indexed based on colorcat code:

route.dat, RT_
route.key, CODE
recl=512
===================================================
CODE, Routing Code, C 6
NAME, Routing Name Description, C 30
MOFT, T/A/C (truck/air/courier), C 1
SHIPPINGDAY, Day of Week for Shipping, C 7

Now, as you know, in the above example, we have already opened the ColorCat File, and we have opened and read a Color record.

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
30180 LET ccode$=color$(CO_CODE) !:
LET Name$=color$(CO_NAME)

Now all that’s left to do is to take the Color File’s ColorCat code and use it to look up the ColorCat File’s description.

30190 LET ColorCat$ = fnReadDescription$(ColorCatFile, CC_NAME, Color$(CO_CATEGORY),
mat ColorCat$, mat ColorCat, mat form$)

==== fnReadUnopenedDescription$ ====
This function accomplishes the same thing as fnReadDescription except that it opens the data file for you. It is slower then FnReadDescription$, but it is easier to use.

''FnReadUnopenedDescription$(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the value of the key field in the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2, so sometimes it is a good idea to design your data files so that string field number two is a descriptive field, like Name or Description.

This function only works on the first key file for each data file. This function is a convenience function but it is slow because it opens the file and closes it for each call. Opening a file is one of the most time consuming program operations.

==== fnReadNumber ====

fnReadNumber does the same thing that ReadDescription does except it reads a numeric field instead of a description.

Lets take a look at how this function works:

''fnReadNumber(Fl,subscript,key$,mat F$,mat F,mat fm$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout).
*Key$ - Item that should match a key in this file somewhere.
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading. They have to be dimensioned properly by [[FileIO_Library#fnOpenFile|fnOpen]].
*mat Fm$ - This will need to be our array of form statements, so the function can read the file properly.

==== fnReadUnopenedNumber ====
This function accomplishes the same thing as fnReadNumber except that it opens the data file for you. It is slower then FnReadNumber, but it is easier to use.

''fnReadUnopenedNumber(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the key of the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2.

==== fnReadRelativeDescription$ ====
This function is the same as fnReadDescription$ but for Relative Files.

''fnReadRelativeDescription$(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat F,mat form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedDescription$ ====
This is the same as ReadUnopenedDescription$ but for Relative Files.

''fnReadRelUnopenedDescription(Layout$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRelativeNumber ====
This is the same as fnReadNumber but for Relative Files.

''fnReadRelativeNumber(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat f,mat Form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedNumber ====
This is the same as fnReadUnopenedNumber but for Relative Files.

''fnReadRelUnopenedNumber(LayoutName$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRecordWhere$ ====
This function returns the record where the given element matches the given value. It does not depend on any key files, and it can be used to locate a record based on any element. However, it loops through the entire data file to do this and it could be a bit slow for large data files. This function opens the file for you, so the file does not have to be already opened.

''FnReadRecordWhere$(Layout$,SearchSub,SearchKey$*255,ReturnSub)''

*Layout$ - the layout of the file we are searching
*SearchSub - Subscript of the element to look in
*SearchKey$ - The value we are looking for
*ReturnSub - Subscript of the element to return

=== FileIO Utility Functions ===
==== fnDataCrawler ====
This function launches the Data Crawler as a function, so you can make your own programs link to it. Special thanks to Mikhail Zheleznov for turning the DataCrawler into a library function.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnDataEdit ====
This function is the same as fnDataCrawler only it opens a Grid for editing.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnShowData ====

This function builds a list or a grid in a floating window that is tied to a data file. It uses the same function that the datacrawler uses, but its much more customizable. All other datacrawler functions are just wrappers for this one.

The first parameter is the only required parameter.

''def library fnShowData(FileLay$;Edit,sRow,sCol,Rows,Cols,KeyNumber,Caption$*127,Path$*255,KeyMatch$*255,SearchMatch$*255,CallingProgram$*255,mat Records,mat IncludeCols$,mat IncludeUI$,mat ColumnDescription$,mat ColumnWidths,mat ColumnForms$,DisplayField$*80,mat FilterFields$,mat FilterForm$,mat FilterCompare$,mat FilterCaption$,mat FilterDefaults$,mat FilterKey)''

*FileLay$ - the file layout you want to display
*Edit - 1 for Edit (Grid) and 0 for View (Listview)
*sRow, sCol - the start position. if not given, its centered. If given but out of bounds, they'll be automatically adjusted to fit the grid on the screen.
*Rows, Cols - the size. If not given, defaults to fullscreen. If given but not big enough to fit the UI elements you request, they're automatically adjusted to fit everthing.
*KeyNumber - the Key to use when reading the data, used with other parameters. If not given, the file is read Relative for faster performance. Required if KeyMatch$ is given.
*Caption$ - the Caption to display, defaults to FileIO's Datacrawler
*Path$ - Alternate path to use for data files (Prepended to the name found in the layout)
*KeyMatch$ - Show only records that match this key. You can use Partial Keys. If this parameter is given, you must also give KeyNumber (above).
*SearchMatch$ - Show only records that contain this substring in them anywhere
*CallingProgram$ - used for logging purposes, pass in the system function Program$
*mat Records - Show only these records in the Grid. Use it to control exactly what the user sees.
*mat IncludeCols$ - Show only these columns. These column names must match the subscript names from the file layout.
*mat IncludeUI$ - Which UI Options to show. Build this array with one element for each optional UI element to include. Explanations of UI elements follow:
**"ColumnsButton" - adds a Select Columns button that the user can use to modify which columns appear on the list.
**"ExportButton" - adds an Export to CSV button that exports the data to a CSV file.
**"ImportButton" - adds an Import from CSV button that imports from the CSV file.
**"AddButton" - adds a button that can be used to add records to the data file.
**"SaveButton" - adds a button allowing the user to save changes
**"DeleteButton" - adds a button allowing the user to delete a row
**"KeyButton" - adds a button allowing the user to jump to a specified position by key or by record number (depending on if the file is opened keyed or not)
**"QuitButton" - adds a Quit button to the screen (the Esc key also quits)
**"Search" - adds a case insensitive search box to the screen.
**"Border" - adds a border around the screen
**"Caption" - adds a caption. (If you specify a caption, this is automatically turned on. If you don't specify a caption but turn on caption here, then FileIO uses the default FileIO data crawler caption.
**"Recl" - adds the Recl to the caption
**"Position" - adds the positions to the field descriptions in the column headings.
*mat ColumnDescription$ - Show these captions. If blank, use the descriptions from the layout
*mat ColumnWidths - Use these widths for the data, if not given, calculate from the file layout
*mat ColumnForms$ - Display Format for the data, including DATE and FMT and PIC
*mat DisplayField$ - Counter Field to display on the Loading Window. If its a field with an associated DATE ColumnForms$ value, that column form will be used when displaying the Counter Field. It can be any of the following:
**REC - this will display the current "REC/LREC" data in the loading window.
**READCOUNT - this will display the "Record Count / LREC" in the loading window.
**FINDCOUNT - this will display the number of records that match the current search criteria by itself in the loading window.
**A Field Name - one of your field names will display that field value in the loading window
**A string literal - anything else will display as a string in the loading window, so you could put something like "Loading, please wait" here and it will display.
*mat FilterFields$ - Contains the subscript of the field to compare to
*mat FilterForm$ - Contains the format of the field to compare to
*mat FilterCompare$ - Contains the comparison type ("<>" or ">" or "=" or ">=" or "*") (* means do a substring search)
*mat FilterCaption$ - The caption for the filter box
*mat FilterDefaults$ - The default value for the filter information
*mat FilterKey - The action to use when filtering the data this way (0 means simple exclude, 1 means start here, -1 means stop here)
**The final five arrays can be used to add user filter boxes to the data grid. You need one element in each array for every custom user filter box on the screen.

==== fnBeginAudit ====

The [[AuditBR|FileIO Compare]] routine is available and can be called from within your programs. To do so, call fnBeginAudit to mark the Start of the compare, then do whatever you need, then run fnCompare to compare everything that has changed between when you ran fnBeginAudit and when you ran fnCompare.

See [[AuditBR#fnBeginAudit|the documentation]] for more details.

==== fnCompare ====

See [[AuditBR#fnCompare|the documentation]] for more details.

==== fnCSVImport ====

This function calls the FileIO Import routine, the same one that you get from the Datacrawlers Import Button.

''fnCsvImport(Layout$*64;SuppressDialog,FileName$*300,ImportModeKey)''

*Layout$ - The file layout to import into
*SupressDialog - 1 to Supress the Import Dialog
*FileName$ - the name of the CSV file (Required if Dialog is Suppressed)
*ImportModeKey - the Import Mode Key (Required if Dialog is Suppressed)
**-1 - Add all records to the file
**0 - Update by Record Number (The file must contain a RecNum column and it must be first)
**1+ - Any positive number means Update by that Key (as listed in the layout).

==== fnCSVExport ====

This function exports a data file to a CSV file.

''fnCsvExport(Layout$*64;SuppressDialog,Filename$*300,IncludeRecNums,KeyNumber,StartKey$,KeyMatch$,Startrec,mat Records,SearchMatch$)''

*Layout$ - The File Layout to Export
*SuppressDialog - (1 to Suppress the Export Dialog, 0 to show it)
*Filename$ - the output file name (Required if SuppressDialog is 1)
*IncludeRecNums - Include a column with the Record Numbers in it
*KeyNumber - Use this key when reading the data for export
*StartKey$ - Start with the record that matches StartKey$
*KeyMatch$ - Export only the record(s) that match KeyMatch$
*StartRec - Start with this Record Number
*mat Records - Export only these records
*SearchMatch$ - Export only records containing this search string anywhere in them

==== fnExportListViewCsv ====

Exports the contents of the specified Listview in CSV format.

''fnExportListViewCsv(Window,Spec$;GenFileName,Delim$,FileName$*255)''

*Window - The Window containing the listview.
*Spec$ - The Spec identifying the listview.
*GenFileName - Flag telling weather or not to generate the file name.
*Delim$ - Delimiter to use. Comma is default.
*Filename$ - Filename to use

==== fnGenerateLayout & fnWriteLayout ====

This function calls on the Generate File Layout Wizard to generate and save the layout indicated by the parameters you give it. You must give it the same valid parameters that you would have come up with if you worked through the layout wizard the normal way, by running FileIO directly and choosing "Generate Layout".

You can also bypass the automatic parsing and generate a layout by specifying all the data directly and using fnWriteLayout.

''fnGenerateLayout(mat OpenStrings$, ReadString$*999, FormString$*20000, DimString$*999; DisplayFile)''
''

*mat OpenString$ - array of all the open strings for the given file from one of your old programs.
*mat ReadString$ - solid read statement from one of your old programs reading the entire record, (or at least everything you want in the layout).
*mat FormString$ - the form statement that goes with the ReadString$ (practice using the Generate Layout Wizard the normal way for details)
*mat DimString$ - the string containing Dim statements for each array mentioned in ReadString$. We need this to know how big the arrays are.
*DisplayFile - if True (1), it will Display the new layout in notepad when its done creating it. If false (0), it will simply create the file.

fnGenerateLayout takes all the above information and parses it into a layout, then calls fnWriteLayout to actually write the layout.

If you already know the information you want to put in the layout, its more direct to call fnWriteLayout below.

''fnWriteLayout(Name$,FileName$*127,VER,PRE$,MAT KFNAME$,MAT KDESCRIPTION$,MAT SUBS$,MAT DESCR$,MAT FORM$;RECL,MAT EXTRA$,DISPLAYFILE)''

*Name$ - the name of the new layout
*FileName$*127 - the name of the data file
*Ver - the version of the data file
*Pre$ - the prefix to use for the data file
*mat KfName$ - array of all the keys for the file
*mat Kdescription$ - array of the subscripts that each key is based on
*mat Subs$ - the subscript for each field in the file
*mat Descr$ - the descriptions for each field in the file
*mat Form$ - the form specs for each field in the file
*Recl - (optional) the record length of the file
*mat Extra$ - (optional) Additonal Information for each field in the file, placed in the Comments column of the new layout. This column is ignored by standard fileio processing.
DisplayFile - if True, open the file in Notepad after it has been created.

==== fnSubstituteStringCode ====
A Large Text Field that is searched. Code is run and any resulting variables are set, if they exist inside String enclosed between Substitute Chars (default []), then they will be replaced with the values derived by the code.

''fnSubstituteStringCode(&String$,Code$*2048;SubstituteChar$)''

*String$ - the string to be searched
*Code$ - code to be run. The resulting variables can be substituted into String
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnSubstituteString ====
A Large Text Field that is searched. Any matching fields in the passed in record will be substituted into their places. For example, if the string contained [cu_name] and you ran substitutions on the Customer file, then [cu_name] would be replaced by the name in the actual Customer record.

''fnSubstituteString(&String$,Filelayout$,mat F$,mat F;SubstituteChar$)''

*String$ - the string to be searched
*FileLayout$ - the layout to be searched
*mat F$ - the record to be used for substitution
*mat F - the record to be used for substitution
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnShowMessage ====
Displays a message to the user, in a child window. Returns the child window number, so that you can close it when you're done with the message.

''WindowNumber=fnShowMessage(Message$*54)''

*Message - the Message to display to the user

=== File System Utility Functions ===
These functions perform other tasks that aid with interacting with the file system.

==== fnGetFileDateTime$ ====
This does a directory listing to determine the Last Modified Date and Time of the given file. You pass it a file name, not a file layout, and it can be used on any file. Its not limited to BR internal files.

The syntax is:

''let FileDate$=fnGetFileDateTime$(Filename$*255)''

==== fnProgressBar ====
There's a Progress Bar that FileIO uses when copying or updating data files. You can use it in your own functions by calling fnProgressBar inside the main loop of the process that you want to display the progress bar over, and by calling fnCloseBar when you're done.

''fnProgressBar(Percent;Color$,ProgressAfter,ProgressThreshhold,UpdateThreshhold,Caption$*255,MessageRow$*255)''

*Percent - Percentage Complete expressed as a float between 0 and 1
*Color$ - HTML Color Code of BR Color Attribute to color the Progress Bar. Defaults to Green.
*ProgressAfter - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*ProgressThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*UpdateThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*Caption$ - Optional message to display above the progress bar.
*MessageRow$ - Optional message to display on the progress bar.

==== fnCloseBar ====

''fnCloseBar''

Call this function to close the progress bar window when your task is done running.

==== fnCopyFile ====

''fnCopyFile(FromFile$*255,ToFile$*255)''

*FromFile$ - The file to copy.
*ToFile$ - The destination file name including path.

This function copies any file, by opening it as an external file and reading and writing the data to the destination file. The advantage of this technique, over using the BR copy command, is this routine is more reliable when run on client server where you may be transferring large files from one side to the other over the internet.

This fnCopyFile also has a progress bar that displays as the file is transferred, so the user knows your software is busy.

This function works over Client Server. Under Client Server, specify @: at the beginning of your filename, to specify that the file is on the client. If the file is on the server, simply leave the @: off. See the chapter on [[Copy#Client_Server|using BR's copy command under Client Server]] for more details on the "@:".

This function's parameters and syntax are modeled off of the built in BR copy command, and like that one, this should work for local transfers, LAN transfers, or even internet transfers. This function will work better for internet transfers then the built in BR Copy Command, however.

==== fnCopyDataFiles ====

''fnCopyDataFiles(DestinationFolder$*255)''

*DestinationFolder$ - the folder to copy your data files to.

This function reads your file layouts and makes a copy of every data file (and key file) in your system to the destination folder, utilizing fnCopyFile above, for better performance and reliability when running over the internet, as well as a progress bar for each individual file.

It also displays a listview while its copying so you can watch the progress while its transferring your data files.

This can be used for making backups of your BR data, or for transferring the latest data onto a laptop for access to it while you're on the road away from the internet.

==== fnReIndex ====

This function reindexes a single data file

''fnReIndex(DataFile$*255;CallingProgram$*255,IndexNum,Path$*25)''

*Datafile$ - the file layout of the file to index
*CallingProgram$ - used for logging, pass Program$ in here
*IndexNum - The index to rebuild - if not given, rebuilds all indexes
*Path$ - the optional alternate path to use for rebuilding the data file.

==== fnReIndexAllFiles ====

This function reindexes all your data files. It doesn't require any parameters.

''fnReIndexAllFiles''

==== fnUpdateFile ====
This function checks and Updates a data file if it needs to be updated, by opening and then closing the data file.

''fnUpdateFile(FileLayout$)''

*FileLayout$ - The name of the file to update

==== fnRemoveDeletes ====

This function, written by Susan Smith, removes deleted records by copying the file with the -D option.

''fnRemoveDeletes(LayoutName$*255;Path$*255,CallingProgram$*255)''

*LayoutName$ - the file layout
*Path$ - Optional Alternate Path
*CallingPRogram$ - used for logging, pass Program$ in here

=== Layout Interrogation ===
Layout interrogation functions are provided for convenience and to enable future dictionary changes without disrupting any programs that interrogate it.

==== fnMakeSubProc ====
This function obtains the subscript assignments that were assigned by fnOpen according to the file layout. The fnMakeSubProc$ routine obtains the subscript assignments without actually opening the file. This is useful when a file record is passed as arrays into a library function in another program, or when you chained to another program and you need to know how to reach the data in the arrays without actually reopening the file.

''fnMakeSubProc(filelay$;mat Subscripts$)''

*FileLay$ - The name of the file layout from which to read the subscripts.
*mat Subscripts$ - If you give this optional array, fnMakeSubProc passes the subscripts back in this array rather then in the subs.$$$ file. This is much faster and helps avoid sharing conflicts.

When this routine returns, you can set the subscripts in your program by executing every element of the Subscripts$ array in a for/next loop.

If you did not pass in a subscripts array, then the a procedure file named subs.$$$ is created. If you proc that file, the proper subscripts will be set.

==== fnReadLayoutArrays ====
This function reads the fields in a file layout into arrays. You call it like the following

''fnReadLayoutArrays(filelay$,&prefix$;mat SSubs$, mat NSubs$, mat SSpec$, mat NSpec$,mat SDescription$, mat NDescription$,Mat Spos,Mat Npos)''

*filelay$ - the name of the layout to read
*prefix$ - the return value for the prefix for the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

This function call would read the fields from the layout in filelay$, and it would return the prefix to prefix$. The Subs would be returned in mat SSubs$ and mat NSubs$.

The Spec statements are returned in mat SSpec$ and mat NSpec$ and the Descriptions are returned in mat SDescription$ and mat NDescription$. The start positions on disk of each element are returned in mat SPos and mat NPos.

All the arrays are optional. If you don’t pass them the information they are supposed to record is simply not returned.

==== fnReadLayoutHeader ====
This function reads the header for a given file layout.

''fnReadLayoutHeader(Layoutname$*255;&Filename$,Mat Keys$,Mat KeyDescription$)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file

==== fnReadEntireLayout ====
This function reads the entire layout by calling fnReadLayoutHeader and fnReadLayoutArrays.

''fnReadEntireLayout(Layoutname$*255;&Filename$,&Prefix$,Mat Keys$,Mat KeyDescription$,Mat Ssubs$,Mat Nsubs$,Mat Sspec$,Mat Nspec$,Mat Sdescription$,Mat Ndescription$,Mat Spos,Mat Npos)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*prefix$ - the return value for the prefix for the file
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

==== fnReadSubs ====
This function reads the subscripts from a layout into Subs arrays.

''fnReadSubs(Layout$,mat SSubs$,mat NSubs$,&Prefix$)''

*Layout$ - the file layout name
*mat SSubs$ - the String Subscript Names
*mat NSubs$ - the Number Subscript Names
*Prefix$ - the files Prefix

==== fnReadKeyFiles ====
This function reads the list of key files from the layout.

''fnReadKeyFiles(Layout$,mat Keys$)''

*Layout$ - The file layout
*mat Keys$ - output array, the keys are returned here.

==== fnLayoutExtension$ ====

This function returns the layout extension being used.

==== fnReadLayouts ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''FnReadLayouts(mat Dirlist$)''

*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all the file layouts that FileIO can find.

==== fnDirVersionHistoryFiles ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''fnDirVersionHistoryFiles(Layout$,mat DirList$;BypassExtension$)''
*Layout$ - Which layout to look up version history of
*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all previous versions from history of the requested layout.

==== fnReadLayoutPath$ ====
This function doesn't actually interrogate your layouts. Instead, it interrogates your settings and returns the path specified for your layout files. This would usually be "filelay\" but you can change it in [[#fnSettings|fileio.ini.]]

It has no parameters.

''let Path$=fnReadLayoutPath$''

==== fnDoesLayoutExist ====
This function returns true if the given file layout exists. It returns false if the layout does not exist.

''FnDoesLayoutExist(layout$)''

*Layout$ - Layout to test for

==== fnReadForm$ (uncompiled) ====
Sometimes you need to know the original form statement that fileio is using to read your data file, most often when you're debugging your file layout, and you're getting some problem when reading the file. The form statement that fileio normally returns is compiled using CFORM$ to save space in the array, and to make the execution of your read statements faster. You can use this function to return the original form statement for the file.

The syntax is:

''let FormStatement$=fnReadForm$*10000(FileLayout$)''

Remember to dimension FormStatement to something huge! fnReadForm$ can return up to 10,000 characters.

==== fnReadFormAndSubs ====

This function does the same as above but it also reads the subscripts from the file into an array.

''let fnReadFormAndSubs(Layout$,mat Subs$,&ReadForm$,&StringSize,&NumberSize)''

Note that unlike most of our functions, all the above parameters are required.

The layout is the layout you're interrogating. The Array will be populated with the subscripts after the function. The ReadForm$ variable will be filled with the form statement for the file. Remember to dimension it large enough. StringSize and NumberSize will contain the number of string fields and numeric fields in the file.

Mat Subs$ will be returned, strings first, numbers last, matching the form statement that is returned. So Subs$(1) is the first string subscript and Subs$(StringSize+1) is the first Numeric subscript.

==== fnClearLayoutCache ====

fnClearLayoutCash (v2.3+) clears out the cache of layout name and data to get realtime Updates to File Layouts.

=== Other Useful Functions (non-layout related) ===

==== fnAskCombo ====

Opens a window with a combo box and returns the users selection.

''fnAskCombo$*255(mat Description$;Caption$*60,Default$*255)''

*mat Description$ - contains the combo box choices
*Caption$ - contains the optional caption for the window
*Default$ - the text of the item in mat Description$ that you want to be selected by default

==== fnSendEmail ====

This function sends an email and an optional attachment to the email address specified.

''fnSendEmail(Emailaddress$*255,Message$*10000;Subject$*255,Invoicefile$*255)''

*EmailAddress$ - the Destination Email Address
*Message$ - the Message$ to send
*Subject$ - the subject
*InvoiceFile$ - the filename of a file to attach. This is the BR filename (the function automatically converts it to an OS Filename.)

The function returns 1 when the email was sent successfully, or 0 if it wasn't sent successfully.

In order to use this function, you must have the emailcfg file layout in your layouts folder and you must have a copy of SendEmail.exe which is free and can be downloaded from the internet. Both of these files are included with the latest update of fileio.

You also have to configure fileio with the authentication information for your email server.

To configure your email server, simply run FileIO to get the data crawler, then select the emailcfg file layout and press F5 to edit it. Add a row if the file is empty.

Simply fill in the information the file is asking for in the appropriate fields and save the data, and then test sending an email to make sure it worked.

More information about sendEmail.exe is available from the author's product site here: [http://caspian.dotconf.net/menu/Software/SendEmail/ http://caspian.dotconf.net/menu/Software/SendEmail/]

==== fnClientEnv$ ====

This function returns the value of a Windows Environment Variable on the client under Client Server.

''fnClientEnv$*255(EnvKey$)''

*EnvKey$ is the name of the Windows Environment Variable to check on the client.

The function returns the value of the entered environment variable.

==== fnClientServer ====

This function returns true if you're currently running in Client Server mode, and false if you're running in the old "native" mode.

==== fnEmpty & fnEmptyS ====
These functions test if the passed in array is empty or not..

The syntax is:

''fnEmpty(mat Numeric)''

or

''fnEmptyS(mat String$)''

Example:

def fnSomeFunction(String$,mat Array$; mat OtherArray)
if fnEmpty(mat OtherArray) then
! Arrays were empty.
end if
fnend

==== fnReadScreenSize ====
This function reads the screen size of the given window (or window 0 if a window wasn't passed.) This is useful for centering a window on the screen, or for making sure window 0 is big enough for the child window you're trying to create.

The syntax is:

''fnReadScreenSize(&Rows,&Cols;Window)''

*Rows & Cols - returns the screen size in rows and columns.
*Window - the window to interrogate. If not given, assumes [[Open_Window#Comments_and_Examples|Window 0]].

==== fnBuildProcFile ====
This function builds a proc file to be executed later. This function and the next simplify the process of executing code in a proc file. It can even be used to spawn a new session of BR.

To use it, call fnBuildProcFile one or more times and specify some lines of code to execute.

''fnBuildProcFile(Command$*255)''

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnRunProcFile ====

This function spawns a new copy of BR and in it, runs the proc file that you've previously built using fnBuildProcFile (above).

'' fnRunProcFile(;NoWait) ''

The optional parameter "NoWait" causes the other session to spawn and run in a new thread. If you don't specify NoWait, the current session pauses and waits for the other session to close before proceeding.

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnLog & fnErrLog ====
These next two functions are functions to aid in logging. When you call either of these two functions, you give them a string that you wish to log. They will open the FileIO Log File and add a record to the end of it containing some user information such as login_name and session$, and the string that you specified. FnErrLog does the same thing as fnLog except it also logs the Error Number and the Line.

The syntax is:

''FnLog(string$)''

*String$ - the Log Message

''FnErrLog(String$)''

*String$ - the Log Message

==== fnLogArray ====

This function logs the given arrays to the log file, logging each field in the arrays. Its useful for recording, for example, an entire data record that is about to be written to a data file.

The syntax is:
''fnLogarray(mat F$,mat f;Message$*512,CallingProgram$*255)''
The first two parameters, of course, are the array to log. The third parameter is an optional message to be recorded along with the array, and the fourth optional parameter is the CallingProgram$ to save in the log along with the message. (The CallingProgram$ parameter can usually be passed as the system function Program$)

==== fnSetLogChanges ====
This function works in conjunction with the next function, and they're for recording just what changed in a data file. When the file is read, you call fnSetLogChanges and record the "before" picture of the file record.

After changes have been made and saved back to disk, you can call fnLogChanges below to record the actual changes.

The syntax is:
''fnSetLogChanges(mat F$,mat F)''

==== fnLogChanges ====
This function is the other half of the function above. It compares the given arrays with the ones set previously in the above function and checks for changes. Then it generates a log message recording information about just the items that changed.

The syntax is:
''fnLogChanges(mat F$,mat F;Message$*1024,CallingProgram$*255,Layout$)''

You need to pass in the same two arrays as before, but this time the modified versions of them.

You can also optionally pass a 1024 byte log message to record with the log entry.

CallingProgram$ again should be passed as the system internal function Program$.

The final parameter allows the passing of a Layout$. If you pass a Layout$, that layout is read and the subscripts are used when making the log message of changes, so that its easier to read. If you pass a layout, it will identify the changed fields by name. If you don't it will identify those fields by relative position number.

==== fnViewLogFile ====
All of the above functions store the information by default into a BR internal file defined in the filelay\logfile layout.

The fnViewLog function uses fnShowData to call the Data Crawler to display the FileIO Log File in a searchable listview.

''fnViewLogFile(;ShowQuit,ShowColumns,ShowExport)''

*ShowQuit - Show a quit button on the UI (if off, ESC will quit).
*ShowColumns - Include a button to allow the user to select which columns to view.
*ShowExport - Include a button to export the log file to CSV.

==== fnReadLockedUsers ====

This function returns a list of all users using the locked data file.

''fnReadLockedUsers(mat Users$)''

*mat Users$ - the list of users is returned here

==== fnDisplayLength ====
This function calculates the display length of a field based on its form spec.

''fnDisplayLength(Spec$)''

*Spec - the Form Spec to return the display length of.

==== fnLength ====
This function calculates the length on disk of a field based on its form spec.

''fnLength(Spec$)''

*Spec$ - the Form Spec to return the length of.

==== fnStandardTime$ ====
Converts Military Time to Standard Time. Returns Standard Time$

''fnStandardTime$(MilitaryTime$;Seconds)''

*MilitaryTime$ - Time in 24 hr format.

==== fnMilitaryTime$ ====
''fnMilitaryTime$(StandardTime$;Seconds)''

*StandardTime$ - Time in AM/PM Format

==== fnCalculateHours ====
Calculates the difference between 2 specified times.

''fnCalculateHours(TimeIn$,TOut$,DaysIN,DaysOut)''

*TimeIn$ - From Time
*TimeOut$ - To Time
*DaysIn - Days Start
*DaysOut - Days End

==== fnBuildTime$ ====
Builds a time in the format used by the above functions.

''fnBuildTime$(H,M,S,P;Military,Seconds)''

*H - Hours
*M - Minutes
*S - Seconds
*P - Boolean indicating AM/PM - 0 is AM, 1 is PM
*Military - Flag indicating weather desired result is in Military Time or not
*Seconds - Flag indicating weather to count seconds or ignore them. (1 means count seconds)

==== fnParseTime ====
Takes a time and pulls out the values

''fnParseTime(T$,&H,&M,&S,&P)''

*T$ - the time to parse
*H - Return value for Hours
*M - Return value for Minutes
*S - Return value for Seconds
*P - Return Value for AM/PM

== FileIO fnSettings (Global Settings Code) ==

The FileIO library can be made to implement certain policies across the board. These are established by creating a file called fileio.ini and typing statements like the following into it. This file is "PROCed", so you don't want to put line numbers in it.

Anything you don't specify in fileio.ini will take its default value, shown below. So you only need to specify the items that you want to be different.

Note, for the boolean settings below, 1 denotes TRUE and 0 denotes FALSE.

let EnforceDupkeys=1 ! Enforce that key number 1 is unique key
let Defaultfilelayoutpath$="filelay\" ! Path To Your File Layouts
let Promptonfilecreate=1 ! Ask User Before Creating New Files
let Createlogfile=0 ! Use Logging
let StartFileNumber=1 ! Set above 300 to avoid conflicts with legacy programs.
let CheckIndex=0 ! Automatically Verify Indexes (slow)
let CompressColumns=0 ! Shrink or Expand Columns in Data Crawler by Default
let MaxColWidth=20 ! Max Default Column Width in Data Crawler
let LogLibrary$="" ! Defaut Log Library, defaults to None
let LogLayout$="" ! Log file layout, defaults to Internal File
let AnimateDatacrawler=1 ! Use ScreenIO Animation for Datacrawler
let TemplatePath$="filelay\template\" ! Default Template Path
let IgnoreLayouts$="" ! List any Ignore Layouts here.
let CloseFileSimple=0 ! Use simple comparison for fnCloseFile

==== EnforceDupkeys ====

Turn on the EnforceDupkeys option to force that the first key listed in your file layouts is a unique key. FileIO will generate the standard BR error for Dupkeys when attempting to create indexes if it is not unique.

==== DefaultFileLayoutPath$ ====

Use the DefaultFileLayoutPath option to specify the path from your programs to your file layout folder. The default is "filelay\". Use this setting if you want to place your file layouts in another folder from the default.

==== PromptOnFileCreate ====

Use the PromptOnFileCreate setting to cause FileIO to display a message box whenever it is attempting to create a new file. This happens during the automatic update procedure, as well as during any attempt to access a file that does not exist. This setting should be turned off in your live system, and only turned on for development purposes. If you use the message box to cancel creating of the new file, then the file is not created, and fileIO or your application will most likely give an error when you attempt to actually access the new file.

It can be useful during development to make sure that you don't accidentally create the wrong files, due to an incorrectly specified path or a typeo in the filename in the layout file. However, in a live system, these things have already been tested, and you generally want the default behavior, because you don't want your users to have the ability to cancel the normal operation of FileIO.

==== CreateLogFile ====

Use this option to specify weather or not to use the FileIO log file. If it is turned on, a log file called FileIO.log in the current directory is created with entries listing all attempts to open a file, automatically update one, or automatically update your indexes.

==== StartFileNumber ====

Use this option to set the starting file number that the fnGetFileNumber and the fnOpen functions use to search for available file numbers. This is so that if you have certian reserved file numbers in your code, you can make sure that FileIO will not use those reserved file numbers, causing a conflict with your already existing programs. The default is 1, which is fine if your software does not have any reserved file numbers.

The allowable BR file numbers are 1-200 and 300-999.

==== CheckIndex ====

This function is used for Partial FileIO Implementations. If all of your software uses FileIO then all of your indexes are kept automatically up to date by the FileIO library and BR's internal file processing systems. However, if some of your programs do not use FileIO, and you use the FileIO library to add a new index file that those other programs do not know about, then its possible for the additional index file to become out of date when the master file is updated by your other programs.

Use this setting to cause FileIO to check the DateTime stamp on all your index files when opening a new file, and automatically update any indexes that may have potentially gotten out of date from other programs.

This option slows down the processing of the fnOpen function, particularly when running under client server over the internet. If you know that every program in your application suite uses FileIO, and that any programs that do not use FileIO still properly update all the indexes that your data file uses, then you can safely leave this setting turned off, and optimize your performance when opening several files using the fileIO system.

==== CompressColumns ====
This instructs the datacrawler to use smaller widths for small columns. If CompressColumns is false, the data crawler will make the column the width of the field or the width of the caption, whichever is wider. If CompressColumns is true, it will use the width of the field, not the caption.

==== MaxColWidth ====
This limits the column width to a set amount. This is applied after CompressColumns above.

==== LogLibrary$ ====
If a library is specified here, then fileio looks for a BR library with the specified name, and attempts to call a library function in it called fnFileIOLog that. This function should expect six parameters, which are Logstring$, Login_Name$, Session$, Days of Date$, Time$, and CallingProgram$, if LogLayout is also nonblank.

If you specify a LogLibrary and LogLayout is blank, then it calls your function giving it only 1 parameter.

It will call your function '''''instead of''''' the normal log file. Use this to implement your own logging functions however you want.

==== LogLayout$ ====
Use this setting to specify an alternate file layout for an alternate file to do the logging in. Base the file layout for this file on the logfile we supply for you in the filelay folder. It should have at least those fields, which our log routine will automatically populate, but you can add other fields if you want (though you will need to manage them yourself).

If you don't specify LogLayout, the default filelay\logfile will be used. This will allow you to also use the fnViewLogFile function to access it.

==== AnimateDataCrawler ====
The sister library [[ScreenIO]] has a feature that allows you to use an animation of a clock in your loading screens in your own programs. If you have [[ScreenIO]] then FileIO will automatically detect it and use it to display a loading animation while the data in the data crawler loads.

Set AnimateDataCrawler to false (0) in your fileio.ini file to bypass the animations if you do have screenio but don't want to see the animations anyway.

==== TemplatePath$ ====
This setting points to the folder that contains the code templates used by the Generate Code button on the main page of the Data Crawler.

==== IgnoreLayouts$ ====
This is a comma delimited list of all layouts that you wish to suppress from appearing on the main page of the data crawler. You can still access these layouts with your code, but they won't be listed in the data crawler for you to access.

Whatever you're using for a log layout, is automatically added to this list.
==== CloseFileSimple ====
The fnCloseFile function closes all the individual handles to a data file that was opened for output using multiple keys.

For BR 4.18 and higher, we support a better algorithm for detecting which files are matches for a given opened file number.

Set CloseFileSimple to true (1) to force it to check the old way.

== FileIO Add-on Packages ==

Many FileIO Add-on packages are currently in the works.

=== ScreenIO Library ===

The [[ScreenIO Library]] is a sister library to the FileIO library. The ScreenIO library requires the FileIO library in order to run.

The ScreenIO library is a complete Rapid Application Design tool that enables you to implement custom screen functions anywhere in your exiting programs.

If you call the ScreenIO Library as a function library, you call a function called fnFM and tell it which screen you wish to use. The ScreenIO library loads your user interface, loads your data files, and preforms all the file maintenance operations you have designed into your screens.

You can find out the latest information about the ScreenIO library in the ScreenIO page.

=== Audit BR ===

The [[AuditBR|Audit BR]] developer tool makes a backup copy of your file layouts. Then you run some code you're trying to test, and finally, run Audit BR again, to get a report showing all the changes to any of your data files automatically.

AuditBR is now included directly in FileIO. To use it, select the layout from the list of layouts in the Datacrawler and press the "Compare" button.

== What’s New (also described above) ==
=== 2018 ===
*Support for dates in any storage formats on disk (v2.48)

=== 2015 ===
*Added Rec to display for fnShowData
*Added FormStatement$ for debugging of form statements inside fileio
*Added mat BadRead$ for debugging of 726 errors when making new layouts
*Fixed a bug causing crash when logging things from long program folders
*fnClientEnv$ - reads a Windows Environment variable on the client using the command shell
*fnAskCombo$ - added an optional parameter to set default selection.

=== 2010 - 2014 ===
*FileIO now caches your file layouts in memory to make it much faster then before when opening the same data file in multiple programs.
*Generate Layout Wizard
*fnShowData
*Improved Logging
*fnViewLogFile
*Import/Export
*Import/Export by Function
*Many other speed increases
*if ScreenIO is present, Datacrawler uses the animation routines
*fnBuildProcFile & fnRunProcFile
*fnGenerateLayout & fnWriteLayout
*fnReadForm$
*fnReadFormAndSubs
*fnGetFileDateTime$
*fnReadLayoutPath$
*fnSortKeys
*fnSetLogChanges
*fnLogChanges
*fnLogArray
*fnReadScreenSize
*fnEmpty
*fnEmptyS
*Many other useful functions that were added to the documentation at earlier dates.

=== Spring 2009 ===

'''''New Functions:'''''

The FileIO Library has been updated in Spring 2009 to provide several new functions:

*fnReadRecordWhere
*fnKey$
*fnBuildKey$
*fnReadUnopenedDescription$
*fnUpdateFile
*fnDisplayLength
*fnLength
*fnReadLayoutHeader
*fnReadEntireLayout

'''''Speed Increases:'''''

Thanks to the BR [[Profiler]], we have increased the speed of FileIO fnOpen function by ten times when running over a LAN and by 100 times when running over the internet using Client Server.

In order to get the new Speed Upgrades, you will need to make sure that you use the latest copy of the [[#fnOpen_Function|fnOpen]] function in each one of your programs that use FileIO.

'''''Network FileIO:'''''
This version of FileIO has been optimized to work better in network situations.

'''''FnSettings: '''''
There are more configuration options in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine.

'''''Automatic Update Speed Fix:'''''
The automatic update proceedure has been made to run more then 100 times faster then before according to our benchmarking tests.

=== Fall 2008 ===
'''''DataCrawler Grid:'''''

By popular request we added a read/write version to the data crawler. This version works exactly the same as the datacrawler did before but it displays all the contents of your data files in a grid instead of a listview.

When you run the fileIO library as a program, it launches a tool known as the [[#DataCrawler|DataCrawler]]. The DataCrawler shows a listview displaying all your layout files in it. If you select one, it builds another listview with all the data in your selected data file.

If you are looking at the first list of all your file layouts, and you press F5, a grid will be build displaying all the data in your data files. You can change any of the records you like, and when you're done, your changes will be saved to the data file. Additionally, you can Add or Delete records using the buttons at the bottom. Any changes you make are not written to the disk until you click the "Save" button. If you press ESC (Cancel) the grid is closed and all changes you made sinse the last save are lost.

This tool is for programmers only. Do not give your end users access to the DataCrawler.

Use the DataCrawler at your own risk. Gabriel Bakker and Sage AX are not responsible for any harm that comes to your data files through the use of this or any other tools we offer.

The DataCrawler is not designed to be used to maintain your data files. It can be used carefully to correct small things in your data files.

'''''Support for Nonstandard Paths:'''''

Many BR Vendors keep different versions of the same data files in different locations. For example, sometimes a BR vendor will use a different Data folder to represent data for different Warehouses, or Customers. In cases like this it is necessary for your programs to specify the path to your data files. They may do so by specifying the optional "PATH" parameter to your data files. See the section [[#fnOpenFile]] for more information.

'''''Support for Nonstandard Layout Files Path:'''''

Old versions of the fileIO library required you to place all your file layouts in a subfolder of your program directory called "filelay". We have now changed the Fileio library to allow you to place your file layouts any place you want. The only requirement is that they are all together in one folder by themselves.

If you use a nonstandard path in the fileIO library, it is necessary to make a change to the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code in your copy of fileio.br.

'''''Prompt on Create:'''''

The FileIO library automatically creates any data files that it can't find. This was done to make it easier to deploy your finished programs - if you had any empty data files you could omit them from the packages and they would be created when they were needed, on the fly.

The current version of the FileIO library contains the same ability. However, it prompts you before creating any data files. This helps to avoid bugs that happen from incorrectly specifying the path to your data files.

However, if you do intend for your data files to be autocreated, then you probably don't want your end users to modify them. Therefore, you can use the PromptOnCreate setting in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code to specify. If this value is set to true, then the fileIO library will prompt you whenever it attempts to Autocreate a data file. If it is set to false, then the fileIO library will create the data files without prompting you, like it always did before.

'''''fnSettings:'''''

The newest version of the FileIO library supports some features that require you to specify Global Settings values. These are done by modifying the contents of the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine at the beginning of the fileIO library.

=== Fall 2006 ===
Many improvements have been made in the FileIO library over the summer. This section is intended to acquaint you with the highlights of those changes. Most of these improvements were built from ideas generated during the discussion at the April conference.

'''''Intermixed String and Numeric Specs:'''''
The File Library has been expanded to allow the reading of data files that contain mixed string and numeric specs. This is to aid those of you who are planning on implementing the FileIO Library on existing data files which may not be organized with strings first and numbers second.

The central idea of the FileIO Library is based upon the reading of your data files into a String and Numeric array. This will enable you to refer to the fields in your file by using a named subscript, saying F$(FM_NAME) to refer, for example, to the farm file’s name field. The advantage to this is that when you change the file layout, all your existing programs will not have to be modified, because they will only be looking at F$(FM_NAME). If the name field changes from the third string field to the fourth, the value of FM_NAME will also change, and you won’t have to worry about updating your data files.

However, in order to support the reading of a data file with intermixed string and numeric specs, the generated form statement will actually calculate the position of any fields that are not in order, so that the file read statement will still return all string fields first (into your string array) and the numeric fields second (into your numeric array). You do not need to worry about this; the library does it for you. All you have to do is read your file and use the data values.

The only thing that is required is making sure that all your string subscript names end with a “$”. This will tell the library that they are strings. Thank you, George, for this suggestion.

'''''Versioning / Automatic Updates:'''''
The file layouts have been expanded to contain a version number. This version number will be used to determine when a file needs to be updated. The version number is the third parameter in the file layout.

Any time you wish to change your file layouts, simply increment this version number. Each time the library attempts to open a data file, the file’s version is checked and compared with the version in the file layout. If the file layout has been changed (if the version in the file layout is greater then the version in the file) then the file will be updated to the latest version. Depending on the file size this may take a couple of moments. A simple progress bar will be displayed on screen while this is happening. The progress bar will be displayed in its own window, so it should not affect anything your programs may have had on screen.

The library uses the following procedure for updating a file. First, the file is copied to a backup file (prefixed by the letter ‘o’ for old). So color.dat would become ocolor.dat, and color.key would become ocolor.key. Then the new file is created and marked with the proper version number. (color.dat, color.key). The old file is opened in read-only mode, and the new file is opened for OutIn. The update routine actually reads through the old file layout, and one record at a time creates a new record, using the new file layout, with the same data, saving it to the new data file.

When it is done upgrading, the progress bar window is closed, and the file is reopened in the fashion you described in your call to fnOpen, and flow returns to your program as though nothing unusual has happened.

If an error occurs during processing, the routine will do what it can to roll your data files back to the previous version, but please make frequent backups of your data files anyway, just to be safe.

'''''Error Checking – If there is a mistake in the file layout:'''''
The routine attempts to discover the cause of the error in the case that one is encountered due to a missing file, a file sharing violation, or an invalid or corrupt file layout. If this should happen, the program is paused, and a text message is printed out explaining the most likely source for the error, including what part of the file layout, if any, may have caused the error.

You may then examine the printed text, and the contents of the BR system variables ERR and LINE to determine the problem. If you type “GO”, the next line will be execute “system”, ending your program.

If the file was in the middle of an upgrade when the error happened, it will be automatically rolled back to the previous version, so that when you fix the problem and try to run your program again, the file will again attempt to update from the beginning, and you won’t have to worry about corrupted data.

However, please backup your data before upgrading your data files anyway, just to be safe.

'''''Implementation of Keys / Creation of New Data Files:'''''
The library has been expanded to automatically create all new data files, and to automatically update any existing files. This means that in the file layout header, two new fields that were previously ignored are no longer ignored. The RECL value that you specify in your file layout will be used, along with the description/definition of your keys file. When you open a new file (or update an existing one), the library will calculate the proper kps and kln by evaluating the key description. This key description must match up with subscript values from the data elements in your file, and more then one may be specified, but they must be separated with slashes (/). If I wanted my Farm File to be keyed based on CODE and NAME, the proper key description would be:

farm.key, CODE/NAME

The library will then look up the position and length on disk of the CODE and NAME fields and put them together to create the proper keys during an update or creation of a new file.

'''''DataCrawler:'''''
Perhaps the most exciting new addition to the library is the addition of a programming tool I like to call a DataCrawler. If you run the FileIO Library directly as a program, instead of using it as a library, it will function as a DataCrawler. The DataCrawler requires a New Gui version of BR, as it requires a ListView to be able to properly and easily display the data in your files.

If you run it in an older version of BR you will get a message, telling you to run it in a newer copy. If you run it in a New Gui version of BR with CONFIG GUI OFF, then GUI will be turned temporarily on for the use of the DataCrawler and then turned off again when you are finished. If you run it in a New Gui version of BR with GUI ON, it will just run normally.

When you run the DataCrawler, first you will see a ListView displaying every file layout it can find in the filelay folder. If you select a file, the DataCrawler will open a large ListView with as many columns as there are fields in the file. The Column Headings will come from the element descriptions in your data files, and the column widths will come from the displayed width of the fields. There will be a row for every record in your data file, and you can resize the column widths, and scroll around the data file to view the raw data of your BR data files on disk.

If you are dealing with a particularly enormous data file (50,000+ records) it can take a moment to populate the ListView with the data in your data file. You may hit ESC to stop loading if you like, and view only the already loaded records.

If you would like to look up a particular record (based only upon the primary key for the data file), you may press F4. This will give you a window which asks you to input the key or partial key. When you press enter, the file will be reloaded, starting at the key you specified and continuing on to the end of the file, or until you press ESC. The records you are looking for should appear at the top of the ListView.

To reset the ListView and look at the contents of the entire file again, simply press F4, and enter a blank (“”) key.

Finally, as with any ListView, you may resort your data by clicking on any of the column headings. Then you can use the slider bar at the right to scroll down to the record you desire.

This is a programming tool and is not designed to be used by an end user. This tool will open your file in read-only mode. It will not allow you to modify the data; I leave that as an exercise for the reader. However, it will update any datafiles you view to the latest version (if they need to be updated) when it opens them, just as any other program that uses the library will do.

== Appendix (Examples)==

=== Example.br ===
00010 ! example.br - This program is an example of for the data reading simplification
00020 ! Copyright April 2006 by Gabriel Bakker
00030 ! Distributed open source as a Christmas gift to brag members
00040 !
00100 execute "config gui off"
01020 DIM form$(1)*255
01030 DIM color$(1)*255,color(1)
01040 DIM colorcat$(1)*255,colorcat(1)
02020 library "fileio": fnopenfile, fnreaddescription$
04000 !
04010 Openfiles: ! Open your files here
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)
06000 ! gosub WriteFiles ! If you want to test this line, make sure to drop flag from 4030
07000 !
07010 MainBit: ! This'un here's tha Main Bit
07030 RESTORE #ColorFile:
07100 ReadNextcolor: ! Read next record
07120 read #ColorFile, using form$(ColorFile) : mat Color$, mat Color eof EndReadColor
07180 PRINT Color$(co_name)&" ("&Color$(co_html)&") is a member of the '";
07190 PRINT trim$(fnReadDescription$(ColorcatFile,cc_Name,Color$(co_category),mat Colorcat$,mat Colorcat,mat form$))&"' category."
07290 goto ReadNextColor
07300 EndReadcolor: ! Finished with Color File
08000 STOP
25000 !
25010 WriteFiles: ! Uncalled routine to demonstrate writing files
25105 let color$(co_code)="GD" !:
let color$(co_Name)="Gold" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFD700"
25110 write #colorfile, using form$(colorfile): mat color$, mat color
25115 let color$(co_code)="LV" !:
let color$(co_Name)="Lavender" !:
let color$(co_Category)="BL" !:
let color$(co_html)="E6E6FA"
25120 write #colorfile, using form$(colorfile): mat color$, mat color
25125 let color$(co_Code)="OR" !:
let color$(co_Name)="Orange" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFA500"
25130 write #colorfile, using form$(colorfile): mat color$, mat color
25205 let colorcat$(cc_Code)="YL" !:
let colorcat$(cc_Name)="Yellows" !:
let colorcat$(cc_html)="FFFF00"
25210 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25215 let colorcat$(cc_Code)="BL" !:
let colorcat$(cc_Name)="Blues" !:
let colorcat$(cc_html)="0000FF"
25220 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25300 return
40000 !
40010 Open: ! ***** Function to call library openfile and proc subs
40020 def fnOpen(FILENAME$, MAT F$, MAT F, MAT FORM$;INPUTONLY,KEYNUM,___,INDEX)
40025 dim _FileIOSubs$(1)*50
40030 let fnopen=fnopenfile(FILENAME$, MAT F$, MAT F, MAT FORM$,INPUTONLY,KEYNUM,MAT _FileIOSubs$)
40040 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
40090 fnend
50000 !
60000 Ignore: Continue

Color File Layout
color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

ColorCat File Layout
colorcat.dat, CC_, 0
colorcat.key, CODE
recl=127
===================================================
CODE$, Category Code, C 6
NAME$, English Name for Color, V 30
HTML$, HTML Code for the Color, C 6

Example Layout showing multiple keys (price)
price.dat, PR_, 0
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2

[[Category:Utilities_Third_Party]]

FileIO Library

2024-09-11T13:35:12Z

Gordon.dye:

The '''FileIO''' Library began as a project to find a way to reduce the effort associated with making changes to data file layouts. Thanks to the Fileio library, when I have to make a change to a data file layout for my customers today, I can complete the task in under 1 minute, and not a single program needs to be changed in order to continue working with the new file layout. In fact, I don’t even have to update my customer’s data files, as the FileIO library takes care of this for me as well.

The trick is to define each of your file layouts in an ASCII text file layout file that is described below. The FileIO Library will parse through your file layouts, and it will instruct your programs how to access the file data after it has been read. It will also automatically detect when you make changes to the file layout, and it will update your customer’s data files on the fly to make sure they have the latest version. Finally, it contains a DataCrawler that you can use to examine the contents of any of your BR data files in a raw format.

For more information about the FileIO Library visit the [http://www.sageax.com/products/fileio-library/ Sage AX Website]

To download the latest copy of FileIO, click [http://www.sageax.com/downloads/FileIO.zip here.]

== Method of Operation ==
The file IO library parses a formatted text file layout and uses this information to structure the opening and initializing of the reading of a file “object”. The word object here is used to refer to all the data in a given record layout in one of your files. This library is easy to use, and provided you follow some simple standards, it will simplify your life immensely.

Your programs will need to define one array for all [[Form|file layout form statements]] and add a snippet of code (given below) to the program for interfacing with with the library. For each file you will need to define a couple of arrays and use the library to open them. From that point on access to data is simple and direct.

=== File Object Arrays ===

First, in your program you must create two arrays to store the file information. If we are dealing with the Color File these would be MAT COLOR$ and MAT COLOR. One will store all the string information about a color, and the other will store all the numeric data. Our working example will involve two files: a Color File and a Color Category File. You should dimension these to:

01030 DIM color$(1)*1000,color(1)
01040 DIM colorcat$(1)*1000,colorcat(1)

We're dimensioning the string arrays to 1000. This is the length of one field in the color file. It needs to be at least as big as the largest string field in the data file.

However, it is recommended to make sure the length is long enough to handle any field you might eventually add to the file at any point in the future. BR supports multi-line textboxes, so I sometimes add long memo fields to my data files that might be 400 or 800 or even 1000 characters long, therefore 1000 is the length I use now in all my new development.

But anything will work as long as its long enough to handle the largest data field in your file.

=== Forms Array ===

Your programs will need a string variable array to store the form statements associated with reading files. This form statements array will be dynamically generated or expanded whenever the a file is opened. It will say:

01234 DIM form$(1)*255

This form statement will be compiled by the FileIO open statement. BR limits all form statements to 255 bytes, so 255 is sufficient to hold the compiled Forms$ statements.

=== Library Linkage ===

You will also need the library statement:

02020 library "fileio.br": fnopenfile, fnreaddescription$

=== fnOpen Function ===

Now, add a snippet of code to interface with the library.

Because BR libraries do not share global variables with the programs they are called from, we will need to execute a proc file whenever we open a file to set the names of all our variables after we return. Add the following snippet of code into your program. It will create an FnOpen function that calls the library and runs the proc file. The $$$ at the end of the procfile name tells the procfile to self-destruct after execution. Since this procfile is used simply to return variable information back from the library to the main program, we don’t need it sitting around collecting dust.

99010 OPEN: ! ***** Function To Call Library Openfile And Proc Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
99030 dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
99050 if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
99060 fnend

Or, for those with [[Lexi]]:
OPEN: ! ***** Function To Call Library Openfile And Proc Subs
def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
fnend

=== Using FileIO in Your Programs ===
Now you are ready to process files. 
'''''You simply open the files by saying:'''''

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

'''''read each file as follows:'''''

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
'''''and access the data:'''''

30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name)

=== How it Works ===
The above statements tell the File Library to look in the filelay folder to find the file layout for the Color File, and read it to find out what the Color File looks like. Then it OPENs the Color File, and sets MAT COLOR$ and MAT COLOR to the correct number of elements to hold an entire color record. Finally, it will define several variables that we can use as pointers (subscripts) into these arrays to access the data read into the 2 arrays, and it will assign the file handle to a variable called "colorfile".

The second open above will do the same thing to the color category file, except the 1 parameter value tells the function to open readonly. The array subscripts populate procedure (passed back from Fileio) will be executed, thereby assigning values to the subscript names in the calling program. So, if I had a file layout such as the following:

color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

Then the functions would do the same thing as the following individual lines of code (assuming the next available file handle was 5):

DIM FORM$(5)*255
DIM COLOR$(9)*1023, COLOR(1)
OPEN #5: “Name=color.dat, kfname=color.key”,internal,outin,keyed
LET FORM$(5)=”form C 6,V 30,V 6,C 6”
LET FORM$(5)=CFORM$(FORM$(5))
LET COLORFILE=5
CO_CODE=1
CO_NAME=2
CO_CATEGORY=3
CO_HTML=4

The data is used by referencing the file array, with the subscript name, so the color’s description becomes color$(co_Name).

In the old days, if we wanted to change the file layout of our file, all of the programs that used that file would have to be changed one at a time to use the new file layout. Also, if the order of the fields changed, then all the programs would have to also be changed to use the new fields.

But now, using this function, we can change the file layout all we want. If we later want to insert a field into the file layout before color name, I won’t have to look at this program again; this program will just work fine, because the library maps the subscripts to the actual fields.

Also, the code is easier to read and maintain.

=== Example ===
The whole thing looks like this:

01025 ! Dimension the Arrays
01030 DIM color$(1)*1023,color(1)
01040 DIM colorcat$(1)*1023,colorcat(1)
01050 DIM form$(1)*255
02000 !
02020 library "fileio.br": fnopenfile, fnreaddescription$
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$) ! Open the file
05000 !
30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore ! Read the file
30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name) ! Use the data by referincing it in the file arrays
80000 !
90000 ! Every program using fileio needs the following code
99010 OPEN: ! ***** Function To Call Library Openfile And Generate Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths)
99030 dim _FileIOSubs$(1)*800
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$)
99050 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
99060 fnend

== File Layouts ==
Now lets inspect the anatomy of a properly formatted file layout. These should be placed in a subdirectory called filelay.

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...
<hr>
price.dat, PR_, 1

The first line contains the name of the Farm File, a unique string to prefix all of your subscript pointers, and the file version number. The subscript value is to ensure that the program knows the difference between the Farm File’s Farm Code, and the Route File’s Route Code. (One will be RT_CODE and the other is FM_CODE). These are separated by a comma. Spacing does not matter, so adjust your spacing so that it looks nice.

The Version number is used to determine when the data has changed, and an update needs to be made to your data file. Your file layouts should all start at version 0, and each time you want to make a change, you may increment this value by 1.

Each time you open a file with the FILEIO library, it reads the file version number of the file on disk (using the BR version() function), and then it compares it to the version number in your file layout. If your file layout has a higher version number then your existing data file, then the library opens the backup of the file layout for the version of the data file that exists on disk. It makes a backup copy of the existing data file, and creates a new file with the proper version number. Then it reads your records one at a time, and copies all the data from the old file into the new file one field at a time. If a field is dropped from the file layout, that data gets lost. If fields are rearranged, the data is copied and saved in the new file in the new positions. If a new field is added, it starts out blank (or 0).

If you look in the filelay folder, you will notice a version folder. This contains several files ending with a number. For example you may see a color.0, and a color.1 file.

If you run the fnopen function and it can not find your data file (usually because this is a new file and it hasn’t been created yet), ''the library will automatically create your file,'' based on the information you give in the first part of the file layout.

Also, whenever you make changes to your file layout, the function library will automatically update the data files on disk for you. It does this by renaming the old file, creating a new one with the new version number, and then copying the data from the old one to the new one a record at a time.

Any time it creates a file, or updates the file on disk, it creates a backup of the file ''layout''. The first time you run a program that tries to read your new data file, it will create the data file for you and make a backup of the layout, and if the number in your file layout is 0, then it will create, for example, a filelay\version\price.0 file, a backup of your file layout that the library uses to figure out what has changed the next time you try to update the file.

If you wish to make any changes to this data file, first you increment the version number, (in this case make the 0 into a 1). Then change the file layout all you want. You may rearrange fields, add new fields, add or remove keys, or change the record length.

The only step necessary for having your data files updated is to increment the version number every time you make a change to the file layout.

You may make any changes you like to the file layouts, but do not change the names of your existing subscripts. If you change the subscript name, not only will all the programs that reference that subscript be broken, but additionally, the routine will not understand that you are changing the name. It will think you are dropping the old field and adding a new field and any data stored in this location will be lost when the file is updated.

price.key, FARM

The second line contains the name of the first key, and a definition telling what the key is based on. These are separated by a comma. The key definition is made up of each of the subscript names in this file that form the keyfields for the file. When the library is called to open a file, if the file does not exist, or if it needs to be updated, a new one will be created. The function will read these subscript names that form your key definitions, and it will calculate the proper key position (KPS=) and length (KLN=) values. Then the create routine will use this information with the Index command to create the new key files.

price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127

Notice that the third key is based on three different fields. These are separated by a “/”. It is important that you use a “/” to separate your keys when you are building a key out of more then one field, because the function uses this “/” to help it make the proper BR syntax for defining complex key fields.

Also, note the "-U" at the end of the fieldname in the 4th key. This indicates that the "Description" part of that key is case insensitive. This translates to using the "U" on part of your key spec in Business Rules.

The file can have as many keys as you want. The function will keep parsing key file names until it reaches the next part of the layout. It opens any OutIn files with all keys so that any changes you may make to the data stored on disk will be properly reflected in all the key files.

The optional RECL= Parameter is read and used whenever a new file is created or an old one is updated. If it is not specified, the record length is calculated from the fields in the layout.

===================================================

The next line in the file is skipped by the parsing routine, and its purpose is to make the file layouts more readable to a programmer.

 
FARM$, Farm Code (or blank), C 4

Following the file and key structure, the fields are defined. There are three parameters on each field definition line, and you make one line for each field in your file layout. The first parameter is the subscript name that you will use in your program to refer to this data element. Place a $ at the end of the subscript name for all string elements. Don’t place anything at the end of the subscript name for numeric elements. Note that each of these names will be prefixed by the second parameter of the very first line of this layout.

The second parameter is the description. This description is for the benefit of the programmer, so when the programmer is reading the file layouts, (s)he can tell which field does what. The spaces are ignored, so you may include as many spaces as you wish to make the layout look good. It does seem like good general guidelines would be to limit your layout lines to 255 characters and your descriptions to 80.

The description is also used by the built in DataCrawler, a program that reads any of your data files and displays the entire contents in raw form in a listview. The Descriptions become the headings for each column in the listview.

Those descriptions are also used for the default captions for your fields if you use ScreenIO, a library for building GUI programs that itself builds off of fileio.

The third parameter is the form statement, which is pretty straightforward. Any items with a form statement of type “X” will be ignored, except that the length will still be used to calculate the position on disk of all remaining fields in the record. The library will take X fields into consideration when building the form statement, but not at any other time.

The fourth parameter is optionally a [[#Support for Dates|Disk Date Format]]. You can specify DATE(Julian) if you're storing your dates in Julian format on disk. Or you can specify DATE(cymd) or DATE(ymd) or DATE(mdy) or any other valid date spec here, and FileIO will treat this field like a date.

Your programs will still have to unpack it for you, fileio can't do that because fileio doesn't read the file for you.

However, the data crawler, the automatic updates, and screenIO, are all compatible with these dates specified in your file layout.

If the fourth parameter is anything other then DATE(format), then its treated as a comment and ignored.

The fifth and all later columns, if any, are treated as comments and ignored.

! default cost is normally zero
Comment line text must begin with an exclamation point, but it may be indented. Comment lines may appear anywhere (vertically) and are ignored. 
Blank lines are ignored as well.

#eof#
additional comments...
After the last field definition, an ''optional'' #eof# line may be specified, in which case any lines after that will be ignored.

 
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...

And that’s all there is to it.

=== Support for Dates ===
As of V2.48, file layouts support dates in any storage formats on disk. Whether you store your dates in Julian or in YMD or MDY or any other format, specify so in the 4th column of your file layouts, using the FileIO Date Keyword. ex: DATE(Julian) or DATE(YMD) or any other valid BR Date Format.

[[File:Dates0.png]]

When this is specified, it enables the FileIO data exploration tool (Data Crawler) to display the dates in human readable format. This works for both Viewing, and for Editing.

The new Date functionality also supports the File Layout Upgrade facility, allowing you to change the format of your dates on disk and FileIO will handle it automatically, upgrading the field to use the new date format for you.

It works also for Exporting your data files to CSV, and is supported automatically in the FileIO functions that do those exports. It converts the dates on export to a standard format (Default: m/d/cy) that you can specify in your FileIO.Ini File.

And it extends ScreenIO's date features to all date fields, no matter what format they're stored in. (Previously, ScreenIO's advanced date features only worked for dates stored in Julian on disk.)

This update adds two new ini file options:
CODE: SELECT ALL
DateFormatExport$='m/d/cy' ! Format of Dates when Exporting to CSV
DateFormatDisplay$='m/d/cy' ! Format of Dates when displaying in Data Crawler

You can use these to specify your preferred Date format for Viewing/Editing, and your preferred Date format for Exporting.

Remember, you can see the full list of FileIO ini file options, by looking in the source code at the top of FileIO.

There is a new optional parameter for all layout reading functions, mat NDateSpec$ and mat SDateSpec$ which correspond with the other arrays, to let you know which fields are date fields, so that you can develop routines in your programs to automatically pack and unpack the dates.

Important Note: Using FileIO, the reading of the data file is still done directly in your programs. So this does not change how your existing programs work. It does not unpack the dates for you in your programs. You still have to do all that.

For this reason, upgrading to the new Date processing will not break any of your current code.

=== Debugging Tips ===

When you're making new layouts, a missing comma can cause FileIO to parse the layout wrong and give you errors. Here are a couple tips to help ensure your layouts are error free before using them in your programs.

*Use the Data Crawler to test your layout. The data crawler is the simplest way to test your new layout without writing any code. It opens it and accesses the file in a very simple and straight forward manor to help identify any errors in the layout that you might have.

*If you have trouble with the form statement, you can't see whats in it because FileIO uses CForm$ to compile your form statement to make your programs run faster. But here's a way to tell what the original form statement was that FileIO generated when it put the strings first and numbers last in your program: Open the file in the Data Crawler. When you get an error, type "Print FormStatement$" to see the original form statement.

This works even if your file is working fine. Any time the file is opened with the data crawler, you can press CTRL-A and then type PRINT FormStatement$ and it will print out the uncompiled form statement for the file.

== Utilities ==

Now that you have your file layouts defined, you have access to several powerful utilities right out of the box using Fileio. Additionally, several more utilities are available as [[#FileIO_Add-on_Packages|Add-Ons]], including our most popular development tool [[Screenio|ScreenIO]]. You can read more about them in their section below.

But for now, lets take a look at some of the wonderful free utilities that come built into Fileio.

Some of these utilities are accessible from your code via library functions, but the primary way you access any of them is by simply loading the FileIO Library and running it directly.

=== DataCrawler ===
The data crawler is the original utility of FileIO. This utility shows you first a list of all data files allowing you to select one.

Select a data file and press enter, and FileIO will then display a listview containing all the data in the data file. This list is sized based on the size of your main BR window (window 0) automatically to take up the full size available to it, so if you want to see more, try [[Open Window|opening window 0]] larger before running FileIO.

At the top of the window is a filter box, and you can type anything you want in there and click "Refresh" and it will reread the data file, shortening the list to show only those records that match (case insensitive) what you have typed.

If you have ScreenIO installed, then FileIO's data crawler will take advantage of the included Animation Engine in ScreenIO to animate a loading window while the listview is displaying. If you don't have ScreenIO then FileIO will simply load the listview.

If you don't want to wait for the entire file to load, press ESC to stop the load process.

If the file is empty, FileIO will display a message box letting you know.

This tool is very useful for sorting out data errors. It will allow you to look inside any data file you have a layout for and directly view the data there.

At the bottom of the Data Crawler are several buttons. There's a Jump button that repositions the file by a key you specify and then loads the list with the data from that key on down to the end of the file.

There is a "Columns" button which you can use to decide which columns should show up on the listview. Fewer columns means faster loading so sometimes for large files I press ESC immediately when the file first starts loading to cancel the load. Then I click "Columns" and check only the columns I want to see. Finally I press the "Refresh" button to trigger it to read the file again and this time it loads much faster then before.

Next you'll find an Export button which starts the process for exporting a file to CSV. You can read more on that in the next section. And next to that is a Quit button.

In this example, we loaded the file "Read Only" so it put everything in a listview. But there are times when its useful to fix data errors this way too, especially during development. So if you want to directly edit your data file, on the first page select the file you want to edit and instead of pressing "Enter" or clicking "View", this time press "F5". F5 is the secret Edit button that loads a data file into a grid instead.

You can use the grid to change records, delete them or add them, and in addition to the buttons listed above, it also has an "Import" button for importing a CSV file into this data file.

Any changes you make to the data file are not saved until you click the "Save" button (which also only appears when you're in Edit mode).

In the 01/2015 release of FileIO, each records rec # is displayed in the listview, to aid in debugging bad data problems.

==== Debugging Tip ====
Any time you're viewing a file layout in the Data Crawler, you can see the Uncompiled Form Statement by pressing CTRL-A to get to an ATTN prompt, and then entering the command:

print FormStatement$

and it will print out the original form statement.

==== Another Debugging Tip ====

The FileIO Datacrawler ignores records that it cannot read. This is to allow for data files that have multiple record layouts in one data file. You make a custom layout for each record type and the data crawler shows just the records that match that type in the file.

However that becomes a problem when you're making a layout to work with an existing data file. Error 726 indicates that something minor in the file layout doesn't match the data on the disk, but these errors are ignored so you might see either an empty data file, or a data file with some records missing. If that happens, you need to see the missing records in order to figure out what is wrong with your layout. '''''It's very important that you don't try to use a file layout that isn't quite working right. Make sure your layout works and can read every record of a file that it should read before using it.'''''

To see the records that could not be read in a file, run the data crawler on the layout, then press CTRL-A to get an ATTN prompt. From there, enter the command

print mat BadRead$

and it will print all the records that were ignored because the file layout didn't match them. It prints out the raw data from the file.

==== Function Access to use Data Crawler in your programs ====
You can use the data crawler in your own programs by using one of the following functions:
* [[#fnDataCrawler|fnDataCrawler]] - Open a Listview showing the data file
* [[#fnDataEdit|fnDataEdit]] - Display the data in an editable grid
* [[#fnShowData|fnShowData]] - This function does the same thing as the above two, but with many many more options allowing you to customize exactly what appears and exactly what they're allowed to change.

Note: its not recommended to allow your customers to use the data crawler to access your data files directly. There's no way to specify validations or do anything complicated, so unless you're careful, there are lots of ways your customers could use this tool to do damage to your data files. It is a programmer tool only.

If you do decide to use it for your end users, be careful how you implement it.

=== Import/Export to CSV ===

You can use FileIO to export your data files to CSV or import from CSV into your data file. To do this, you want to run the data crawler and select the file layout you're looking for. Then, view it (or press F5 to edit if you want to import something). Click on the Export button and it will ask you to select a file. Once that is selected it will ask a couple other simple questions, and when you've specified the options to your satisfaction, click the Export! button. A new CSV file will be created.

Import is even more simple. To import, you must be in Edit mode (press F5 to select the file instead of the enter key) and then simply select the Import button. It will ask you again to choose the file, and then it will ask you if it should update all files by Record Number (if record number is recorded in the CSV file) or by Key (if the file has keys) or to just Add all information to the file. Select what you want and press Import and the CSV file is added to the BR data file.

==== Function Access to Import/Export from your programs ====

You can use the following functions to call the Import and Export functionality from your code.

*[[#fnCSVImport|fnCSVImport]]
*[[#fnCSVExport|fnCSVExport]]

These functions are intended to give you the ability to use our functionality to write your own import and export routines for your customers, because its not a good idea to let your customers run the Data Crawler.

=== Generate Layout Wizard ===

There is also a Generate Layout Wizard utility in FileIO. This utility is there to help you build your file layouts. It is designed to work with a certain style of BR programming that was common in the 80s and 90s. So if your software is written in a style that opens the file directly, and reads/writes the data to a long series of individual variables, the Generate Layout Wizard is for you.

To use it, start by running FileIO. Then, don't select a layout - instead, click on the "Generate Layout" button.

You'll see a screen with a bunch of large text boxes, a small grid, and some buttons.

The first thing you want to do is select the "Browse" button and then select a .wb or .br file that contains a program that reads or writes Most of the File.

When you select one, press the Scan All button and it fileio will search the whole program looking first for all the open strings. It will take the file that is opened the most times and then search for all read statements to that file. It will look for the longest read statement and then find the Form statement associated with that Read statement, and any DIM statements for any variables used.

If you don't like the file its chosen, click the "Open Scratch Pad" button to open the temp work file it uses into the program of your choice (I use myEdit for BRS files). Simply select all the open statements for the file you DO want to build off of, then click the Paste button to paste those open statements into the "Open String" list. After that click "Clear All" to erase what it did on the first search and then click "Scan All" again to rescan the program using this new data file.

You may have to help it a bit, but once it has a proper matching open statement, read statement, form statement and dim statements for any arrays used, press the "Generate Layout" button and it will build a layout for that file.

Finally, load the layout it built and clean up anything if you want, and consider adding better descriptions for each of the fields that you know (as it will use the variable names for both the subscripts AND descriptions in the layout).

When you're all done, click "Done".

==== Functions to Generate Layouts from your code ====

* [[#fnGenerateLayout_.26_fnWriteLayout|fnGenerateLayout]]
* [[#fnGenerateLayout_.26_fnWriteLayout|fnWriteLayout]]

=== Code Templates ===

One more tool FileIO has to help is the ability to generate code based on your file layouts.

Run FileIO and this time select a file layout and press "Generate Code". A window will pop up listing all the "Code Templates" that are available. Select one (and then select a key if it asks you - some templates require extra info). It looks like nothing happened, but the code you generated is now in your clip board. Paste it somewhere and take a look at it!

Code Templates help us to standardize our ways of doing things, which eventually leads to more and more powerful tools we can use. Code Templates also help ensure we use cleaner code by doing some of the busy-work of writing clean code for us.

==== Writing Code Templates ====
FileIO ships with several basic code templates. If you want to add your own, take a look in the filelay\templates folder (configurable in fileio.ini) and look at basic.brs. Copy it to your own program and then modify it to have your own code templates in it. Write me at gabriel.bakker@gmail.com with any questions. I want to help.

And if you write good code templates, its easy to share them with the BR community. Anyone can download your templates and place them in this folder and they'll instantly be available for use.

== FileIO Function Reference ==
''The FileIO Library contains a number of other useful functions.'' The following functions are available and you are welcome to use them:

=== Primary Functions ===

==== fnOpen ====
fnOpen is the primary function that opens a file, and it’s used like so:

''def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, DontSortSubs, Path$*255, Mat Descr$, Mat FieldWidths, SupressPrompt, IgnoreErrors, SuppressLog)''

Note that all of the parameters after MAT Form$ are optional. If you need to specify a parameter in the middle of the optional parameter group, just list zeroes and empty strings for the intervening unused parameters.

*FileName$ - The filename of the file layout for the file you’re reading.
*MAT F$ - The array that will be used to hold the string data for the file.
*MAT F – The array that will hold the numeric data for the file.
*MAT Form$ - An array of form statements.
*InputOnly – 1 means open for input only. 0 means open for OutIn and open every key file associated with the given data file (this is because all key files need to be open for the keys to be updated on an output) (defaults to 0). Files opened for input process considerably faster than files opened for output. Furthermore when files are opened for input only, alternate key files are ''not'' opened.
*KeyNum – This tells the function of which key to return the file handle (defaults to 1). Specify -1 to force the file to open Relative, without using its keys. If a file has no keys, it will always be opened Relative.
*DontSortSubs – The function by default, when compiling the Form statement, will sort the string and numeric subs in order to allow for reading the data into an array, and this parameter would turn this functionality off. However, if you are trying to read your data without reading it into an array, you are missing out on some serious efficiencies. You should normally leave this option turned off (0). This is a totally unsupported feature, and should always be set to 0, if it is specified at all.
*Path$ - The path to your data files. This optional parameter can be passed in by the calling function. It is prefixed to the beginning of the paths given in the file layout files. It is useful when your data files can be in different locations depending on the state of your program.
*mat Description$ - This optional parameter provides a way to read the description for each field from the original file layout. If the parameter is not provided, no description data will be returned.
*mat Fieldwidths – This optional parameter will return an array of the calculated display field widths. This number will always be at least large enough to contain the data for this field.
*SuppressPrompt - This optional parameter can be used to suppress the prompt normally given when fileIO creates a file. It can have three values. A value of 0, the default, uses the setting stored in your FileIO fnSettings routine to determine weather or not to prompt on Creation of a new file. A nonzero value always suppresses the prompt. A value of 1 indicates never to create a file if the file doesn't exist. A value of 2 automatically creates the file if the file doesn't exist.
*IgnoreErrors - Normally when fileio opens a data file, if there are errors trying to open the file, it prints them out to the debug console and pauses so that you can try to find out whats going wrong. If you specify 1 for "IgnoreErrors" it will cause Fileio to log those errors instead, and continue loading your program. This will result in the fnOpen file function returning Zero instead of the opened file number, so if you use IgnoreErrors, you need to test to make sure that fnOpen returned a file number before you try to access the file.
*SuppressLog - this optional parameter can be used to suppress writing to the log file for this one specific open statement. I use it for files that will be opened all the time, for example, the menu data file on one of my customers systems. Without this boolean parameter, his log file is quickly filled up with useless information any time his employees look at his menu. I specify this optional parameter to suppress logging anything about the menu file so that I can more easily find the actual programs they've used when looking in the logfile.

'''''Note: When using fnOpenFile, you really want to call your local function fnOpen, which in turn calls fnOpenFile for you.''''' FnOpenFile is for internal use only.

Example:

Let FFILE=FNOPEN(“FARM”,MAT FARM$,MAT FARM,MAT FORM$,0,2)
Let RFILE=FNOPEN(“ROUTE”,MAT ROUTE$,MAT ROUTE,MAT FORM$,1,3)
Let CFILE=FNOPEN(“CUSTOMER”,MAT CUSTOMER$,MAT CUSTOMER,MAT FORM$)

assuming:
farm.dat has 3 keys: farm.ky1, farm.ky2, farm.ky3
route.dat has 4 keys: route.ky1 … route.ky4
customer.dat has 2 keys: customer.ky1, customer.ky2

This will perform the following opens and set the following variables:

OPEN #1: “Name=Farm.Dat, kfname=farm.ky2”,internal,outin,keyed
OPEN #2: “Name=Farm.Dat, kfname=farm.ky1”,internal,outin,keyed
OPEN #3: “Name=Farm.Dat, kfname=farm.ky3”,internal,outin,keyed
OPEN #4: “Name=Route.Dat, kfname=route.ky3”,internal,input,keyed
OPEN #5: “Name=Customer.Dat,kfname=customer.ky1”,internal,outin,keyed
OPEN #6: “Name=Customer.Dat,kfname=customer.ky2”,internal,outin,keyed
LET FFILE=1
LET RFILE=4
LET CFILE=5

This will also resize the arrays, set the form statement, and create all the subscripts to make accessing the data clear and simple, as in the above example. The KEYNUM parameter is where you list the key file you would like to use for reading and writing. The extra keys are opened to ensure that all keys get updated properly when the file is changed.

Example:
DIM FORM$(1),PRICE$(1)*255,PRICE(1),
DIM DESCRIPTION$(1)*80,FIELDWIDTHS(1)

Let PRICEFILE=FNOPEN(“PRICE”,MAT PRICE$,MAT PRICE,MAT FORM$,0,2,0,"",MAT DESCRIPTION$)

Assuming the Price File layout (filelay\price) contains:

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30

This will perform the following opens and set the following variables:

OPEN #1: “Name=Price.Dat, kfname=Price.ky2”,internal,outin,keyed
OPEN #2: “Name=Price.Dat, kfname=Price.ky1”,internal,outin,keyed
OPEN #3: “Name=Price.Dat, kfname=Price.ky3”,internal,outin,keyed
let PRICEFILE=1
let PR_FARM=1
let PR_ITEM=2
let PR_GRADE=3
let PR_DESCR=4
let PR_PRICE=1
let PR_COST=2
let PR_XOPRICE=3
let PR_XOCOST=4
let PR_MOPRICE=5
let PR_MOCOST=6
let PR_VOPRICE=7
let PR_VOCOST=8
MAT FORM$(1)
MAT PRICE$(4)
MAT PRICE(8)
MAT DESCRIPTION$(12)
MAT FIELDWIDTHS(12)
let FORM$(1)=CFORM$(”form C 4,C 4,C 4,POS 74,C 30,POS 50,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2”)
let Description$(1)= “Farm Code (or blank)”
let Description$(2) = “Item Code”
let Description$(3) = “Quality”
let Description$(4) = “Description of Price Rule”
let Description$(5) = “Default Price”
let Description$(6) = “Default Cost”
let Description$(7) = “Default Christmas Price”
let Description$(8) = “Default Christmas Cost”
let Description$(9) = “Default Mothers D Price”
let Description$(10) = “Default Mothers D Cost”
let Description$(11) = “Default Valentine Price”
let Description$(12) = “Default Valentine Cost”
let FieldWidths(1) = 4
let FieldWidths(2) = 4
let FieldWidths(3) = 4
let FieldWidths(4) = 30
let FieldWidths(5) = 8
let FieldWidths(6) = 8
let FieldWidths(7) = 8
let FieldWidths(8) = 8
let FieldWidths(9) = 8
let FieldWidths(10) = 8
let FieldWidths(11) = 8
let FieldWidths(12) = 8

There are a few things I’d like to point out about the example above. First, you will notice that the form statement jumps around to put all the strings first, and then the numbers last. This is why it has a “POS 74, C 30,POS 50”. Then notice that the subscripts for the string variables are 1 .. 4, and the subscripts for the numbers are 1 .. 8. Finally, the order of the Description and FieldWidth fields also match the sorted positioning of the Form Statement.

The reason that we sort our form statements is so that BR will allow us to read the file into arrays by saying:

Read #pricefile, using form$(pricefile) : mat price$, mat price

Without resorting, the above statement would give a conversion error as BR attempted to put the PR_PRICE field inside mat price$(4). However, because we have reordered the form statement, we are able to read them safely into two arrays, and then we will be able to use the values without caring what position they are in the file, by simply saying PRICE$(PR_DESCRIPTION) when we want the description, and PRICE(PR_PRICE) when we want the pr_Price field.

Another thing you may notice about the above example is that it gives the calculated display length for the numeric fields as 8, when on the disk (and in the file layout) they are listed as BH 3.2. The reason for this is the program looks at the BH 3, and figures that a number that takes up 3 bytes on disk has a potential maximum size of 256**3 or 16,777,216, and therefore will need up to 8 characters of screen display space to view.

Finally, note that any field with a form statement of X is ignored by the library, except that the blank space is used when building the FORM statement.

==== fnCloseFile ====
This function will close the specified file number and all keys that were opened with the file. The purpose of this function is to facilitate the closing of the extra keys that are opened when you open a file for OutIn with the library. There is no need to use this for files opened for input because it is easier to just close the file directly. Secondary keys are not opened by FileIO for files opened for input only.

You must give the function the name of the file layout. It uses this information to determine how many keys were opened, and how many it must therefore close.

Then it basically starts at the file number you gave it, and closes the next X files that were opened with the same file name as this, where X is the number of keys associated with this file.

The syntax is:

''fnCloseFile(filenumber,filelay$;path$)''

*FileNumber – The filenumber of the file you are trying to close.
*FileLay$ - The name of the file layout for this file. This is used to determine how many keys the file would have been opened with and therefore how many we now need to close.
*Path$ - Optional Alternate Path. Use to close files that were opened using the open file's optional alternate path parameter.

==== fnGetFileNumber ====
FnGetFileNumber is a simple function to find a valid unused file handle. If you use this function in all of your programs, they will become much more portable, as you will never have to worry about your file handles fighting with each other. The function will return 0 if no free file number was found (but with 999 of them available now, I have never seen it happen).

''fnGetFileNumber(;X,Count)''

*X – This optional parameter will specify where to start looking.
*Count - This optional parameter will specify how many file numbers to find in a row. If count is 3, then fnGetFileNumber will return the first filenumber in the first gap of three unused file numbers that it finds.

=== File Reading Helper Functions ===

These functions perform various useful calculations to aid in interacting with data files when you're using fileio.

==== fnBuildKey$ ====
This function will return the key for a given record in a data file. It actually reads the file layout and builds the key to match the layout.

''FnBuildKey$(Layout$, Mat F$, Mat F; Keynum)''

*Layout$ - the name of the data file to build the key for.
*Mat F$ - the string array of the file object
*Mat F - the numeric array of the file object
*KeyNum - This optional parameter specifies which of the key files in the given layout the key should be built for.

To use this, you want some code like in the following example:

mat customer$=("") : mat Customer=(0)
let customer$(cu_name)=CustName$
let customer$(cu_phone)=CustPhone$
read #customer, using form$(Customer), key=fnBuildKey$("customer",mat Customer$,mat Customer,2) : mat Customer$, mat Customer nokey KeyNotFound
! The above code assumes that the second key of the Customer file is based on the Name and Phone fields.

By using this logic you are able to avoid directly specifying the key in your code - which means that even if the key changes in the future, as long as your code specifies enough information, it will still find the correct key. In our example, even if we dropped the phone number from the key in the future, or even if we expand the length of the Customer Name field, our code would still work and fnBuildKey$ would still build the correct key without us having to look at or change our code again.

This kind of reasoning is central to the fileio system, which, when implemented properly, ensures that you can change your data files in any way you need to in the future, without breaking your existing programs.

==== fnUniqueKey ====
This function tests to see if a given key is unique to the specified file. This function is very useful for situations where you need to ensure that the user-entered key is unique.

''fnUniqueKey(Fl,key$*255)''

*FL – The file number of the opened file.
*Key$ - This is the key to test. If this key is the key for a preexisting record in the file, the function will return false. If this key can not be found in the file, the function will return true.

==== fnMakeUniqueKey$ ====
This function generates a unique key for a given file. This is useful if you do not care what the key is, but it needs to be unique. I use this function in situations where the user never needs to know what the given key is.

This function reads the key length for the given file. Then it returns a string that is the right length, which is generated by counting in binary until a key is found that does not appear in the file. The first key found for a 4 byte key field would be chr$(0)&chr$(0)&chr$(0)&chr$(0). If that key was already in use in the file, the function would return chr$(0)&chr$(0)&chr$(0)&chr$(1). If that one was also in use, it would then try chr$(0)&chr$(0)&chr$(0)&chr$(2), and so on until it found one that wasn’t in use.

''FnMakeUniqueKey$(fl)''

*FL – This is the file number of the opened file for the desired key.

==== fnKey$ ====
This function formats the key for the given file number. All it does is ensure the key is the correct length. You should use fnBuildKey$ instead to properly build the correct key for the record you want to read.

''FnKey$(FileNumber, Key$)''

*FileNumber - the file number we are formatting the key for
*Key$ - the key we are trying to format.

==== fnNotInFile ====
This function will determine if a non-key element in a line is unique. It works almost exactly like fnUniqueKey specified above, except that it allows you to enter the subscript value of the element you are checking for uniqueness. You can use this to look for uniqueness in any field, not just in the key field. Additionally, the search engine used by this function looks for a partial match, and will only return true if the given string is not found anywhere in the specified element for the given file.

''fnNotInFile(string$*100,filename$,sub)''

*String$ - Value to check for uniqueness in this file.
*Filename$ - This is the name of the file layout of the file you want to check. This file does not have to be open in order for you to search it, because the function will open it for you.
*Sub – This is the subscript value of the element you are checking.

==== fnSortKeys ====
This function takes an array of Primary Keys indicating records in the data file, and resorts it into the order you would have expected using one of the other keys for your data file.

For example: Lets say you had a customer file, and the first key was Customer Code and the second key was Customer Last Name. This function would take an array of Customer Codes and sort it into Last Name order.

This function requires the file to already be opened (which is usually the case when you have an array of keys from that file).

''fnSortKeys(mat Keys$,Layout$,DataFile,mat F$,mat F,mat Form$;KeyNum)''

*mat Keys$ - the array of keys. These keys are based on whatever key the file was opened with in DataFile.
*Layout$ - the file layout for the file.
*DataFile - the open file number matching the key file that matches mat Keys$.
*mat F$ - array sized to hold the strings from the data file. This is the array you get back from fnOpen.
*mat F - array sized to hold the numerics from the data file. This is the array you get back from fnOpen.
*mat Form$ - array of form statements, that you get back from fnOpen.
*KeyNum - This is the key that we'll sort based on. If not given, the first key listed in the layout is assumed.

=== File Reading Functions ===

These functions actually read information from your data file and return it. These functions can be used to simplify the logic in your programs for many common tasks.

==== fnReadAllKeys ====
This function will read through a file, returning the specified element(s) from each record into (a) dynamically dimensioned array(s). For example, I could tell it to give me the Inventory Code for every inventory item in my database in one array, while placing the Inventory Description (name) for each item into the corresponding position in another array.

''fnReadAllKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$;sub2,mat out2$)''

*Fl – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array
*mat out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

For example:

FnReadAllKeys(InventFile,mat Invent$,mat Invent,mat Form$,IN_Code,mat InvtList$,IN_Name,mat InvtNames$)

==== fnReadMatchingKeys ====

This function will read through a file, returning the specified element(s) from each record where the key matches the specified key into (a) dynamically dimensioned array(s). This function is the same as the above function except this one will filter the results, returning only those records where the key matches the specified key.

''fnReadMatchingKeys(Fl,mat f$,mat f,mat fm$,key$,keysub,sub1,mat out1$;sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - Only records where the key field matches key$ will be returned.
*Keysub – This tells the function which element is the key element for this particular file number.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadAllNewKeys ====

This function will read through a file, returning the specified element(s) from each record that isn’t already there into (a) dynamically dimensioned array(s). This function is the same as the above function, except this one will filter the results returning only those records that don’t already exist in the array (eliminating duplicates).

''FnReadAllNewKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$; dont_reset,sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Dont_reset – By default the array will clear the contents of the arrays that are passed in. This Boolean flag will instruct the function to not empty the passed in arrays.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadFilterKeys ====

This function by Mikhail Zheleznov is a modification of the above functions. Like its predecessors, it reads an entire file, populating the specified arrays with data from all or some of the records in the file. The given subscripts specify which fields to return from each record. The key given specifies search criteria for the records. The filter specifies filtering criteria that can be preformed on the data before it is returned.

''FnReadFilterKeys(Fl,Mat F$,Mat F,Mat Fm$,Key$,Keyfld,Sub1,Mat Out1$;Filter$,Filter_Sub,Readlarger,Sub2,Mat Out2$, Sub3, Mat Out3$, Sub4,Mat Out4$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - The key to search for in the read statements
*Keyfld – the subscript of the key field in the data file. This must match the key field specified in the data file otherwise the function won’t work.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Filter$ – This optional parameter identifies matches to search for in the records. It works in conjunction with Filter_Sub
*Filter_Sub – This parameter specifies which field to look for in the records for matches to Filter$. Only records which have Filter$ in the specified field will be returned.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.
*Sub3 – Subscript of the element to return in the third array. This is optional. If it is specified, you must give MAT out3$, or BR will return an error.
*MAT out3$ - Array in which to return the third (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub3 is given (non-zero). This parameter will not be used if Sub3 is not given or is given as 0.
*Sub4 – Subscript of the element to return in the fourth array. This is optional. If it is specified, you must give MAT out4$, or BR will return an error.
*mat out4$ - Array in which to return the fourth (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub4 is given (non-zero). This parameter will not be used if Sub4 is not given or is given as 0.

This function was written by Mikhail Zheleznov for the fileIO library.

==== fnReadDescription$ ====
''fnReadDescription$(Fl,Subscript,key$,mat F$,mat F,mat Form$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout) (RT_NAME, which should equal 2 after opening routefile (unless we change the file layout later)).
*key$ - Item that should match a key in this file somewhere (in this case it is the route code from the farm record).
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading they have to be dimensioned properly, which is why we use our colorcat$ and our colorcat for these parameters.
*mat Form$ - This will need to be our array of form statements, so the function can read the file properly.

Lets take a look at how this function works:

In the example program I used above, I am reading the Color File to get details about each color. The color file contains a colorcat code field, but I want to display the colorcat description. The colorcat file contains a few details about a color category, and it is indexed based on colorcat code:

route.dat, RT_
route.key, CODE
recl=512
===================================================
CODE, Routing Code, C 6
NAME, Routing Name Description, C 30
MOFT, T/A/C (truck/air/courier), C 1
SHIPPINGDAY, Day of Week for Shipping, C 7

Now, as you know, in the above example, we have already opened the ColorCat File, and we have opened and read a Color record.

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
30180 LET ccode$=color$(CO_CODE) !:
LET Name$=color$(CO_NAME)

Now all that’s left to do is to take the Color File’s ColorCat code and use it to look up the ColorCat File’s description.

30190 LET ColorCat$ = fnReadDescription$(ColorCatFile, CC_NAME, Color$(CO_CATEGORY),
mat ColorCat$, mat ColorCat, mat form$)

==== fnReadUnopenedDescription$ ====
This function accomplishes the same thing as fnReadDescription except that it opens the data file for you. It is slower then FnReadDescription$, but it is easier to use.

''FnReadUnopenedDescription$(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the value of the key field in the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2, so sometimes it is a good idea to design your data files so that string field number two is a descriptive field, like Name or Description.

This function only works on the first key file for each data file. This function is a convenience function but it is slow because it opens the file and closes it for each call. Opening a file is one of the most time consuming program operations.

==== fnReadNumber ====

fnReadNumber does the same thing that ReadDescription does except it reads a numeric field instead of a description.

Lets take a look at how this function works:

''fnReadNumber(Fl,subscript,key$,mat F$,mat F,mat fm$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout).
*Key$ - Item that should match a key in this file somewhere.
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading. They have to be dimensioned properly by [[FileIO_Library#fnOpenFile|fnOpen]].
*mat Fm$ - This will need to be our array of form statements, so the function can read the file properly.

==== fnReadUnopenedNumber ====
This function accomplishes the same thing as fnReadNumber except that it opens the data file for you. It is slower then FnReadNumber, but it is easier to use.

''fnReadUnopenedNumber(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the key of the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2.

==== fnReadRelativeDescription$ ====
This function is the same as fnReadDescription$ but for Relative Files.

''fnReadRelativeDescription$(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat F,mat form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedDescription$ ====
This is the same as ReadUnopenedDescription$ but for Relative Files.

''fnReadRelUnopenedDescription(Layout$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRelativeNumber ====
This is the same as fnReadNumber but for Relative Files.

''fnReadRelativeNumber(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat f,mat Form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedNumber ====
This is the same as fnReadUnopenedNumber but for Relative Files.

''fnReadRelUnopenedNumber(LayoutName$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRecordWhere$ ====
This function returns the record where the given element matches the given value. It does not depend on any key files, and it can be used to locate a record based on any element. However, it loops through the entire data file to do this and it could be a bit slow for large data files. This function opens the file for you, so the file does not have to be already opened.

''FnReadRecordWhere$(Layout$,SearchSub,SearchKey$*255,ReturnSub)''

*Layout$ - the layout of the file we are searching
*SearchSub - Subscript of the element to look in
*SearchKey$ - The value we are looking for
*ReturnSub - Subscript of the element to return

=== FileIO Utility Functions ===
==== fnDataCrawler ====
This function launches the Data Crawler as a function, so you can make your own programs link to it. Special thanks to Mikhail Zheleznov for turning the DataCrawler into a library function.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnDataEdit ====
This function is the same as fnDataCrawler only it opens a Grid for editing.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnShowData ====

This function builds a list or a grid in a floating window that is tied to a data file. It uses the same function that the datacrawler uses, but its much more customizable. All other datacrawler functions are just wrappers for this one.

The first parameter is the only required parameter.

''def library fnShowData(FileLay$;Edit,sRow,sCol,Rows,Cols,KeyNumber,Caption$*127,Path$*255,KeyMatch$*255,SearchMatch$*255,CallingProgram$*255,mat Records,mat IncludeCols$,mat IncludeUI$,mat ColumnDescription$,mat ColumnWidths,mat ColumnForms$,DisplayField$*80,mat FilterFields$,mat FilterForm$,mat FilterCompare$,mat FilterCaption$,mat FilterDefaults$,mat FilterKey)''

*FileLay$ - the file layout you want to display
*Edit - 1 for Edit (Grid) and 0 for View (Listview)
*sRow, sCol - the start position. if not given, its centered. If given but out of bounds, they'll be automatically adjusted to fit the grid on the screen.
*Rows, Cols - the size. If not given, defaults to fullscreen. If given but not big enough to fit the UI elements you request, they're automatically adjusted to fit everthing.
*KeyNumber - the Key to use when reading the data, used with other parameters. If not given, the file is read Relative for faster performance. Required if KeyMatch$ is given.
*Caption$ - the Caption to display, defaults to FileIO's Datacrawler
*Path$ - Alternate path to use for data files (Prepended to the name found in the layout)
*KeyMatch$ - Show only records that match this key. You can use Partial Keys. If this parameter is given, you must also give KeyNumber (above).
*SearchMatch$ - Show only records that contain this substring in them anywhere
*CallingProgram$ - used for logging purposes, pass in the system function Program$
*mat Records - Show only these records in the Grid. Use it to control exactly what the user sees.
*mat IncludeCols$ - Show only these columns. These column names must match the subscript names from the file layout.
*mat IncludeUI$ - Which UI Options to show. Build this array with one element for each optional UI element to include. Explanations of UI elements follow:
**"ColumnsButton" - adds a Select Columns button that the user can use to modify which columns appear on the list.
**"ExportButton" - adds an Export to CSV button that exports the data to a CSV file.
**"ImportButton" - adds an Import from CSV button that imports from the CSV file.
**"AddButton" - adds a button that can be used to add records to the data file.
**"SaveButton" - adds a button allowing the user to save changes
**"DeleteButton" - adds a button allowing the user to delete a row
**"KeyButton" - adds a button allowing the user to jump to a specified position by key or by record number (depending on if the file is opened keyed or not)
**"QuitButton" - adds a Quit button to the screen (the Esc key also quits)
**"Search" - adds a case insensitive search box to the screen.
**"Border" - adds a border around the screen
**"Caption" - adds a caption. (If you specify a caption, this is automatically turned on. If you don't specify a caption but turn on caption here, then FileIO uses the default FileIO data crawler caption.
**"Recl" - adds the Recl to the caption
**"Position" - adds the positions to the field descriptions in the column headings.
*mat ColumnDescription$ - Show these captions. If blank, use the descriptions from the layout
*mat ColumnWidths - Use these widths for the data, if not given, calculate from the file layout
*mat ColumnForms$ - Display Format for the data, including DATE and FMT and PIC
*mat DisplayField$ - Counter Field to display on the Loading Window. If its a field with an associated DATE ColumnForms$ value, that column form will be used when displaying the Counter Field. It can be any of the following:
**REC - this will display the current "REC/LREC" data in the loading window.
**READCOUNT - this will display the "Record Count / LREC" in the loading window.
**FINDCOUNT - this will display the number of records that match the current search criteria by itself in the loading window.
**A Field Name - one of your field names will display that field value in the loading window
**A string literal - anything else will display as a string in the loading window, so you could put something like "Loading, please wait" here and it will display.
*mat FilterFields$ - Contains the subscript of the field to compare to
*mat FilterForm$ - Contains the format of the field to compare to
*mat FilterCompare$ - Contains the comparison type ("<>" or ">" or "=" or ">=" or "*") (* means do a substring search)
*mat FilterCaption$ - The caption for the filter box
*mat FilterDefaults$ - The default value for the filter information
*mat FilterKey - The action to use when filtering the data this way (0 means simple exclude, 1 means start here, -1 means stop here)
**The final five arrays can be used to add user filter boxes to the data grid. You need one element in each array for every custom user filter box on the screen.

==== fnBeginAudit ====

The [[AuditBR|FileIO Compare]] routine is available and can be called from within your programs. To do so, call fnBeginAudit to mark the Start of the compare, then do whatever you need, then run fnCompare to compare everything that has changed between when you ran fnBeginAudit and when you ran fnCompare.

See [[AuditBR#fnBeginAudit|the documentation]] for more details.

==== fnCompare ====

See [[AuditBR#fnCompare|the documentation]] for more details.

==== fnCSVImport ====

This function calls the FileIO Import routine, the same one that you get from the Datacrawlers Import Button.

''fnCsvImport(Layout$*64;SuppressDialog,FileName$*300,ImportModeKey)''

*Layout$ - The file layout to import into
*SupressDialog - 1 to Supress the Import Dialog
*FileName$ - the name of the CSV file (Required if Dialog is Suppressed)
*ImportModeKey - the Import Mode Key (Required if Dialog is Suppressed)
**-1 - Add all records to the file
**0 - Update by Record Number (The file must contain a RecNum column and it must be first)
**1+ - Any positive number means Update by that Key (as listed in the layout).

==== fnCSVExport ====

This function exports a data file to a CSV file.

''fnCsvExport(Layout$*64;SuppressDialog,Filename$*300,IncludeRecNums,KeyNumber,StartKey$,KeyMatch$,Startrec,mat Records,SearchMatch$)''

*Layout$ - The File Layout to Export
*SuppressDialog - (1 to Suppress the Export Dialog, 0 to show it)
*Filename$ - the output file name (Required if SuppressDialog is 1)
*IncludeRecNums - Include a column with the Record Numbers in it
*KeyNumber - Use this key when reading the data for export
*StartKey$ - Start with the record that matches StartKey$
*KeyMatch$ - Export only the record(s) that match KeyMatch$
*StartRec - Start with this Record Number
*mat Records - Export only these records
*SearchMatch$ - Export only records containing this search string anywhere in them

==== fnExportListViewCsv ====

Exports the contents of the specified Listview in CSV format.

''fnExportListViewCsv(Window,Spec$;GenFileName,Delim$,FileName$*255)''

*Window - The Window containing the listview.
*Spec$ - The Spec identifying the listview.
*GenFileName - Flag telling weather or not to generate the file name.
*Delim$ - Delimiter to use. Comma is default.
*Filename$ - Filename to use

==== fnGenerateLayout & fnWriteLayout ====

This function calls on the Generate File Layout Wizard to generate and save the layout indicated by the parameters you give it. You must give it the same valid parameters that you would have come up with if you worked through the layout wizard the normal way, by running FileIO directly and choosing "Generate Layout".

You can also bypass the automatic parsing and generate a layout by specifying all the data directly and using fnWriteLayout.

''fnGenerateLayout(mat OpenStrings$, ReadString$*999, FormString$*20000, DimString$*999; DisplayFile)''
''

*mat OpenString$ - array of all the open strings for the given file from one of your old programs.
*mat ReadString$ - solid read statement from one of your old programs reading the entire record, (or at least everything you want in the layout).
*mat FormString$ - the form statement that goes with the ReadString$ (practice using the Generate Layout Wizard the normal way for details)
*mat DimString$ - the string containing Dim statements for each array mentioned in ReadString$. We need this to know how big the arrays are.
*DisplayFile - if True (1), it will Display the new layout in notepad when its done creating it. If false (0), it will simply create the file.

fnGenerateLayout takes all the above information and parses it into a layout, then calls fnWriteLayout to actually write the layout.

If you already know the information you want to put in the layout, its more direct to call fnWriteLayout below.

''fnWriteLayout(Name$,FileName$*127,VER,PRE$,MAT KFNAME$,MAT KDESCRIPTION$,MAT SUBS$,MAT DESCR$,MAT FORM$;RECL,MAT EXTRA$,DISPLAYFILE)''

*Name$ - the name of the new layout
*FileName$*127 - the name of the data file
*Ver - the version of the data file
*Pre$ - the prefix to use for the data file
*mat KfName$ - array of all the keys for the file
*mat Kdescription$ - array of the subscripts that each key is based on
*mat Subs$ - the subscript for each field in the file
*mat Descr$ - the descriptions for each field in the file
*mat Form$ - the form specs for each field in the file
*Recl - (optional) the record length of the file
*mat Extra$ - (optional) Additonal Information for each field in the file, placed in the Comments column of the new layout. This column is ignored by standard fileio processing.
DisplayFile - if True, open the file in Notepad after it has been created.

==== fnSubstituteStringCode ====
A Large Text Field that is searched. Code is run and any resulting variables are set, if they exist inside String enclosed between Substitute Chars (default []), then they will be replaced with the values derived by the code.

''fnSubstituteStringCode(&String$,Code$*2048;SubstituteChar$)''

*String$ - the string to be searched
*Code$ - code to be run. The resulting variables can be substituted into String
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnSubstituteString ====
A Large Text Field that is searched. Any matching fields in the passed in record will be substituted into their places. For example, if the string contained [cu_name] and you ran substitutions on the Customer file, then [cu_name] would be replaced by the name in the actual Customer record.

''fnSubstituteString(&String$,Filelayout$,mat F$,mat F;SubstituteChar$)''

*String$ - the string to be searched
*FileLayout$ - the layout to be searched
*mat F$ - the record to be used for substitution
*mat F - the record to be used for substitution
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnShowMessage ====
Displays a message to the user, in a child window. Returns the child window number, so that you can close it when you're done with the message.

''WindowNumber=fnShowMessage(Message$*54)''

*Message - the Message to display to the user

=== File System Utility Functions ===
These functions perform other tasks that aid with interacting with the file system.

==== fnGetFileDateTime$ ====
This does a directory listing to determine the Last Modified Date and Time of the given file. You pass it a file name, not a file layout, and it can be used on any file. Its not limited to BR internal files.

The syntax is:

''let FileDate$=fnGetFileDateTime$(Filename$*255)''

==== fnProgressBar ====
There's a Progress Bar that FileIO uses when copying or updating data files. You can use it in your own functions by calling fnProgressBar inside the main loop of the process that you want to display the progress bar over, and by calling fnCloseBar when you're done.

''fnProgressBar(Percent;Color$,ProgressAfter,ProgressThreshhold,UpdateThreshhold,Caption$*255,MessageRow$*255)''

*Percent - Percentage Complete expressed as a float between 0 and 1
*Color$ - HTML Color Code of BR Color Attribute to color the Progress Bar. Defaults to Green.
*ProgressAfter - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*ProgressThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*UpdateThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*Caption$ - Optional message to display above the progress bar.
*MessageRow$ - Optional message to display on the progress bar.

==== fnCloseBar ====

''fnCloseBar''

Call this function to close the progress bar window when your task is done running.

==== fnCopyFile ====

''fnCopyFile(FromFile$*255,ToFile$*255)''

*FromFile$ - The file to copy.
*ToFile$ - The destination file name including path.

This function copies any file, by opening it as an external file and reading and writing the data to the destination file. The advantage of this technique, over using the BR copy command, is this routine is more reliable when run on client server where you may be transferring large files from one side to the other over the internet.

This fnCopyFile also has a progress bar that displays as the file is transferred, so the user knows your software is busy.

This function works over Client Server. Under Client Server, specify @: at the beginning of your filename, to specify that the file is on the client. If the file is on the server, simply leave the @: off. See the chapter on [[Copy#Client_Server|using BR's copy command under Client Server]] for more details on the "@:".

This function's parameters and syntax are modeled off of the built in BR copy command, and like that one, this should work for local transfers, LAN transfers, or even internet transfers. This function will work better for internet transfers then the built in BR Copy Command, however.

==== fnCopyDataFiles ====

''fnCopyDataFiles(DestinationFolder$*255)''

*DestinationFolder$ - the folder to copy your data files to.

This function reads your file layouts and makes a copy of every data file (and key file) in your system to the destination folder, utilizing fnCopyFile above, for better performance and reliability when running over the internet, as well as a progress bar for each individual file.

It also displays a listview while its copying so you can watch the progress while its transferring your data files.

This can be used for making backups of your BR data, or for transferring the latest data onto a laptop for access to it while you're on the road away from the internet.

==== fnReIndex ====

This function reindexes a single data file

''fnReIndex(DataFile$*255;CallingProgram$*255,IndexNum,Path$*25)''

*Datafile$ - the file layout of the file to index
*CallingProgram$ - used for logging, pass Program$ in here
*IndexNum - The index to rebuild - if not given, rebuilds all indexes
*Path$ - the optional alternate path to use for rebuilding the data file.

==== fnReIndexAllFiles ====

This function reindexes all your data files. It doesn't require any parameters.

''fnReIndexAllFiles''

==== fnUpdateFile ====
This function checks and Updates a data file if it needs to be updated, by opening and then closing the data file.

''fnUpdateFile(FileLayout$)''

*FileLayout$ - The name of the file to update

==== fnRemoveDeletes ====

This function, written by Susan Smith, removes deleted records by copying the file with the -D option.

''fnRemoveDeletes(LayoutName$*255;Path$*255,CallingProgram$*255)''

*LayoutName$ - the file layout
*Path$ - Optional Alternate Path
*CallingPRogram$ - used for logging, pass Program$ in here

=== Layout Interrogation ===
Layout interrogation functions are provided for convenience and to enable future dictionary changes without disrupting any programs that interrogate it.

==== fnMakeSubProc ====
This function obtains the subscript assignments that were assigned by fnOpen according to the file layout. The fnMakeSubProc$ routine obtains the subscript assignments without actually opening the file. This is useful when a file record is passed as arrays into a library function in another program, or when you chained to another program and you need to know how to reach the data in the arrays without actually reopening the file.

''fnMakeSubProc(filelay$;mat Subscripts$)''

*FileLay$ - The name of the file layout from which to read the subscripts.
*mat Subscripts$ - If you give this optional array, fnMakeSubProc passes the subscripts back in this array rather then in the subs.$$$ file. This is much faster and helps avoid sharing conflicts.

When this routine returns, you can set the subscripts in your program by executing every element of the Subscripts$ array in a for/next loop.

If you did not pass in a subscripts array, then the a procedure file named subs.$$$ is created. If you proc that file, the proper subscripts will be set.

==== fnReadLayoutArrays ====
This function reads the fields in a file layout into arrays. You call it like the following

''fnReadLayoutArrays(filelay$,&prefix$;mat SSubs$, mat NSubs$, mat SSpec$, mat NSpec$,mat SDescription$, mat NDescription$,Mat Spos,Mat Npos)''

*filelay$ - the name of the layout to read
*prefix$ - the return value for the prefix for the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

This function call would read the fields from the layout in filelay$, and it would return the prefix to prefix$. The Subs would be returned in mat SSubs$ and mat NSubs$.

The Spec statements are returned in mat SSpec$ and mat NSpec$ and the Descriptions are returned in mat SDescription$ and mat NDescription$. The start positions on disk of each element are returned in mat SPos and mat NPos.

All the arrays are optional. If you don’t pass them the information they are supposed to record is simply not returned.

==== fnReadLayoutHeader ====
This function reads the header for a given file layout.

''fnReadLayoutHeader(Layoutname$*255;&Filename$,Mat Keys$,Mat KeyDescription$)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file

==== fnReadEntireLayout ====
This function reads the entire layout by calling fnReadLayoutHeader and fnReadLayoutArrays.

''fnReadEntireLayout(Layoutname$*255;&Filename$,&Prefix$,Mat Keys$,Mat KeyDescription$,Mat Ssubs$,Mat Nsubs$,Mat Sspec$,Mat Nspec$,Mat Sdescription$,Mat Ndescription$,Mat Spos,Mat Npos)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*prefix$ - the return value for the prefix for the file
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

==== fnReadSubs ====
This function reads the subscripts from a layout into Subs arrays.

''fnReadSubs(Layout$,mat SSubs$,mat NSubs$,&Prefix$)''

*Layout$ - the file layout name
*mat SSubs$ - the String Subscript Names
*mat NSubs$ - the Number Subscript Names
*Prefix$ - the files Prefix

==== fnReadKeyFiles ====
This function reads the list of key files from the layout.

''fnReadKeyFiles(Layout$,mat Keys$)''

*Layout$ - The file layout
*mat Keys$ - output array, the keys are returned here.

==== fnLayoutExtension$ ====

This function returns the layout extension being used.

==== fnReadLayouts ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''FnReadLayouts(mat Dirlist$)''

*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all the file layouts that FileIO can find.

==== fnDirVersionHistoryFiles ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''fnDirVersionHistoryFiles(Layout$,mat DirList$;BypassExtension$)''
*Layout$ - Which layout to look up version history of
*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all previous versions from history of the requested layout.

==== fnReadLayoutPath$ ====
This function doesn't actually interrogate your layouts. Instead, it interrogates your settings and returns the path specified for your layout files. This would usually be "filelay\" but you can change it in [[#fnSettings|fileio.ini.]]

It has no parameters.

''let Path$=fnReadLayoutPath$''

==== fnDoesLayoutExist ====
This function returns true if the given file layout exists. It returns false if the layout does not exist.

''FnDoesLayoutExist(layout$)''

*Layout$ - Layout to test for

==== fnReadForm$ (uncompiled) ====
Sometimes you need to know the original form statement that fileio is using to read your data file, most often when you're debugging your file layout, and you're getting some problem when reading the file. The form statement that fileio normally returns is compiled using CFORM$ to save space in the array, and to make the execution of your read statements faster. You can use this function to return the original form statement for the file.

The syntax is:

''let FormStatement$=fnReadForm$*10000(FileLayout$)''

Remember to dimension FormStatement to something huge! fnReadForm$ can return up to 10,000 characters.

==== fnReadFormAndSubs ====

This function does the same as above but it also reads the subscripts from the file into an array.

''let fnReadFormAndSubs(Layout$,mat Subs$,&ReadForm$,&StringSize,&NumberSize)''

Note that unlike most of our functions, all the above parameters are required.

The layout is the layout you're interrogating. The Array will be populated with the subscripts after the function. The ReadForm$ variable will be filled with the form statement for the file. Remember to dimension it large enough. StringSize and NumberSize will contain the number of string fields and numeric fields in the file.

Mat Subs$ will be returned, strings first, numbers last, matching the form statement that is returned. So Subs$(1) is the first string subscript and Subs$(StringSize+1) is the first Numeric subscript.

==== fnClearLayoutCache ====

fnClearLayoutCash (v2.3+) clears out the cache of layout name and data to get realtime Updates to File Layouts.

=== Other Useful Functions (non-layout related) ===

==== fnAskCombo ====

Opens a window with a combo box and returns the users selection.

''fnAskCombo$*255(mat Description$;Caption$*60,Default$*255)''

*mat Description$ - contains the combo box choices
*Caption$ - contains the optional caption for the window
*Default$ - the text of the item in mat Description$ that you want to be selected by default

==== fnSendEmail ====

This function sends an email and an optional attachment to the email address specified.

''fnSendEmail(Emailaddress$*255,Message$*10000;Subject$*255,Invoicefile$*255)''

*EmailAddress$ - the Destination Email Address
*Message$ - the Message$ to send
*Subject$ - the subject
*InvoiceFile$ - the filename of a file to attach. This is the BR filename (the function automatically converts it to an OS Filename.)

The function returns 1 when the email was sent successfully, or 0 if it wasn't sent successfully.

In order to use this function, you must have the emailcfg file layout in your layouts folder and you must have a copy of SendEmail.exe which is free and can be downloaded from the internet. Both of these files are included with the latest update of fileio.

You also have to configure fileio with the authentication information for your email server.

To configure your email server, simply run FileIO to get the data crawler, then select the emailcfg file layout and press F5 to edit it. Add a row if the file is empty.

Simply fill in the information the file is asking for in the appropriate fields and save the data, and then test sending an email to make sure it worked.

More information about sendEmail.exe is available from the author's product site here: [http://caspian.dotconf.net/menu/Software/SendEmail/ http://caspian.dotconf.net/menu/Software/SendEmail/]

==== fnClientEnv$ ====

This function returns the value of a Windows Environment Variable on the client under Client Server.

''fnClientEnv$*255(EnvKey$)''

*EnvKey$ is the name of the Windows Environment Variable to check on the client.

The function returns the value of the entered environment variable.

==== fnClientServer ====

This function returns true if you're currently running in Client Server mode, and false if you're running in the old "native" mode.

==== fnEmpty & fnEmptyS ====
These functions test if the passed in array is empty or not..

The syntax is:

''fnEmpty(mat Numeric)''

or

''fnEmptyS(mat String$)''

Example:

def fnSomeFunction(String$,mat Array$; mat OtherArray)
if fnEmpty(mat OtherArray) then
! Arrays were empty.
end if
fnend

==== fnReadScreenSize ====
This function reads the screen size of the given window (or window 0 if a window wasn't passed.) This is useful for centering a window on the screen, or for making sure window 0 is big enough for the child window you're trying to create.

The syntax is:

''fnReadScreenSize(&Rows,&Cols;Window)''

*Rows & Cols - returns the screen size in rows and columns.
*Window - the window to interrogate. If not given, assumes [[Open_Window#Comments_and_Examples|Window 0]].

==== fnBuildProcFile ====
This function builds a proc file to be executed later. This function and the next simplify the process of executing code in a proc file. It can even be used to spawn a new session of BR.

To use it, call fnBuildProcFile one or more times and specify some lines of code to execute.

''fnBuildProcFile(Command$*255)''

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnRunProcFile ====

This function spawns a new copy of BR and in it, runs the proc file that you've previously built using fnBuildProcFile (above).

'' fnRunProcFile(;NoWait) ''

The optional parameter "NoWait" causes the other session to spawn and run in a new thread. If you don't specify NoWait, the current session pauses and waits for the other session to close before proceeding.

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnLog & fnErrLog ====
These next two functions are functions to aid in logging. When you call either of these two functions, you give them a string that you wish to log. They will open the FileIO Log File and add a record to the end of it containing some user information such as login_name and session$, and the string that you specified. FnErrLog does the same thing as fnLog except it also logs the Error Number and the Line.

The syntax is:

''FnLog(string$)''

*String$ - the Log Message

''FnErrLog(String$)''

*String$ - the Log Message

==== fnLogArray ====

This function logs the given arrays to the log file, logging each field in the arrays. Its useful for recording, for example, an entire data record that is about to be written to a data file.

The syntax is:
''fnLogarray(mat F$,mat f;Message$*512,CallingProgram$*255)''
The first two parameters, of course, are the array to log. The third parameter is an optional message to be recorded along with the array, and the fourth optional parameter is the CallingProgram$ to save in the log along with the message. (The CallingProgram$ parameter can usually be passed as the system function Program$)

==== fnSetLogChanges ====
This function works in conjunction with the next function, and they're for recording just what changed in a data file. When the file is read, you call fnSetLogChanges and record the "before" picture of the file record.

After changes have been made and saved back to disk, you can call fnLogChanges below to record the actual changes.

The syntax is:
''fnSetLogChanges(mat F$,mat F)''

==== fnLogChanges ====
This function is the other half of the function above. It compares the given arrays with the ones set previously in the above function and checks for changes. Then it generates a log message recording information about just the items that changed.

The syntax is:
''fnLogChanges(mat F$,mat F;Message$*1024,CallingProgram$*255,Layout$)''

You need to pass in the same two arrays as before, but this time the modified versions of them.

You can also optionally pass a 1024 byte log message to record with the log entry.

CallingProgram$ again should be passed as the system internal function Program$.

The final parameter allows the passing of a Layout$. If you pass a Layout$, that layout is read and the subscripts are used when making the log message of changes, so that its easier to read. If you pass a layout, it will identify the changed fields by name. If you don't it will identify those fields by relative position number.

==== fnViewLogFile ====
All of the above functions store the information by default into a BR internal file defined in the filelay\logfile layout.

The fnViewLog function uses fnShowData to call the Data Crawler to display the FileIO Log File in a searchable listview.

''fnViewLogFile(;ShowQuit,ShowColumns,ShowExport)''

*ShowQuit - Show a quit button on the UI (if off, ESC will quit).
*ShowColumns - Include a button to allow the user to select which columns to view.
*ShowExport - Include a button to export the log file to CSV.

==== fnReadLockedUsers ====

This function returns a list of all users using the locked data file.

''fnReadLockedUsers(mat Users$)''

*mat Users$ - the list of users is returned here

==== fnDisplayLength ====
This function calculates the display length of a field based on its form spec.

''fnDisplayLength(Spec$)''

*Spec - the Form Spec to return the display length of.

==== fnLength ====
This function calculates the length on disk of a field based on its form spec.

''fnLength(Spec$)''

*Spec$ - the Form Spec to return the length of.

==== fnStandardTime$ ====
Converts Military Time to Standard Time. Returns Standard Time$

''fnStandardTime$(MilitaryTime$;Seconds)''

*MilitaryTime$ - Time in 24 hr format.

==== fnMilitaryTime$ ====
''fnMilitaryTime$(StandardTime$;Seconds)''

*StandardTime$ - Time in AM/PM Format

==== fnCalculateHours ====
Calculates the difference between 2 specified times.

''fnCalculateHours(TimeIn$,TOut$,DaysIN,DaysOut)''

*TimeIn$ - From Time
*TimeOut$ - To Time
*DaysIn - Days Start
*DaysOut - Days End

==== fnBuildTime$ ====
Builds a time in the format used by the above functions.

''fnBuildTime$(H,M,S,P;Military,Seconds)''

*H - Hours
*M - Minutes
*S - Seconds
*P - Boolean indicating AM/PM - 0 is AM, 1 is PM
*Military - Flag indicating weather desired result is in Military Time or not
*Seconds - Flag indicating weather to count seconds or ignore them. (1 means count seconds)

==== fnParseTime ====
Takes a time and pulls out the values

''fnParseTime(T$,&H,&M,&S,&P)''

*T$ - the time to parse
*H - Return value for Hours
*M - Return value for Minutes
*S - Return value for Seconds
*P - Return Value for AM/PM

== FileIO fnSettings (Global Settings Code) ==

The FileIO library can be made to implement certain policies across the board. These are established by creating a file called fileio.ini and typing statements like the following into it. This file is "PROCed", so you don't want to put line numbers in it.

Anything you don't specify in fileio.ini will take its default value, shown below. So you only need to specify the items that you want to be different.

Note, for the boolean settings below, 1 denotes TRUE and 0 denotes FALSE.

let EnforceDupkeys=1 ! Enforce that key number 1 is unique key
let Defaultfilelayoutpath$="filelay\" ! Path To Your File Layouts
let Promptonfilecreate=1 ! Ask User Before Creating New Files
let Createlogfile=0 ! Use Logging
let StartFileNumber=1 ! Set above 300 to avoid conflicts with legacy programs.
let CheckIndex=0 ! Automatically Verify Indexes (slow)
let CompressColumns=0 ! Shrink or Expand Columns in Data Crawler by Default
let MaxColWidth=20 ! Max Default Column Width in Data Crawler
let LogLibrary$="" ! Defaut Log Library, defaults to None
let LogLayout$="" ! Log file layout, defaults to Internal File
let AnimateDatacrawler=1 ! Use ScreenIO Animation for Datacrawler
let TemplatePath$="filelay\template\" ! Default Template Path
let IgnoreLayouts$="" ! List any Ignore Layouts here.
let CloseFileSimple=0 ! Use simple comparison for fnCloseFile

==== EnforceDupkeys ====

Turn on the EnforceDupkeys option to force that the first key listed in your file layouts is a unique key. FileIO will generate the standard BR error for Dupkeys when attempting to create indexes if it is not unique.

==== DefaultFileLayoutPath$ ====

Use the DefaultFileLayoutPath option to specify the path from your programs to your file layout folder. The default is "filelay\". Use this setting if you want to place your file layouts in another folder from the default.

==== PromptOnFileCreate ====

Use the PromptOnFileCreate setting to cause FileIO to display a message box whenever it is attempting to create a new file. This happens during the automatic update procedure, as well as during any attempt to access a file that does not exist. This setting should be turned off in your live system, and only turned on for development purposes. If you use the message box to cancel creating of the new file, then the file is not created, and fileIO or your application will most likely give an error when you attempt to actually access the new file.

It can be useful during development to make sure that you don't accidentally create the wrong files, due to an incorrectly specified path or a typeo in the filename in the layout file. However, in a live system, these things have already been tested, and you generally want the default behavior, because you don't want your users to have the ability to cancel the normal operation of FileIO.

==== CreateLogFile ====

Use this option to specify weather or not to use the FileIO log file. If it is turned on, a log file called FileIO.log in the current directory is created with entries listing all attempts to open a file, automatically update one, or automatically update your indexes.

==== StartFileNumber ====

Use this option to set the starting file number that the fnGetFileNumber and the fnOpen functions use to search for available file numbers. This is so that if you have certian reserved file numbers in your code, you can make sure that FileIO will not use those reserved file numbers, causing a conflict with your already existing programs. The default is 1, which is fine if your software does not have any reserved file numbers.

The allowable BR file numbers are 1-200 and 300-999.

==== CheckIndex ====

This function is used for Partial FileIO Implementations. If all of your software uses FileIO then all of your indexes are kept automatically up to date by the FileIO library and BR's internal file processing systems. However, if some of your programs do not use FileIO, and you use the FileIO library to add a new index file that those other programs do not know about, then its possible for the additional index file to become out of date when the master file is updated by your other programs.

Use this setting to cause FileIO to check the DateTime stamp on all your index files when opening a new file, and automatically update any indexes that may have potentially gotten out of date from other programs.

This option slows down the processing of the fnOpen function, particularly when running under client server over the internet. If you know that every program in your application suite uses FileIO, and that any programs that do not use FileIO still properly update all the indexes that your data file uses, then you can safely leave this setting turned off, and optimize your performance when opening several files using the fileIO system.

==== CompressColumns ====
This instructs the datacrawler to use smaller widths for small columns. If CompressColumns is false, the data crawler will make the column the width of the field or the width of the caption, whichever is wider. If CompressColumns is true, it will use the width of the field, not the caption.

==== MaxColWidth ====
This limits the column width to a set amount. This is applied after CompressColumns above.

==== LogLibrary$ ====
If a library is specified here, then fileio looks for a BR library with the specified name, and attempts to call a library function in it called fnFileIOLog that. This function should expect six parameters, which are Logstring$, Login_Name$, Session$, Days of Date$, Time$, and CallingProgram$, if LogLayout is also nonblank.

If you specify a LogLibrary and LogLayout is blank, then it calls your function giving it only 1 parameter.

It will call your function '''''instead of''''' the normal log file. Use this to implement your own logging functions however you want.

==== LogLayout$ ====
Use this setting to specify an alternate file layout for an alternate file to do the logging in. Base the file layout for this file on the logfile we supply for you in the filelay folder. It should have at least those fields, which our log routine will automatically populate, but you can add other fields if you want (though you will need to manage them yourself).

If you don't specify LogLayout, the default filelay\logfile will be used. This will allow you to also use the fnViewLogFile function to access it.

==== AnimateDataCrawler ====
The sister library [[ScreenIO]] has a feature that allows you to use an animation of a clock in your loading screens in your own programs. If you have [[ScreenIO]] then FileIO will automatically detect it and use it to display a loading animation while the data in the data crawler loads.

Set AnimateDataCrawler to false (0) in your fileio.ini file to bypass the animations if you do have screenio but don't want to see the animations anyway.

==== TemplatePath$ ====
This setting points to the folder that contains the code templates used by the Generate Code button on the main page of the Data Crawler.

==== IgnoreLayouts$ ====
This is a comma delimited list of all layouts that you wish to suppress from appearing on the main page of the data crawler. You can still access these layouts with your code, but they won't be listed in the data crawler for you to access.

Whatever you're using for a log layout, is automatically added to this list.
==== CloseFileSimple ====
The fnCloseFile function closes all the individual handles to a data file that was opened for output using multiple keys.

For BR 4.18 and higher, we support a better algorithm for detecting which files are matches for a given opened file number.

Set CloseFileSimple to true (1) to force it to check the old way.

== FileIO Add-on Packages ==

Many FileIO Add-on packages are currently in the works.

=== ScreenIO Library ===

The [[ScreenIO Library]] is a sister library to the FileIO library. The ScreenIO library requires the FileIO library in order to run.

The ScreenIO library is a complete Rapid Application Design tool that enables you to implement custom screen functions anywhere in your exiting programs.

If you call the ScreenIO Library as a function library, you call a function called fnFM and tell it which screen you wish to use. The ScreenIO library loads your user interface, loads your data files, and preforms all the file maintenance operations you have designed into your screens.

You can find out the latest information about the ScreenIO library in the ScreenIO page.

=== Audit BR ===

The [[AuditBR|Audit BR]] developer tool makes a backup copy of your file layouts. Then you run some code you're trying to test, and finally, run Audit BR again, to get a report showing all the changes to any of your data files automatically.

AuditBR is now included directly in FileIO. To use it, select the layout from the list of layouts in the Datacrawler and press the "Compare" button.

== What’s New (also described above) ==
=== 2018 ===
*Support for dates in any storage formats on disk (v2.48)

=== 2015 ===
*Added Rec to display for fnShowData
*Added FormStatement$ for debugging of form statements inside fileio
*Added mat BadRead$ for debugging of 726 errors when making new layouts
*Fixed a bug causing crash when logging things from long program folders
*fnClientEnv$ - reads a Windows Environment variable on the client using the command shell
*fnAskCombo$ - added an optional parameter to set default selection.

=== 2010 - 2014 ===
*FileIO now caches your file layouts in memory to make it much faster then before when opening the same data file in multiple programs.
*Generate Layout Wizard
*fnShowData
*Improved Logging
*fnViewLogFile
*Import/Export
*Import/Export by Function
*Many other speed increases
*if ScreenIO is present, Datacrawler uses the animation routines
*fnBuildProcFile & fnRunProcFile
*fnGenerateLayout & fnWriteLayout
*fnReadForm$
*fnReadFormAndSubs
*fnGetFileDateTime$
*fnReadLayoutPath$
*fnSortKeys
*fnSetLogChanges
*fnLogChanges
*fnLogArray
*fnReadScreenSize
*fnEmpty
*fnEmptyS
*Many other useful functions that were added to the documentation at earlier dates.

=== Spring 2009 ===

'''''New Functions:'''''

The FileIO Library has been updated in Spring 2009 to provide several new functions:

*fnReadRecordWhere
*fnKey$
*fnBuildKey$
*fnReadUnopenedDescription$
*fnUpdateFile
*fnDisplayLength
*fnLength
*fnReadLayoutHeader
*fnReadEntireLayout

'''''Speed Increases:'''''

Thanks to the BR [[Profiler]], we have increased the speed of FileIO fnOpen function by ten times when running over a LAN and by 100 times when running over the internet using Client Server.

In order to get the new Speed Upgrades, you will need to make sure that you use the latest copy of the [[#fnOpen_Function|fnOpen]] function in each one of your programs that use FileIO.

'''''Network FileIO:'''''
This version of FileIO has been optimized to work better in network situations.

'''''FnSettings: '''''
There are more configuration options in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine.

'''''Automatic Update Speed Fix:'''''
The automatic update proceedure has been made to run more then 100 times faster then before according to our benchmarking tests.

=== Fall 2008 ===
'''''DataCrawler Grid:'''''

By popular request we added a read/write version to the data crawler. This version works exactly the same as the datacrawler did before but it displays all the contents of your data files in a grid instead of a listview.

When you run the fileIO library as a program, it launches a tool known as the [[#DataCrawler|DataCrawler]]. The DataCrawler shows a listview displaying all your layout files in it. If you select one, it builds another listview with all the data in your selected data file.

If you are looking at the first list of all your file layouts, and you press F5, a grid will be build displaying all the data in your data files. You can change any of the records you like, and when you're done, your changes will be saved to the data file. Additionally, you can Add or Delete records using the buttons at the bottom. Any changes you make are not written to the disk until you click the "Save" button. If you press ESC (Cancel) the grid is closed and all changes you made sinse the last save are lost.

This tool is for programmers only. Do not give your end users access to the DataCrawler.

Use the DataCrawler at your own risk. Gabriel Bakker and Sage AX are not responsible for any harm that comes to your data files through the use of this or any other tools we offer.

The DataCrawler is not designed to be used to maintain your data files. It can be used carefully to correct small things in your data files.

'''''Support for Nonstandard Paths:'''''

Many BR Vendors keep different versions of the same data files in different locations. For example, sometimes a BR vendor will use a different Data folder to represent data for different Warehouses, or Customers. In cases like this it is necessary for your programs to specify the path to your data files. They may do so by specifying the optional "PATH" parameter to your data files. See the section [[#fnOpenFile]] for more information.

'''''Support for Nonstandard Layout Files Path:'''''

Old versions of the fileIO library required you to place all your file layouts in a subfolder of your program directory called "filelay". We have now changed the Fileio library to allow you to place your file layouts any place you want. The only requirement is that they are all together in one folder by themselves.

If you use a nonstandard path in the fileIO library, it is necessary to make a change to the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code in your copy of fileio.br.

'''''Prompt on Create:'''''

The FileIO library automatically creates any data files that it can't find. This was done to make it easier to deploy your finished programs - if you had any empty data files you could omit them from the packages and they would be created when they were needed, on the fly.

The current version of the FileIO library contains the same ability. However, it prompts you before creating any data files. This helps to avoid bugs that happen from incorrectly specifying the path to your data files.

However, if you do intend for your data files to be autocreated, then you probably don't want your end users to modify them. Therefore, you can use the PromptOnCreate setting in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code to specify. If this value is set to true, then the fileIO library will prompt you whenever it attempts to Autocreate a data file. If it is set to false, then the fileIO library will create the data files without prompting you, like it always did before.

'''''fnSettings:'''''

The newest version of the FileIO library supports some features that require you to specify Global Settings values. These are done by modifying the contents of the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine at the beginning of the fileIO library.

=== Fall 2006 ===
Many improvements have been made in the FileIO library over the summer. This section is intended to acquaint you with the highlights of those changes. Most of these improvements were built from ideas generated during the discussion at the April conference.

'''''Intermixed String and Numeric Specs:'''''
The File Library has been expanded to allow the reading of data files that contain mixed string and numeric specs. This is to aid those of you who are planning on implementing the FileIO Library on existing data files which may not be organized with strings first and numbers second.

The central idea of the FileIO Library is based upon the reading of your data files into a String and Numeric array. This will enable you to refer to the fields in your file by using a named subscript, saying F$(FM_NAME) to refer, for example, to the farm file’s name field. The advantage to this is that when you change the file layout, all your existing programs will not have to be modified, because they will only be looking at F$(FM_NAME). If the name field changes from the third string field to the fourth, the value of FM_NAME will also change, and you won’t have to worry about updating your data files.

However, in order to support the reading of a data file with intermixed string and numeric specs, the generated form statement will actually calculate the position of any fields that are not in order, so that the file read statement will still return all string fields first (into your string array) and the numeric fields second (into your numeric array). You do not need to worry about this; the library does it for you. All you have to do is read your file and use the data values.

The only thing that is required is making sure that all your string subscript names end with a “$”. This will tell the library that they are strings. Thank you, George, for this suggestion.

'''''Versioning / Automatic Updates:'''''
The file layouts have been expanded to contain a version number. This version number will be used to determine when a file needs to be updated. The version number is the third parameter in the file layout.

Any time you wish to change your file layouts, simply increment this version number. Each time the library attempts to open a data file, the file’s version is checked and compared with the version in the file layout. If the file layout has been changed (if the version in the file layout is greater then the version in the file) then the file will be updated to the latest version. Depending on the file size this may take a couple of moments. A simple progress bar will be displayed on screen while this is happening. The progress bar will be displayed in its own window, so it should not affect anything your programs may have had on screen.

The library uses the following procedure for updating a file. First, the file is copied to a backup file (prefixed by the letter ‘o’ for old). So color.dat would become ocolor.dat, and color.key would become ocolor.key. Then the new file is created and marked with the proper version number. (color.dat, color.key). The old file is opened in read-only mode, and the new file is opened for OutIn. The update routine actually reads through the old file layout, and one record at a time creates a new record, using the new file layout, with the same data, saving it to the new data file.

When it is done upgrading, the progress bar window is closed, and the file is reopened in the fashion you described in your call to fnOpen, and flow returns to your program as though nothing unusual has happened.

If an error occurs during processing, the routine will do what it can to roll your data files back to the previous version, but please make frequent backups of your data files anyway, just to be safe.

'''''Error Checking – If there is a mistake in the file layout:'''''
The routine attempts to discover the cause of the error in the case that one is encountered due to a missing file, a file sharing violation, or an invalid or corrupt file layout. If this should happen, the program is paused, and a text message is printed out explaining the most likely source for the error, including what part of the file layout, if any, may have caused the error.

You may then examine the printed text, and the contents of the BR system variables ERR and LINE to determine the problem. If you type “GO”, the next line will be execute “system”, ending your program.

If the file was in the middle of an upgrade when the error happened, it will be automatically rolled back to the previous version, so that when you fix the problem and try to run your program again, the file will again attempt to update from the beginning, and you won’t have to worry about corrupted data.

However, please backup your data before upgrading your data files anyway, just to be safe.

'''''Implementation of Keys / Creation of New Data Files:'''''
The library has been expanded to automatically create all new data files, and to automatically update any existing files. This means that in the file layout header, two new fields that were previously ignored are no longer ignored. The RECL value that you specify in your file layout will be used, along with the description/definition of your keys file. When you open a new file (or update an existing one), the library will calculate the proper kps and kln by evaluating the key description. This key description must match up with subscript values from the data elements in your file, and more then one may be specified, but they must be separated with slashes (/). If I wanted my Farm File to be keyed based on CODE and NAME, the proper key description would be:

farm.key, CODE/NAME

The library will then look up the position and length on disk of the CODE and NAME fields and put them together to create the proper keys during an update or creation of a new file.

'''''DataCrawler:'''''
Perhaps the most exciting new addition to the library is the addition of a programming tool I like to call a DataCrawler. If you run the FileIO Library directly as a program, instead of using it as a library, it will function as a DataCrawler. The DataCrawler requires a New Gui version of BR, as it requires a ListView to be able to properly and easily display the data in your files.

If you run it in an older version of BR you will get a message, telling you to run it in a newer copy. If you run it in a New Gui version of BR with CONFIG GUI OFF, then GUI will be turned temporarily on for the use of the DataCrawler and then turned off again when you are finished. If you run it in a New Gui version of BR with GUI ON, it will just run normally.

When you run the DataCrawler, first you will see a ListView displaying every file layout it can find in the filelay folder. If you select a file, the DataCrawler will open a large ListView with as many columns as there are fields in the file. The Column Headings will come from the element descriptions in your data files, and the column widths will come from the displayed width of the fields. There will be a row for every record in your data file, and you can resize the column widths, and scroll around the data file to view the raw data of your BR data files on disk.

If you are dealing with a particularly enormous data file (50,000+ records) it can take a moment to populate the ListView with the data in your data file. You may hit ESC to stop loading if you like, and view only the already loaded records.

If you would like to look up a particular record (based only upon the primary key for the data file), you may press F4. This will give you a window which asks you to input the key or partial key. When you press enter, the file will be reloaded, starting at the key you specified and continuing on to the end of the file, or until you press ESC. The records you are looking for should appear at the top of the ListView.

To reset the ListView and look at the contents of the entire file again, simply press F4, and enter a blank (“”) key.

Finally, as with any ListView, you may resort your data by clicking on any of the column headings. Then you can use the slider bar at the right to scroll down to the record you desire.

This is a programming tool and is not designed to be used by an end user. This tool will open your file in read-only mode. It will not allow you to modify the data; I leave that as an exercise for the reader. However, it will update any datafiles you view to the latest version (if they need to be updated) when it opens them, just as any other program that uses the library will do.

== Appendix (Examples)==

=== Example.br ===
00010 ! example.br - This program is an example of for the data reading simplification
00020 ! Copyright April 2006 by Gabriel Bakker
00030 ! Distributed open source as a Christmas gift to brag members
00040 !
00100 execute "config gui off"
01020 DIM form$(1)*255
01030 DIM color$(1)*255,color(1)
01040 DIM colorcat$(1)*255,colorcat(1)
02020 library "fileio": fnopenfile, fnreaddescription$
04000 !
04010 Openfiles: ! Open your files here
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)
06000 ! gosub WriteFiles ! If you want to test this line, make sure to drop flag from 4030
07000 !
07010 MainBit: ! This'un here's tha Main Bit
07030 RESTORE #ColorFile:
07100 ReadNextcolor: ! Read next record
07120 read #ColorFile, using form$(ColorFile) : mat Color$, mat Color eof EndReadColor
07180 PRINT Color$(co_name)&" ("&Color$(co_html)&") is a member of the '";
07190 PRINT trim$(fnReadDescription$(ColorcatFile,cc_Name,Color$(co_category),mat Colorcat$,mat Colorcat,mat form$))&"' category."
07290 goto ReadNextColor
07300 EndReadcolor: ! Finished with Color File
08000 STOP
25000 !
25010 WriteFiles: ! Uncalled routine to demonstrate writing files
25105 let color$(co_code)="GD" !:
let color$(co_Name)="Gold" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFD700"
25110 write #colorfile, using form$(colorfile): mat color$, mat color
25115 let color$(co_code)="LV" !:
let color$(co_Name)="Lavender" !:
let color$(co_Category)="BL" !:
let color$(co_html)="E6E6FA"
25120 write #colorfile, using form$(colorfile): mat color$, mat color
25125 let color$(co_Code)="OR" !:
let color$(co_Name)="Orange" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFA500"
25130 write #colorfile, using form$(colorfile): mat color$, mat color
25205 let colorcat$(cc_Code)="YL" !:
let colorcat$(cc_Name)="Yellows" !:
let colorcat$(cc_html)="FFFF00"
25210 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25215 let colorcat$(cc_Code)="BL" !:
let colorcat$(cc_Name)="Blues" !:
let colorcat$(cc_html)="0000FF"
25220 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25300 return
40000 !
40010 Open: ! ***** Function to call library openfile and proc subs
40020 def fnOpen(FILENAME$, MAT F$, MAT F, MAT FORM$;INPUTONLY,KEYNUM,___,INDEX)
40025 dim _FileIOSubs$(1)*50
40030 let fnopen=fnopenfile(FILENAME$, MAT F$, MAT F, MAT FORM$,INPUTONLY,KEYNUM,MAT _FileIOSubs$)
40040 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
40090 fnend
50000 !
60000 Ignore: Continue

Color File Layout
color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

ColorCat File Layout
colorcat.dat, CC_, 0
colorcat.key, CODE
recl=127
===================================================
CODE$, Category Code, C 6
NAME$, English Name for Color, V 30
HTML$, HTML Code for the Color, C 6

Example Layout showing multiple keys (price)
price.dat, PR_, 0
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2

[[Category:Utilities_Third_Party]]

FileIO Library

2024-09-11T13:26:07Z

Gordon.dye: /* How it Works */

The '''FileIO''' Library began as a project to find a way to reduce the headache associated with making changes to data files. In my experiences working for [[BRC]], I had to make a change to the commun file, a data file that stores information about communication with EDI VANs. I added some new fields, and removed a couple of old fields, and then I began searching through the BRC program suite to find and modify each program that referenced this data file in order to update it with the proper new form statement. This task quickly became daunting as I noticed that out of BRC’s program suite of over 600 programs, more than one third of them referenced the commun file. With 223 programs to modify, the task was given up as hopeless and tabled indefinitely.

I am happy to announce that we have solved this problem. When I have to make a change to a data file layout for my customers today, I can complete the task in under 1 minute, and not a single program needs to be changed in order to continue working with the new file layout. In fact, I don’t even have to update my customer’s data files, as the FileIO library takes care of this for me as well.

The trick is to define your file layouts in an ASCII text file layout file that I will tell you about in a minute. The FileIO Library will actually parse through your file layouts, and it will instruct your programs how to read the data file, so that you don’t have to. It will also automatically detect when you make changes to the file layout, and it will update your customer’s data files on the fly to make sure they have the latest version. Finally, it even contains a DataCrawler that you can use to examine the contents of any of your BR data files in a raw format.

For more information about the FileIO Library visit the [http://www.sageax.com/products/fileio-library/ Sage AX Website]

To download the latest copy of FileIO, click [http://www.sageax.com/downloads/FileIO.zip here.]

== Method of Operation ==
The file IO library parses a formatted text file layout and uses this information to structure the opening and initializing of the reading of a file “object”. The word object here is used to refer to all the data in a given record layout in one of your files. This library is easy to use, and provided you follow some simple standards, it will simplify your life immensely.

Your programs will need to define one array for all [[Form|file layout form statements]] and add a snippet of code (given below) to the program for interfacing with with the library. For each file you will need to define a couple of arrays and use the library to open them. From that point on access to data is simple and direct.

=== File Object Arrays ===

First, in your program you must create two arrays to store the file information. If we are dealing with the Color File these would be MAT COLOR$ and MAT COLOR. One will store all the string information about a color, and the other will store all the numeric data. Our working example will involve two files: a Color File and a Color Category File. You should dimension these to:

01030 DIM color$(1)*1000,color(1)
01040 DIM colorcat$(1)*1000,colorcat(1)

We're dimensioning the string arrays to 1000. This is the length of one field in the color file. It needs to be at least as big as the largest string field in the data file.

However, it is recommended to make sure the length is long enough to handle any field you might eventually add to the file at any point in the future. BR supports multi-line textboxes, so I sometimes add long memo fields to my data files that might be 400 or 800 or even 1000 characters long, therefore 1000 is the length I use now in all my new development.

But anything will work as long as its long enough to handle the largest data field in your file.

=== Forms Array ===

Your programs will need a string variable array to store the form statements associated with reading files. This form statements array will be dynamically generated or expanded whenever the a file is opened. It will say:

01234 DIM form$(1)*255

This form statement will be compiled by the FileIO open statement. BR limits all form statements to 255 bytes, so 255 is sufficient to hold the compiled Forms$ statements.

=== Library Linkage ===

You will also need the library statement:

02020 library "fileio.br": fnopenfile, fnreaddescription$

=== fnOpen Function ===

Now, add a snippet of code to interface with the library.

Because BR libraries do not share global variables with the programs they are called from, we will need to execute a proc file whenever we open a file to set the names of all our variables after we return. Add the following snippet of code into your program. It will create an FnOpen function that calls the library and runs the proc file. The $$$ at the end of the procfile name tells the procfile to self-destruct after execution. Since this procfile is used simply to return variable information back from the library to the main program, we don’t need it sitting around collecting dust.

99010 OPEN: ! ***** Function To Call Library Openfile And Proc Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
99030 dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
99050 if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
99060 fnend

Or, for those with [[Lexi]]:
OPEN: ! ***** Function To Call Library Openfile And Proc Subs
def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
fnend

=== Using FileIO in Your Programs ===
Now you are ready to process files. 
'''''You simply open the files by saying:'''''

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

'''''read each file as follows:'''''

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
'''''and access the data:'''''

30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name)

=== How it Works ===
The above statements tell the File Library to look in the filelay folder to find the file layout for the Color File, and read it to find out what the Color File looks like. Then it OPENs the Color File, and sets MAT COLOR$ and MAT COLOR to the correct number of elements to hold an entire color record. Finally, it will define several variables that we can use as pointers (subscripts) into these arrays to access the data read into the 2 arrays, and it will assign the file handle to a variable called "colorfile".

The second open above will do the same thing to the color category file, except the 1 parameter value tells the function to open readonly. The array subscripts populate procedure (passed back from Fileio) will be executed, thereby assigning values to the subscript names in the calling program. So, if I had a file layout such as the following:

color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

Then the functions would do the same thing as the following individual lines of code (assuming the next available file handle was 5):

DIM FORM$(5)*255
DIM COLOR$(9)*1023, COLOR(1)
OPEN #5: “Name=color.dat, kfname=color.key”,internal,outin,keyed
LET FORM$(5)=”form C 6,V 30,V 6,C 6”
LET FORM$(5)=CFORM$(FORM$(5))
LET COLORFILE=5
CO_CODE=1
CO_NAME=2
CO_CATEGORY=3
CO_HTML=4

The data is used by referencing the file array, with the subscript name, so the color’s description becomes color$(co_Name).

In the old days, if we wanted to change the file layout of our file, all of the programs that used that file would have to be changed one at a time to use the new file layout. Also, if the order of the fields changed, then all the programs would have to also be changed to use the new fields.

But now, using this function, we can change the file layout all we want. If we later want to insert a field into the file layout before color name, I won’t have to look at this program again; this program will just work fine, because the library maps the subscripts to the actual fields.

Also, the code is easier to read and maintain.

=== Example ===
The whole thing looks like this:

01025 ! Dimension the Arrays
01030 DIM color$(1)*1023,color(1)
01040 DIM colorcat$(1)*1023,colorcat(1)
01050 DIM form$(1)*255
02000 !
02020 library "fileio.br": fnopenfile, fnreaddescription$
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$) ! Open the file
05000 !
30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore ! Read the file
30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name) ! Use the data by referincing it in the file arrays
80000 !
90000 ! Every program using fileio needs the following code
99010 OPEN: ! ***** Function To Call Library Openfile And Generate Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths)
99030 dim _FileIOSubs$(1)*800
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$)
99050 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
99060 fnend

== File Layouts ==
Now lets inspect the anatomy of a properly formatted file layout. These should be placed in a subdirectory called filelay.

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...
<hr>
price.dat, PR_, 1

The first line contains the name of the Farm File, a unique string to prefix all of your subscript pointers, and the file version number. The subscript value is to ensure that the program knows the difference between the Farm File’s Farm Code, and the Route File’s Route Code. (One will be RT_CODE and the other is FM_CODE). These are separated by a comma. Spacing does not matter, so adjust your spacing so that it looks nice.

The Version number is used to determine when the data has changed, and an update needs to be made to your data file. Your file layouts should all start at version 0, and each time you want to make a change, you may increment this value by 1.

Each time you open a file with the FILEIO library, it reads the file version number of the file on disk (using the BR version() function), and then it compares it to the version number in your file layout. If your file layout has a higher version number then your existing data file, then the library opens the backup of the file layout for the version of the data file that exists on disk. It makes a backup copy of the existing data file, and creates a new file with the proper version number. Then it reads your records one at a time, and copies all the data from the old file into the new file one field at a time. If a field is dropped from the file layout, that data gets lost. If fields are rearranged, the data is copied and saved in the new file in the new positions. If a new field is added, it starts out blank (or 0).

If you look in the filelay folder, you will notice a version folder. This contains several files ending with a number. For example you may see a color.0, and a color.1 file.

If you run the fnopen function and it can not find your data file (usually because this is a new file and it hasn’t been created yet), ''the library will automatically create your file,'' based on the information you give in the first part of the file layout.

Also, whenever you make changes to your file layout, the function library will automatically update the data files on disk for you. It does this by renaming the old file, creating a new one with the new version number, and then copying the data from the old one to the new one a record at a time.

Any time it creates a file, or updates the file on disk, it creates a backup of the file ''layout''. The first time you run a program that tries to read your new data file, it will create the data file for you and make a backup of the layout, and if the number in your file layout is 0, then it will create, for example, a filelay\version\price.0 file, a backup of your file layout that the library uses to figure out what has changed the next time you try to update the file.

If you wish to make any changes to this data file, first you increment the version number, (in this case make the 0 into a 1). Then change the file layout all you want. You may rearrange fields, add new fields, add or remove keys, or change the record length.

The only step necessary for having your data files updated is to increment the version number every time you make a change to the file layout.

You may make any changes you like to the file layouts, but do not change the names of your existing subscripts. If you change the subscript name, not only will all the programs that reference that subscript be broken, but additionally, the routine will not understand that you are changing the name. It will think you are dropping the old field and adding a new field and any data stored in this location will be lost when the file is updated.

price.key, FARM

The second line contains the name of the first key, and a definition telling what the key is based on. These are separated by a comma. The key definition is made up of each of the subscript names in this file that form the keyfields for the file. When the library is called to open a file, if the file does not exist, or if it needs to be updated, a new one will be created. The function will read these subscript names that form your key definitions, and it will calculate the proper key position (KPS=) and length (KLN=) values. Then the create routine will use this information with the Index command to create the new key files.

price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127

Notice that the third key is based on three different fields. These are separated by a “/”. It is important that you use a “/” to separate your keys when you are building a key out of more then one field, because the function uses this “/” to help it make the proper BR syntax for defining complex key fields.

Also, note the "-U" at the end of the fieldname in the 4th key. This indicates that the "Description" part of that key is case insensitive. This translates to using the "U" on part of your key spec in Business Rules.

The file can have as many keys as you want. The function will keep parsing key file names until it reaches the next part of the layout. It opens any OutIn files with all keys so that any changes you may make to the data stored on disk will be properly reflected in all the key files.

The optional RECL= Parameter is read and used whenever a new file is created or an old one is updated. If it is not specified, the record length is calculated from the fields in the layout.

===================================================

The next line in the file is skipped by the parsing routine, and its purpose is to make the file layouts more readable to a programmer.

 
FARM$, Farm Code (or blank), C 4

Following the file and key structure, the fields are defined. There are three parameters on each field definition line, and you make one line for each field in your file layout. The first parameter is the subscript name that you will use in your program to refer to this data element. Place a $ at the end of the subscript name for all string elements. Don’t place anything at the end of the subscript name for numeric elements. Note that each of these names will be prefixed by the second parameter of the very first line of this layout.

The second parameter is the description. This description is for the benefit of the programmer, so when the programmer is reading the file layouts, (s)he can tell which field does what. The spaces are ignored, so you may include as many spaces as you wish to make the layout look good. It does seem like good general guidelines would be to limit your layout lines to 255 characters and your descriptions to 80.

The description is also used by the built in DataCrawler, a program that reads any of your data files and displays the entire contents in raw form in a listview. The Descriptions become the headings for each column in the listview.

Those descriptions are also used for the default captions for your fields if you use ScreenIO, a library for building GUI programs that itself builds off of fileio.

The third parameter is the form statement, which is pretty straightforward. Any items with a form statement of type “X” will be ignored, except that the length will still be used to calculate the position on disk of all remaining fields in the record. The library will take X fields into consideration when building the form statement, but not at any other time.

The fourth parameter is optionally a [[#Support for Dates|Disk Date Format]]. You can specify DATE(Julian) if you're storing your dates in Julian format on disk. Or you can specify DATE(cymd) or DATE(ymd) or DATE(mdy) or any other valid date spec here, and FileIO will treat this field like a date.

Your programs will still have to unpack it for you, fileio can't do that because fileio doesn't read the file for you.

However, the data crawler, the automatic updates, and screenIO, are all compatible with these dates specified in your file layout.

If the fourth parameter is anything other then DATE(format), then its treated as a comment and ignored.

The fifth and all later columns, if any, are treated as comments and ignored.

! default cost is normally zero
Comment line text must begin with an exclamation point, but it may be indented. Comment lines may appear anywhere (vertically) and are ignored. 
Blank lines are ignored as well.

#eof#
additional comments...
After the last field definition, an ''optional'' #eof# line may be specified, in which case any lines after that will be ignored.

 
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...

And that’s all there is to it.

=== Support for Dates ===
As of V2.48, file layouts support dates in any storage formats on disk. Whether you store your dates in Julian or in YMD or MDY or any other format, specify so in the 4th column of your file layouts, using the FileIO Date Keyword. ex: DATE(Julian) or DATE(YMD) or any other valid BR Date Format.

[[File:Dates0.png]]

When this is specified, it enables the FileIO data exploration tool (Data Crawler) to display the dates in human readable format. This works for both Viewing, and for Editing.

The new Date functionality also supports the File Layout Upgrade facility, allowing you to change the format of your dates on disk and FileIO will handle it automatically, upgrading the field to use the new date format for you.

It works also for Exporting your data files to CSV, and is supported automatically in the FileIO functions that do those exports. It converts the dates on export to a standard format (Default: m/d/cy) that you can specify in your FileIO.Ini File.

And it extends ScreenIO's date features to all date fields, no matter what format they're stored in. (Previously, ScreenIO's advanced date features only worked for dates stored in Julian on disk.)

This update adds two new ini file options:
CODE: SELECT ALL
DateFormatExport$='m/d/cy' ! Format of Dates when Exporting to CSV
DateFormatDisplay$='m/d/cy' ! Format of Dates when displaying in Data Crawler

You can use these to specify your preferred Date format for Viewing/Editing, and your preferred Date format for Exporting.

Remember, you can see the full list of FileIO ini file options, by looking in the source code at the top of FileIO.

There is a new optional parameter for all layout reading functions, mat NDateSpec$ and mat SDateSpec$ which correspond with the other arrays, to let you know which fields are date fields, so that you can develop routines in your programs to automatically pack and unpack the dates.

Important Note: Using FileIO, the reading of the data file is still done directly in your programs. So this does not change how your existing programs work. It does not unpack the dates for you in your programs. You still have to do all that.

For this reason, upgrading to the new Date processing will not break any of your current code.

=== Debugging Tips ===

When you're making new layouts, a missing comma can cause FileIO to parse the layout wrong and give you errors. Here are a couple tips to help ensure your layouts are error free before using them in your programs.

*Use the Data Crawler to test your layout. The data crawler is the simplest way to test your new layout without writing any code. It opens it and accesses the file in a very simple and straight forward manor to help identify any errors in the layout that you might have.

*If you have trouble with the form statement, you can't see whats in it because FileIO uses CForm$ to compile your form statement to make your programs run faster. But here's a way to tell what the original form statement was that FileIO generated when it put the strings first and numbers last in your program: Open the file in the Data Crawler. When you get an error, type "Print FormStatement$" to see the original form statement.

This works even if your file is working fine. Any time the file is opened with the data crawler, you can press CTRL-A and then type PRINT FormStatement$ and it will print out the uncompiled form statement for the file.

== Utilities ==

Now that you have your file layouts defined, you have access to several powerful utilities right out of the box using Fileio. Additionally, several more utilities are available as [[#FileIO_Add-on_Packages|Add-Ons]], including our most popular development tool [[Screenio|ScreenIO]]. You can read more about them in their section below.

But for now, lets take a look at some of the wonderful free utilities that come built into Fileio.

Some of these utilities are accessible from your code via library functions, but the primary way you access any of them is by simply loading the FileIO Library and running it directly.

=== DataCrawler ===
The data crawler is the original utility of FileIO. This utility shows you first a list of all data files allowing you to select one.

Select a data file and press enter, and FileIO will then display a listview containing all the data in the data file. This list is sized based on the size of your main BR window (window 0) automatically to take up the full size available to it, so if you want to see more, try [[Open Window|opening window 0]] larger before running FileIO.

At the top of the window is a filter box, and you can type anything you want in there and click "Refresh" and it will reread the data file, shortening the list to show only those records that match (case insensitive) what you have typed.

If you have ScreenIO installed, then FileIO's data crawler will take advantage of the included Animation Engine in ScreenIO to animate a loading window while the listview is displaying. If you don't have ScreenIO then FileIO will simply load the listview.

If you don't want to wait for the entire file to load, press ESC to stop the load process.

If the file is empty, FileIO will display a message box letting you know.

This tool is very useful for sorting out data errors. It will allow you to look inside any data file you have a layout for and directly view the data there.

At the bottom of the Data Crawler are several buttons. There's a Jump button that repositions the file by a key you specify and then loads the list with the data from that key on down to the end of the file.

There is a "Columns" button which you can use to decide which columns should show up on the listview. Fewer columns means faster loading so sometimes for large files I press ESC immediately when the file first starts loading to cancel the load. Then I click "Columns" and check only the columns I want to see. Finally I press the "Refresh" button to trigger it to read the file again and this time it loads much faster then before.

Next you'll find an Export button which starts the process for exporting a file to CSV. You can read more on that in the next section. And next to that is a Quit button.

In this example, we loaded the file "Read Only" so it put everything in a listview. But there are times when its useful to fix data errors this way too, especially during development. So if you want to directly edit your data file, on the first page select the file you want to edit and instead of pressing "Enter" or clicking "View", this time press "F5". F5 is the secret Edit button that loads a data file into a grid instead.

You can use the grid to change records, delete them or add them, and in addition to the buttons listed above, it also has an "Import" button for importing a CSV file into this data file.

Any changes you make to the data file are not saved until you click the "Save" button (which also only appears when you're in Edit mode).

In the 01/2015 release of FileIO, each records rec # is displayed in the listview, to aid in debugging bad data problems.

==== Debugging Tip ====
Any time you're viewing a file layout in the Data Crawler, you can see the Uncompiled Form Statement by pressing CTRL-A to get to an ATTN prompt, and then entering the command:

print FormStatement$

and it will print out the original form statement.

==== Another Debugging Tip ====

The FileIO Datacrawler ignores records that it cannot read. This is to allow for data files that have multiple record layouts in one data file. You make a custom layout for each record type and the data crawler shows just the records that match that type in the file.

However that becomes a problem when you're making a layout to work with an existing data file. Error 726 indicates that something minor in the file layout doesn't match the data on the disk, but these errors are ignored so you might see either an empty data file, or a data file with some records missing. If that happens, you need to see the missing records in order to figure out what is wrong with your layout. '''''It's very important that you don't try to use a file layout that isn't quite working right. Make sure your layout works and can read every record of a file that it should read before using it.'''''

To see the records that could not be read in a file, run the data crawler on the layout, then press CTRL-A to get an ATTN prompt. From there, enter the command

print mat BadRead$

and it will print all the records that were ignored because the file layout didn't match them. It prints out the raw data from the file.

==== Function Access to use Data Crawler in your programs ====
You can use the data crawler in your own programs by using one of the following functions:
* [[#fnDataCrawler|fnDataCrawler]] - Open a Listview showing the data file
* [[#fnDataEdit|fnDataEdit]] - Display the data in an editable grid
* [[#fnShowData|fnShowData]] - This function does the same thing as the above two, but with many many more options allowing you to customize exactly what appears and exactly what they're allowed to change.

Note: its not recommended to allow your customers to use the data crawler to access your data files directly. There's no way to specify validations or do anything complicated, so unless you're careful, there are lots of ways your customers could use this tool to do damage to your data files. It is a programmer tool only.

If you do decide to use it for your end users, be careful how you implement it.

=== Import/Export to CSV ===

You can use FileIO to export your data files to CSV or import from CSV into your data file. To do this, you want to run the data crawler and select the file layout you're looking for. Then, view it (or press F5 to edit if you want to import something). Click on the Export button and it will ask you to select a file. Once that is selected it will ask a couple other simple questions, and when you've specified the options to your satisfaction, click the Export! button. A new CSV file will be created.

Import is even more simple. To import, you must be in Edit mode (press F5 to select the file instead of the enter key) and then simply select the Import button. It will ask you again to choose the file, and then it will ask you if it should update all files by Record Number (if record number is recorded in the CSV file) or by Key (if the file has keys) or to just Add all information to the file. Select what you want and press Import and the CSV file is added to the BR data file.

==== Function Access to Import/Export from your programs ====

You can use the following functions to call the Import and Export functionality from your code.

*[[#fnCSVImport|fnCSVImport]]
*[[#fnCSVExport|fnCSVExport]]

These functions are intended to give you the ability to use our functionality to write your own import and export routines for your customers, because its not a good idea to let your customers run the Data Crawler.

=== Generate Layout Wizard ===

There is also a Generate Layout Wizard utility in FileIO. This utility is there to help you build your file layouts. It is designed to work with a certain style of BR programming that was common in the 80s and 90s. So if your software is written in a style that opens the file directly, and reads/writes the data to a long series of individual variables, the Generate Layout Wizard is for you.

To use it, start by running FileIO. Then, don't select a layout - instead, click on the "Generate Layout" button.

You'll see a screen with a bunch of large text boxes, a small grid, and some buttons.

The first thing you want to do is select the "Browse" button and then select a .wb or .br file that contains a program that reads or writes Most of the File.

When you select one, press the Scan All button and it fileio will search the whole program looking first for all the open strings. It will take the file that is opened the most times and then search for all read statements to that file. It will look for the longest read statement and then find the Form statement associated with that Read statement, and any DIM statements for any variables used.

If you don't like the file its chosen, click the "Open Scratch Pad" button to open the temp work file it uses into the program of your choice (I use myEdit for BRS files). Simply select all the open statements for the file you DO want to build off of, then click the Paste button to paste those open statements into the "Open String" list. After that click "Clear All" to erase what it did on the first search and then click "Scan All" again to rescan the program using this new data file.

You may have to help it a bit, but once it has a proper matching open statement, read statement, form statement and dim statements for any arrays used, press the "Generate Layout" button and it will build a layout for that file.

Finally, load the layout it built and clean up anything if you want, and consider adding better descriptions for each of the fields that you know (as it will use the variable names for both the subscripts AND descriptions in the layout).

When you're all done, click "Done".

==== Functions to Generate Layouts from your code ====

* [[#fnGenerateLayout_.26_fnWriteLayout|fnGenerateLayout]]
* [[#fnGenerateLayout_.26_fnWriteLayout|fnWriteLayout]]

=== Code Templates ===

One more tool FileIO has to help is the ability to generate code based on your file layouts.

Run FileIO and this time select a file layout and press "Generate Code". A window will pop up listing all the "Code Templates" that are available. Select one (and then select a key if it asks you - some templates require extra info). It looks like nothing happened, but the code you generated is now in your clip board. Paste it somewhere and take a look at it!

Code Templates help us to standardize our ways of doing things, which eventually leads to more and more powerful tools we can use. Code Templates also help ensure we use cleaner code by doing some of the busy-work of writing clean code for us.

==== Writing Code Templates ====
FileIO ships with several basic code templates. If you want to add your own, take a look in the filelay\templates folder (configurable in fileio.ini) and look at basic.brs. Copy it to your own program and then modify it to have your own code templates in it. Write me at gabriel.bakker@gmail.com with any questions. I want to help.

And if you write good code templates, its easy to share them with the BR community. Anyone can download your templates and place them in this folder and they'll instantly be available for use.

== FileIO Function Reference ==
''The FileIO Library contains a number of other useful functions.'' The following functions are available and you are welcome to use them:

=== Primary Functions ===

==== fnOpen ====
fnOpen is the primary function that opens a file, and it’s used like so:

''def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, DontSortSubs, Path$*255, Mat Descr$, Mat FieldWidths, SupressPrompt, IgnoreErrors, SuppressLog)''

Note that all of the parameters after MAT Form$ are optional. If you need to specify a parameter in the middle of the optional parameter group, just list zeroes and empty strings for the intervening unused parameters.

*FileName$ - The filename of the file layout for the file you’re reading.
*MAT F$ - The array that will be used to hold the string data for the file.
*MAT F – The array that will hold the numeric data for the file.
*MAT Form$ - An array of form statements.
*InputOnly – 1 means open for input only. 0 means open for OutIn and open every key file associated with the given data file (this is because all key files need to be open for the keys to be updated on an output) (defaults to 0). Files opened for input process considerably faster than files opened for output. Furthermore when files are opened for input only, alternate key files are ''not'' opened.
*KeyNum – This tells the function of which key to return the file handle (defaults to 1). Specify -1 to force the file to open Relative, without using its keys. If a file has no keys, it will always be opened Relative.
*DontSortSubs – The function by default, when compiling the Form statement, will sort the string and numeric subs in order to allow for reading the data into an array, and this parameter would turn this functionality off. However, if you are trying to read your data without reading it into an array, you are missing out on some serious efficiencies. You should normally leave this option turned off (0). This is a totally unsupported feature, and should always be set to 0, if it is specified at all.
*Path$ - The path to your data files. This optional parameter can be passed in by the calling function. It is prefixed to the beginning of the paths given in the file layout files. It is useful when your data files can be in different locations depending on the state of your program.
*mat Description$ - This optional parameter provides a way to read the description for each field from the original file layout. If the parameter is not provided, no description data will be returned.
*mat Fieldwidths – This optional parameter will return an array of the calculated display field widths. This number will always be at least large enough to contain the data for this field.
*SuppressPrompt - This optional parameter can be used to suppress the prompt normally given when fileIO creates a file. It can have three values. A value of 0, the default, uses the setting stored in your FileIO fnSettings routine to determine weather or not to prompt on Creation of a new file. A nonzero value always suppresses the prompt. A value of 1 indicates never to create a file if the file doesn't exist. A value of 2 automatically creates the file if the file doesn't exist.
*IgnoreErrors - Normally when fileio opens a data file, if there are errors trying to open the file, it prints them out to the debug console and pauses so that you can try to find out whats going wrong. If you specify 1 for "IgnoreErrors" it will cause Fileio to log those errors instead, and continue loading your program. This will result in the fnOpen file function returning Zero instead of the opened file number, so if you use IgnoreErrors, you need to test to make sure that fnOpen returned a file number before you try to access the file.
*SuppressLog - this optional parameter can be used to suppress writing to the log file for this one specific open statement. I use it for files that will be opened all the time, for example, the menu data file on one of my customers systems. Without this boolean parameter, his log file is quickly filled up with useless information any time his employees look at his menu. I specify this optional parameter to suppress logging anything about the menu file so that I can more easily find the actual programs they've used when looking in the logfile.

'''''Note: When using fnOpenFile, you really want to call your local function fnOpen, which in turn calls fnOpenFile for you.''''' FnOpenFile is for internal use only.

Example:

Let FFILE=FNOPEN(“FARM”,MAT FARM$,MAT FARM,MAT FORM$,0,2)
Let RFILE=FNOPEN(“ROUTE”,MAT ROUTE$,MAT ROUTE,MAT FORM$,1,3)
Let CFILE=FNOPEN(“CUSTOMER”,MAT CUSTOMER$,MAT CUSTOMER,MAT FORM$)

assuming:
farm.dat has 3 keys: farm.ky1, farm.ky2, farm.ky3
route.dat has 4 keys: route.ky1 … route.ky4
customer.dat has 2 keys: customer.ky1, customer.ky2

This will perform the following opens and set the following variables:

OPEN #1: “Name=Farm.Dat, kfname=farm.ky2”,internal,outin,keyed
OPEN #2: “Name=Farm.Dat, kfname=farm.ky1”,internal,outin,keyed
OPEN #3: “Name=Farm.Dat, kfname=farm.ky3”,internal,outin,keyed
OPEN #4: “Name=Route.Dat, kfname=route.ky3”,internal,input,keyed
OPEN #5: “Name=Customer.Dat,kfname=customer.ky1”,internal,outin,keyed
OPEN #6: “Name=Customer.Dat,kfname=customer.ky2”,internal,outin,keyed
LET FFILE=1
LET RFILE=4
LET CFILE=5

This will also resize the arrays, set the form statement, and create all the subscripts to make accessing the data clear and simple, as in the above example. The KEYNUM parameter is where you list the key file you would like to use for reading and writing. The extra keys are opened to ensure that all keys get updated properly when the file is changed.

Example:
DIM FORM$(1),PRICE$(1)*255,PRICE(1),
DIM DESCRIPTION$(1)*80,FIELDWIDTHS(1)

Let PRICEFILE=FNOPEN(“PRICE”,MAT PRICE$,MAT PRICE,MAT FORM$,0,2,0,"",MAT DESCRIPTION$)

Assuming the Price File layout (filelay\price) contains:

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30

This will perform the following opens and set the following variables:

OPEN #1: “Name=Price.Dat, kfname=Price.ky2”,internal,outin,keyed
OPEN #2: “Name=Price.Dat, kfname=Price.ky1”,internal,outin,keyed
OPEN #3: “Name=Price.Dat, kfname=Price.ky3”,internal,outin,keyed
let PRICEFILE=1
let PR_FARM=1
let PR_ITEM=2
let PR_GRADE=3
let PR_DESCR=4
let PR_PRICE=1
let PR_COST=2
let PR_XOPRICE=3
let PR_XOCOST=4
let PR_MOPRICE=5
let PR_MOCOST=6
let PR_VOPRICE=7
let PR_VOCOST=8
MAT FORM$(1)
MAT PRICE$(4)
MAT PRICE(8)
MAT DESCRIPTION$(12)
MAT FIELDWIDTHS(12)
let FORM$(1)=CFORM$(”form C 4,C 4,C 4,POS 74,C 30,POS 50,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2”)
let Description$(1)= “Farm Code (or blank)”
let Description$(2) = “Item Code”
let Description$(3) = “Quality”
let Description$(4) = “Description of Price Rule”
let Description$(5) = “Default Price”
let Description$(6) = “Default Cost”
let Description$(7) = “Default Christmas Price”
let Description$(8) = “Default Christmas Cost”
let Description$(9) = “Default Mothers D Price”
let Description$(10) = “Default Mothers D Cost”
let Description$(11) = “Default Valentine Price”
let Description$(12) = “Default Valentine Cost”
let FieldWidths(1) = 4
let FieldWidths(2) = 4
let FieldWidths(3) = 4
let FieldWidths(4) = 30
let FieldWidths(5) = 8
let FieldWidths(6) = 8
let FieldWidths(7) = 8
let FieldWidths(8) = 8
let FieldWidths(9) = 8
let FieldWidths(10) = 8
let FieldWidths(11) = 8
let FieldWidths(12) = 8

There are a few things I’d like to point out about the example above. First, you will notice that the form statement jumps around to put all the strings first, and then the numbers last. This is why it has a “POS 74, C 30,POS 50”. Then notice that the subscripts for the string variables are 1 .. 4, and the subscripts for the numbers are 1 .. 8. Finally, the order of the Description and FieldWidth fields also match the sorted positioning of the Form Statement.

The reason that we sort our form statements is so that BR will allow us to read the file into arrays by saying:

Read #pricefile, using form$(pricefile) : mat price$, mat price

Without resorting, the above statement would give a conversion error as BR attempted to put the PR_PRICE field inside mat price$(4). However, because we have reordered the form statement, we are able to read them safely into two arrays, and then we will be able to use the values without caring what position they are in the file, by simply saying PRICE$(PR_DESCRIPTION) when we want the description, and PRICE(PR_PRICE) when we want the pr_Price field.

Another thing you may notice about the above example is that it gives the calculated display length for the numeric fields as 8, when on the disk (and in the file layout) they are listed as BH 3.2. The reason for this is the program looks at the BH 3, and figures that a number that takes up 3 bytes on disk has a potential maximum size of 256**3 or 16,777,216, and therefore will need up to 8 characters of screen display space to view.

Finally, note that any field with a form statement of X is ignored by the library, except that the blank space is used when building the FORM statement.

==== fnCloseFile ====
This function will close the specified file number and all keys that were opened with the file. The purpose of this function is to facilitate the closing of the extra keys that are opened when you open a file for OutIn with the library. There is no need to use this for files opened for input because it is easier to just close the file directly. Secondary keys are not opened by FileIO for files opened for input only.

You must give the function the name of the file layout. It uses this information to determine how many keys were opened, and how many it must therefore close.

Then it basically starts at the file number you gave it, and closes the next X files that were opened with the same file name as this, where X is the number of keys associated with this file.

The syntax is:

''fnCloseFile(filenumber,filelay$;path$)''

*FileNumber – The filenumber of the file you are trying to close.
*FileLay$ - The name of the file layout for this file. This is used to determine how many keys the file would have been opened with and therefore how many we now need to close.
*Path$ - Optional Alternate Path. Use to close files that were opened using the open file's optional alternate path parameter.

==== fnGetFileNumber ====
FnGetFileNumber is a simple function to find a valid unused file handle. If you use this function in all of your programs, they will become much more portable, as you will never have to worry about your file handles fighting with each other. The function will return 0 if no free file number was found (but with 999 of them available now, I have never seen it happen).

''fnGetFileNumber(;X,Count)''

*X – This optional parameter will specify where to start looking.
*Count - This optional parameter will specify how many file numbers to find in a row. If count is 3, then fnGetFileNumber will return the first filenumber in the first gap of three unused file numbers that it finds.

=== File Reading Helper Functions ===

These functions perform various useful calculations to aid in interacting with data files when you're using fileio.

==== fnBuildKey$ ====
This function will return the key for a given record in a data file. It actually reads the file layout and builds the key to match the layout.

''FnBuildKey$(Layout$, Mat F$, Mat F; Keynum)''

*Layout$ - the name of the data file to build the key for.
*Mat F$ - the string array of the file object
*Mat F - the numeric array of the file object
*KeyNum - This optional parameter specifies which of the key files in the given layout the key should be built for.

To use this, you want some code like in the following example:

mat customer$=("") : mat Customer=(0)
let customer$(cu_name)=CustName$
let customer$(cu_phone)=CustPhone$
read #customer, using form$(Customer), key=fnBuildKey$("customer",mat Customer$,mat Customer,2) : mat Customer$, mat Customer nokey KeyNotFound
! The above code assumes that the second key of the Customer file is based on the Name and Phone fields.

By using this logic you are able to avoid directly specifying the key in your code - which means that even if the key changes in the future, as long as your code specifies enough information, it will still find the correct key. In our example, even if we dropped the phone number from the key in the future, or even if we expand the length of the Customer Name field, our code would still work and fnBuildKey$ would still build the correct key without us having to look at or change our code again.

This kind of reasoning is central to the fileio system, which, when implemented properly, ensures that you can change your data files in any way you need to in the future, without breaking your existing programs.

==== fnUniqueKey ====
This function tests to see if a given key is unique to the specified file. This function is very useful for situations where you need to ensure that the user-entered key is unique.

''fnUniqueKey(Fl,key$*255)''

*FL – The file number of the opened file.
*Key$ - This is the key to test. If this key is the key for a preexisting record in the file, the function will return false. If this key can not be found in the file, the function will return true.

==== fnMakeUniqueKey$ ====
This function generates a unique key for a given file. This is useful if you do not care what the key is, but it needs to be unique. I use this function in situations where the user never needs to know what the given key is.

This function reads the key length for the given file. Then it returns a string that is the right length, which is generated by counting in binary until a key is found that does not appear in the file. The first key found for a 4 byte key field would be chr$(0)&chr$(0)&chr$(0)&chr$(0). If that key was already in use in the file, the function would return chr$(0)&chr$(0)&chr$(0)&chr$(1). If that one was also in use, it would then try chr$(0)&chr$(0)&chr$(0)&chr$(2), and so on until it found one that wasn’t in use.

''FnMakeUniqueKey$(fl)''

*FL – This is the file number of the opened file for the desired key.

==== fnKey$ ====
This function formats the key for the given file number. All it does is ensure the key is the correct length. You should use fnBuildKey$ instead to properly build the correct key for the record you want to read.

''FnKey$(FileNumber, Key$)''

*FileNumber - the file number we are formatting the key for
*Key$ - the key we are trying to format.

==== fnNotInFile ====
This function will determine if a non-key element in a line is unique. It works almost exactly like fnUniqueKey specified above, except that it allows you to enter the subscript value of the element you are checking for uniqueness. You can use this to look for uniqueness in any field, not just in the key field. Additionally, the search engine used by this function looks for a partial match, and will only return true if the given string is not found anywhere in the specified element for the given file.

''fnNotInFile(string$*100,filename$,sub)''

*String$ - Value to check for uniqueness in this file.
*Filename$ - This is the name of the file layout of the file you want to check. This file does not have to be open in order for you to search it, because the function will open it for you.
*Sub – This is the subscript value of the element you are checking.

==== fnSortKeys ====
This function takes an array of Primary Keys indicating records in the data file, and resorts it into the order you would have expected using one of the other keys for your data file.

For example: Lets say you had a customer file, and the first key was Customer Code and the second key was Customer Last Name. This function would take an array of Customer Codes and sort it into Last Name order.

This function requires the file to already be opened (which is usually the case when you have an array of keys from that file).

''fnSortKeys(mat Keys$,Layout$,DataFile,mat F$,mat F,mat Form$;KeyNum)''

*mat Keys$ - the array of keys. These keys are based on whatever key the file was opened with in DataFile.
*Layout$ - the file layout for the file.
*DataFile - the open file number matching the key file that matches mat Keys$.
*mat F$ - array sized to hold the strings from the data file. This is the array you get back from fnOpen.
*mat F - array sized to hold the numerics from the data file. This is the array you get back from fnOpen.
*mat Form$ - array of form statements, that you get back from fnOpen.
*KeyNum - This is the key that we'll sort based on. If not given, the first key listed in the layout is assumed.

=== File Reading Functions ===

These functions actually read information from your data file and return it. These functions can be used to simplify the logic in your programs for many common tasks.

==== fnReadAllKeys ====
This function will read through a file, returning the specified element(s) from each record into (a) dynamically dimensioned array(s). For example, I could tell it to give me the Inventory Code for every inventory item in my database in one array, while placing the Inventory Description (name) for each item into the corresponding position in another array.

''fnReadAllKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$;sub2,mat out2$)''

*Fl – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array
*mat out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

For example:

FnReadAllKeys(InventFile,mat Invent$,mat Invent,mat Form$,IN_Code,mat InvtList$,IN_Name,mat InvtNames$)

==== fnReadMatchingKeys ====

This function will read through a file, returning the specified element(s) from each record where the key matches the specified key into (a) dynamically dimensioned array(s). This function is the same as the above function except this one will filter the results, returning only those records where the key matches the specified key.

''fnReadMatchingKeys(Fl,mat f$,mat f,mat fm$,key$,keysub,sub1,mat out1$;sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - Only records where the key field matches key$ will be returned.
*Keysub – This tells the function which element is the key element for this particular file number.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadAllNewKeys ====

This function will read through a file, returning the specified element(s) from each record that isn’t already there into (a) dynamically dimensioned array(s). This function is the same as the above function, except this one will filter the results returning only those records that don’t already exist in the array (eliminating duplicates).

''FnReadAllNewKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$; dont_reset,sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Dont_reset – By default the array will clear the contents of the arrays that are passed in. This Boolean flag will instruct the function to not empty the passed in arrays.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadFilterKeys ====

This function by Mikhail Zheleznov is a modification of the above functions. Like its predecessors, it reads an entire file, populating the specified arrays with data from all or some of the records in the file. The given subscripts specify which fields to return from each record. The key given specifies search criteria for the records. The filter specifies filtering criteria that can be preformed on the data before it is returned.

''FnReadFilterKeys(Fl,Mat F$,Mat F,Mat Fm$,Key$,Keyfld,Sub1,Mat Out1$;Filter$,Filter_Sub,Readlarger,Sub2,Mat Out2$, Sub3, Mat Out3$, Sub4,Mat Out4$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - The key to search for in the read statements
*Keyfld – the subscript of the key field in the data file. This must match the key field specified in the data file otherwise the function won’t work.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Filter$ – This optional parameter identifies matches to search for in the records. It works in conjunction with Filter_Sub
*Filter_Sub – This parameter specifies which field to look for in the records for matches to Filter$. Only records which have Filter$ in the specified field will be returned.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.
*Sub3 – Subscript of the element to return in the third array. This is optional. If it is specified, you must give MAT out3$, or BR will return an error.
*MAT out3$ - Array in which to return the third (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub3 is given (non-zero). This parameter will not be used if Sub3 is not given or is given as 0.
*Sub4 – Subscript of the element to return in the fourth array. This is optional. If it is specified, you must give MAT out4$, or BR will return an error.
*mat out4$ - Array in which to return the fourth (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub4 is given (non-zero). This parameter will not be used if Sub4 is not given or is given as 0.

This function was written by Mikhail Zheleznov for the fileIO library.

==== fnReadDescription$ ====
''fnReadDescription$(Fl,Subscript,key$,mat F$,mat F,mat Form$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout) (RT_NAME, which should equal 2 after opening routefile (unless we change the file layout later)).
*key$ - Item that should match a key in this file somewhere (in this case it is the route code from the farm record).
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading they have to be dimensioned properly, which is why we use our colorcat$ and our colorcat for these parameters.
*mat Form$ - This will need to be our array of form statements, so the function can read the file properly.

Lets take a look at how this function works:

In the example program I used above, I am reading the Color File to get details about each color. The color file contains a colorcat code field, but I want to display the colorcat description. The colorcat file contains a few details about a color category, and it is indexed based on colorcat code:

route.dat, RT_
route.key, CODE
recl=512
===================================================
CODE, Routing Code, C 6
NAME, Routing Name Description, C 30
MOFT, T/A/C (truck/air/courier), C 1
SHIPPINGDAY, Day of Week for Shipping, C 7

Now, as you know, in the above example, we have already opened the ColorCat File, and we have opened and read a Color record.

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
30180 LET ccode$=color$(CO_CODE) !:
LET Name$=color$(CO_NAME)

Now all that’s left to do is to take the Color File’s ColorCat code and use it to look up the ColorCat File’s description.

30190 LET ColorCat$ = fnReadDescription$(ColorCatFile, CC_NAME, Color$(CO_CATEGORY),
mat ColorCat$, mat ColorCat, mat form$)

==== fnReadUnopenedDescription$ ====
This function accomplishes the same thing as fnReadDescription except that it opens the data file for you. It is slower then FnReadDescription$, but it is easier to use.

''FnReadUnopenedDescription$(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the value of the key field in the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2, so sometimes it is a good idea to design your data files so that string field number two is a descriptive field, like Name or Description.

This function only works on the first key file for each data file. This function is a convenience function but it is slow because it opens the file and closes it for each call. Opening a file is one of the most time consuming program operations.

==== fnReadNumber ====

fnReadNumber does the same thing that ReadDescription does except it reads a numeric field instead of a description.

Lets take a look at how this function works:

''fnReadNumber(Fl,subscript,key$,mat F$,mat F,mat fm$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout).
*Key$ - Item that should match a key in this file somewhere.
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading. They have to be dimensioned properly by [[FileIO_Library#fnOpenFile|fnOpen]].
*mat Fm$ - This will need to be our array of form statements, so the function can read the file properly.

==== fnReadUnopenedNumber ====
This function accomplishes the same thing as fnReadNumber except that it opens the data file for you. It is slower then FnReadNumber, but it is easier to use.

''fnReadUnopenedNumber(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the key of the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2.

==== fnReadRelativeDescription$ ====
This function is the same as fnReadDescription$ but for Relative Files.

''fnReadRelativeDescription$(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat F,mat form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedDescription$ ====
This is the same as ReadUnopenedDescription$ but for Relative Files.

''fnReadRelUnopenedDescription(Layout$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRelativeNumber ====
This is the same as fnReadNumber but for Relative Files.

''fnReadRelativeNumber(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat f,mat Form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedNumber ====
This is the same as fnReadUnopenedNumber but for Relative Files.

''fnReadRelUnopenedNumber(LayoutName$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRecordWhere$ ====
This function returns the record where the given element matches the given value. It does not depend on any key files, and it can be used to locate a record based on any element. However, it loops through the entire data file to do this and it could be a bit slow for large data files. This function opens the file for you, so the file does not have to be already opened.

''FnReadRecordWhere$(Layout$,SearchSub,SearchKey$*255,ReturnSub)''

*Layout$ - the layout of the file we are searching
*SearchSub - Subscript of the element to look in
*SearchKey$ - The value we are looking for
*ReturnSub - Subscript of the element to return

=== FileIO Utility Functions ===
==== fnDataCrawler ====
This function launches the Data Crawler as a function, so you can make your own programs link to it. Special thanks to Mikhail Zheleznov for turning the DataCrawler into a library function.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnDataEdit ====
This function is the same as fnDataCrawler only it opens a Grid for editing.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnShowData ====

This function builds a list or a grid in a floating window that is tied to a data file. It uses the same function that the datacrawler uses, but its much more customizable. All other datacrawler functions are just wrappers for this one.

The first parameter is the only required parameter.

''def library fnShowData(FileLay$;Edit,sRow,sCol,Rows,Cols,KeyNumber,Caption$*127,Path$*255,KeyMatch$*255,SearchMatch$*255,CallingProgram$*255,mat Records,mat IncludeCols$,mat IncludeUI$,mat ColumnDescription$,mat ColumnWidths,mat ColumnForms$,DisplayField$*80,mat FilterFields$,mat FilterForm$,mat FilterCompare$,mat FilterCaption$,mat FilterDefaults$,mat FilterKey)''

*FileLay$ - the file layout you want to display
*Edit - 1 for Edit (Grid) and 0 for View (Listview)
*sRow, sCol - the start position. if not given, its centered. If given but out of bounds, they'll be automatically adjusted to fit the grid on the screen.
*Rows, Cols - the size. If not given, defaults to fullscreen. If given but not big enough to fit the UI elements you request, they're automatically adjusted to fit everthing.
*KeyNumber - the Key to use when reading the data, used with other parameters. If not given, the file is read Relative for faster performance. Required if KeyMatch$ is given.
*Caption$ - the Caption to display, defaults to FileIO's Datacrawler
*Path$ - Alternate path to use for data files (Prepended to the name found in the layout)
*KeyMatch$ - Show only records that match this key. You can use Partial Keys. If this parameter is given, you must also give KeyNumber (above).
*SearchMatch$ - Show only records that contain this substring in them anywhere
*CallingProgram$ - used for logging purposes, pass in the system function Program$
*mat Records - Show only these records in the Grid. Use it to control exactly what the user sees.
*mat IncludeCols$ - Show only these columns. These column names must match the subscript names from the file layout.
*mat IncludeUI$ - Which UI Options to show. Build this array with one element for each optional UI element to include. Explanations of UI elements follow:
**"ColumnsButton" - adds a Select Columns button that the user can use to modify which columns appear on the list.
**"ExportButton" - adds an Export to CSV button that exports the data to a CSV file.
**"ImportButton" - adds an Import from CSV button that imports from the CSV file.
**"AddButton" - adds a button that can be used to add records to the data file.
**"SaveButton" - adds a button allowing the user to save changes
**"DeleteButton" - adds a button allowing the user to delete a row
**"KeyButton" - adds a button allowing the user to jump to a specified position by key or by record number (depending on if the file is opened keyed or not)
**"QuitButton" - adds a Quit button to the screen (the Esc key also quits)
**"Search" - adds a case insensitive search box to the screen.
**"Border" - adds a border around the screen
**"Caption" - adds a caption. (If you specify a caption, this is automatically turned on. If you don't specify a caption but turn on caption here, then FileIO uses the default FileIO data crawler caption.
**"Recl" - adds the Recl to the caption
**"Position" - adds the positions to the field descriptions in the column headings.
*mat ColumnDescription$ - Show these captions. If blank, use the descriptions from the layout
*mat ColumnWidths - Use these widths for the data, if not given, calculate from the file layout
*mat ColumnForms$ - Display Format for the data, including DATE and FMT and PIC
*mat DisplayField$ - Counter Field to display on the Loading Window. If its a field with an associated DATE ColumnForms$ value, that column form will be used when displaying the Counter Field. It can be any of the following:
**REC - this will display the current "REC/LREC" data in the loading window.
**READCOUNT - this will display the "Record Count / LREC" in the loading window.
**FINDCOUNT - this will display the number of records that match the current search criteria by itself in the loading window.
**A Field Name - one of your field names will display that field value in the loading window
**A string literal - anything else will display as a string in the loading window, so you could put something like "Loading, please wait" here and it will display.
*mat FilterFields$ - Contains the subscript of the field to compare to
*mat FilterForm$ - Contains the format of the field to compare to
*mat FilterCompare$ - Contains the comparison type ("<>" or ">" or "=" or ">=" or "*") (* means do a substring search)
*mat FilterCaption$ - The caption for the filter box
*mat FilterDefaults$ - The default value for the filter information
*mat FilterKey - The action to use when filtering the data this way (0 means simple exclude, 1 means start here, -1 means stop here)
**The final five arrays can be used to add user filter boxes to the data grid. You need one element in each array for every custom user filter box on the screen.

==== fnBeginAudit ====

The [[AuditBR|FileIO Compare]] routine is available and can be called from within your programs. To do so, call fnBeginAudit to mark the Start of the compare, then do whatever you need, then run fnCompare to compare everything that has changed between when you ran fnBeginAudit and when you ran fnCompare.

See [[AuditBR#fnBeginAudit|the documentation]] for more details.

==== fnCompare ====

See [[AuditBR#fnCompare|the documentation]] for more details.

==== fnCSVImport ====

This function calls the FileIO Import routine, the same one that you get from the Datacrawlers Import Button.

''fnCsvImport(Layout$*64;SuppressDialog,FileName$*300,ImportModeKey)''

*Layout$ - The file layout to import into
*SupressDialog - 1 to Supress the Import Dialog
*FileName$ - the name of the CSV file (Required if Dialog is Suppressed)
*ImportModeKey - the Import Mode Key (Required if Dialog is Suppressed)
**-1 - Add all records to the file
**0 - Update by Record Number (The file must contain a RecNum column and it must be first)
**1+ - Any positive number means Update by that Key (as listed in the layout).

==== fnCSVExport ====

This function exports a data file to a CSV file.

''fnCsvExport(Layout$*64;SuppressDialog,Filename$*300,IncludeRecNums,KeyNumber,StartKey$,KeyMatch$,Startrec,mat Records,SearchMatch$)''

*Layout$ - The File Layout to Export
*SuppressDialog - (1 to Suppress the Export Dialog, 0 to show it)
*Filename$ - the output file name (Required if SuppressDialog is 1)
*IncludeRecNums - Include a column with the Record Numbers in it
*KeyNumber - Use this key when reading the data for export
*StartKey$ - Start with the record that matches StartKey$
*KeyMatch$ - Export only the record(s) that match KeyMatch$
*StartRec - Start with this Record Number
*mat Records - Export only these records
*SearchMatch$ - Export only records containing this search string anywhere in them

==== fnExportListViewCsv ====

Exports the contents of the specified Listview in CSV format.

''fnExportListViewCsv(Window,Spec$;GenFileName,Delim$,FileName$*255)''

*Window - The Window containing the listview.
*Spec$ - The Spec identifying the listview.
*GenFileName - Flag telling weather or not to generate the file name.
*Delim$ - Delimiter to use. Comma is default.
*Filename$ - Filename to use

==== fnGenerateLayout & fnWriteLayout ====

This function calls on the Generate File Layout Wizard to generate and save the layout indicated by the parameters you give it. You must give it the same valid parameters that you would have come up with if you worked through the layout wizard the normal way, by running FileIO directly and choosing "Generate Layout".

You can also bypass the automatic parsing and generate a layout by specifying all the data directly and using fnWriteLayout.

''fnGenerateLayout(mat OpenStrings$, ReadString$*999, FormString$*20000, DimString$*999; DisplayFile)''
''

*mat OpenString$ - array of all the open strings for the given file from one of your old programs.
*mat ReadString$ - solid read statement from one of your old programs reading the entire record, (or at least everything you want in the layout).
*mat FormString$ - the form statement that goes with the ReadString$ (practice using the Generate Layout Wizard the normal way for details)
*mat DimString$ - the string containing Dim statements for each array mentioned in ReadString$. We need this to know how big the arrays are.
*DisplayFile - if True (1), it will Display the new layout in notepad when its done creating it. If false (0), it will simply create the file.

fnGenerateLayout takes all the above information and parses it into a layout, then calls fnWriteLayout to actually write the layout.

If you already know the information you want to put in the layout, its more direct to call fnWriteLayout below.

''fnWriteLayout(Name$,FileName$*127,VER,PRE$,MAT KFNAME$,MAT KDESCRIPTION$,MAT SUBS$,MAT DESCR$,MAT FORM$;RECL,MAT EXTRA$,DISPLAYFILE)''

*Name$ - the name of the new layout
*FileName$*127 - the name of the data file
*Ver - the version of the data file
*Pre$ - the prefix to use for the data file
*mat KfName$ - array of all the keys for the file
*mat Kdescription$ - array of the subscripts that each key is based on
*mat Subs$ - the subscript for each field in the file
*mat Descr$ - the descriptions for each field in the file
*mat Form$ - the form specs for each field in the file
*Recl - (optional) the record length of the file
*mat Extra$ - (optional) Additonal Information for each field in the file, placed in the Comments column of the new layout. This column is ignored by standard fileio processing.
DisplayFile - if True, open the file in Notepad after it has been created.

==== fnSubstituteStringCode ====
A Large Text Field that is searched. Code is run and any resulting variables are set, if they exist inside String enclosed between Substitute Chars (default []), then they will be replaced with the values derived by the code.

''fnSubstituteStringCode(&String$,Code$*2048;SubstituteChar$)''

*String$ - the string to be searched
*Code$ - code to be run. The resulting variables can be substituted into String
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnSubstituteString ====
A Large Text Field that is searched. Any matching fields in the passed in record will be substituted into their places. For example, if the string contained [cu_name] and you ran substitutions on the Customer file, then [cu_name] would be replaced by the name in the actual Customer record.

''fnSubstituteString(&String$,Filelayout$,mat F$,mat F;SubstituteChar$)''

*String$ - the string to be searched
*FileLayout$ - the layout to be searched
*mat F$ - the record to be used for substitution
*mat F - the record to be used for substitution
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnShowMessage ====
Displays a message to the user, in a child window. Returns the child window number, so that you can close it when you're done with the message.

''WindowNumber=fnShowMessage(Message$*54)''

*Message - the Message to display to the user

=== File System Utility Functions ===
These functions perform other tasks that aid with interacting with the file system.

==== fnGetFileDateTime$ ====
This does a directory listing to determine the Last Modified Date and Time of the given file. You pass it a file name, not a file layout, and it can be used on any file. Its not limited to BR internal files.

The syntax is:

''let FileDate$=fnGetFileDateTime$(Filename$*255)''

==== fnProgressBar ====
There's a Progress Bar that FileIO uses when copying or updating data files. You can use it in your own functions by calling fnProgressBar inside the main loop of the process that you want to display the progress bar over, and by calling fnCloseBar when you're done.

''fnProgressBar(Percent;Color$,ProgressAfter,ProgressThreshhold,UpdateThreshhold,Caption$*255,MessageRow$*255)''

*Percent - Percentage Complete expressed as a float between 0 and 1
*Color$ - HTML Color Code of BR Color Attribute to color the Progress Bar. Defaults to Green.
*ProgressAfter - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*ProgressThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*UpdateThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*Caption$ - Optional message to display above the progress bar.
*MessageRow$ - Optional message to display on the progress bar.

==== fnCloseBar ====

''fnCloseBar''

Call this function to close the progress bar window when your task is done running.

==== fnCopyFile ====

''fnCopyFile(FromFile$*255,ToFile$*255)''

*FromFile$ - The file to copy.
*ToFile$ - The destination file name including path.

This function copies any file, by opening it as an external file and reading and writing the data to the destination file. The advantage of this technique, over using the BR copy command, is this routine is more reliable when run on client server where you may be transferring large files from one side to the other over the internet.

This fnCopyFile also has a progress bar that displays as the file is transferred, so the user knows your software is busy.

This function works over Client Server. Under Client Server, specify @: at the beginning of your filename, to specify that the file is on the client. If the file is on the server, simply leave the @: off. See the chapter on [[Copy#Client_Server|using BR's copy command under Client Server]] for more details on the "@:".

This function's parameters and syntax are modeled off of the built in BR copy command, and like that one, this should work for local transfers, LAN transfers, or even internet transfers. This function will work better for internet transfers then the built in BR Copy Command, however.

==== fnCopyDataFiles ====

''fnCopyDataFiles(DestinationFolder$*255)''

*DestinationFolder$ - the folder to copy your data files to.

This function reads your file layouts and makes a copy of every data file (and key file) in your system to the destination folder, utilizing fnCopyFile above, for better performance and reliability when running over the internet, as well as a progress bar for each individual file.

It also displays a listview while its copying so you can watch the progress while its transferring your data files.

This can be used for making backups of your BR data, or for transferring the latest data onto a laptop for access to it while you're on the road away from the internet.

==== fnReIndex ====

This function reindexes a single data file

''fnReIndex(DataFile$*255;CallingProgram$*255,IndexNum,Path$*25)''

*Datafile$ - the file layout of the file to index
*CallingProgram$ - used for logging, pass Program$ in here
*IndexNum - The index to rebuild - if not given, rebuilds all indexes
*Path$ - the optional alternate path to use for rebuilding the data file.

==== fnReIndexAllFiles ====

This function reindexes all your data files. It doesn't require any parameters.

''fnReIndexAllFiles''

==== fnUpdateFile ====
This function checks and Updates a data file if it needs to be updated, by opening and then closing the data file.

''fnUpdateFile(FileLayout$)''

*FileLayout$ - The name of the file to update

==== fnRemoveDeletes ====

This function, written by Susan Smith, removes deleted records by copying the file with the -D option.

''fnRemoveDeletes(LayoutName$*255;Path$*255,CallingProgram$*255)''

*LayoutName$ - the file layout
*Path$ - Optional Alternate Path
*CallingPRogram$ - used for logging, pass Program$ in here

=== Layout Interrogation ===
Layout interrogation functions are provided for convenience and to enable future dictionary changes without disrupting any programs that interrogate it.

==== fnMakeSubProc ====
This function obtains the subscript assignments that were assigned by fnOpen according to the file layout. The fnMakeSubProc$ routine obtains the subscript assignments without actually opening the file. This is useful when a file record is passed as arrays into a library function in another program, or when you chained to another program and you need to know how to reach the data in the arrays without actually reopening the file.

''fnMakeSubProc(filelay$;mat Subscripts$)''

*FileLay$ - The name of the file layout from which to read the subscripts.
*mat Subscripts$ - If you give this optional array, fnMakeSubProc passes the subscripts back in this array rather then in the subs.$$$ file. This is much faster and helps avoid sharing conflicts.

When this routine returns, you can set the subscripts in your program by executing every element of the Subscripts$ array in a for/next loop.

If you did not pass in a subscripts array, then the a procedure file named subs.$$$ is created. If you proc that file, the proper subscripts will be set.

==== fnReadLayoutArrays ====
This function reads the fields in a file layout into arrays. You call it like the following

''fnReadLayoutArrays(filelay$,&prefix$;mat SSubs$, mat NSubs$, mat SSpec$, mat NSpec$,mat SDescription$, mat NDescription$,Mat Spos,Mat Npos)''

*filelay$ - the name of the layout to read
*prefix$ - the return value for the prefix for the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

This function call would read the fields from the layout in filelay$, and it would return the prefix to prefix$. The Subs would be returned in mat SSubs$ and mat NSubs$.

The Spec statements are returned in mat SSpec$ and mat NSpec$ and the Descriptions are returned in mat SDescription$ and mat NDescription$. The start positions on disk of each element are returned in mat SPos and mat NPos.

All the arrays are optional. If you don’t pass them the information they are supposed to record is simply not returned.

==== fnReadLayoutHeader ====
This function reads the header for a given file layout.

''fnReadLayoutHeader(Layoutname$*255;&Filename$,Mat Keys$,Mat KeyDescription$)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file

==== fnReadEntireLayout ====
This function reads the entire layout by calling fnReadLayoutHeader and fnReadLayoutArrays.

''fnReadEntireLayout(Layoutname$*255;&Filename$,&Prefix$,Mat Keys$,Mat KeyDescription$,Mat Ssubs$,Mat Nsubs$,Mat Sspec$,Mat Nspec$,Mat Sdescription$,Mat Ndescription$,Mat Spos,Mat Npos)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*prefix$ - the return value for the prefix for the file
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

==== fnReadSubs ====
This function reads the subscripts from a layout into Subs arrays.

''fnReadSubs(Layout$,mat SSubs$,mat NSubs$,&Prefix$)''

*Layout$ - the file layout name
*mat SSubs$ - the String Subscript Names
*mat NSubs$ - the Number Subscript Names
*Prefix$ - the files Prefix

==== fnReadKeyFiles ====
This function reads the list of key files from the layout.

''fnReadKeyFiles(Layout$,mat Keys$)''

*Layout$ - The file layout
*mat Keys$ - output array, the keys are returned here.

==== fnLayoutExtension$ ====

This function returns the layout extension being used.

==== fnReadLayouts ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''FnReadLayouts(mat Dirlist$)''

*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all the file layouts that FileIO can find.

==== fnDirVersionHistoryFiles ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''fnDirVersionHistoryFiles(Layout$,mat DirList$;BypassExtension$)''
*Layout$ - Which layout to look up version history of
*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all previous versions from history of the requested layout.

==== fnReadLayoutPath$ ====
This function doesn't actually interrogate your layouts. Instead, it interrogates your settings and returns the path specified for your layout files. This would usually be "filelay\" but you can change it in [[#fnSettings|fileio.ini.]]

It has no parameters.

''let Path$=fnReadLayoutPath$''

==== fnDoesLayoutExist ====
This function returns true if the given file layout exists. It returns false if the layout does not exist.

''FnDoesLayoutExist(layout$)''

*Layout$ - Layout to test for

==== fnReadForm$ (uncompiled) ====
Sometimes you need to know the original form statement that fileio is using to read your data file, most often when you're debugging your file layout, and you're getting some problem when reading the file. The form statement that fileio normally returns is compiled using CFORM$ to save space in the array, and to make the execution of your read statements faster. You can use this function to return the original form statement for the file.

The syntax is:

''let FormStatement$=fnReadForm$*10000(FileLayout$)''

Remember to dimension FormStatement to something huge! fnReadForm$ can return up to 10,000 characters.

==== fnReadFormAndSubs ====

This function does the same as above but it also reads the subscripts from the file into an array.

''let fnReadFormAndSubs(Layout$,mat Subs$,&ReadForm$,&StringSize,&NumberSize)''

Note that unlike most of our functions, all the above parameters are required.

The layout is the layout you're interrogating. The Array will be populated with the subscripts after the function. The ReadForm$ variable will be filled with the form statement for the file. Remember to dimension it large enough. StringSize and NumberSize will contain the number of string fields and numeric fields in the file.

Mat Subs$ will be returned, strings first, numbers last, matching the form statement that is returned. So Subs$(1) is the first string subscript and Subs$(StringSize+1) is the first Numeric subscript.

==== fnClearLayoutCache ====

fnClearLayoutCash (v2.3+) clears out the cache of layout name and data to get realtime Updates to File Layouts.

=== Other Useful Functions (non-layout related) ===

==== fnAskCombo ====

Opens a window with a combo box and returns the users selection.

''fnAskCombo$*255(mat Description$;Caption$*60,Default$*255)''

*mat Description$ - contains the combo box choices
*Caption$ - contains the optional caption for the window
*Default$ - the text of the item in mat Description$ that you want to be selected by default

==== fnSendEmail ====

This function sends an email and an optional attachment to the email address specified.

''fnSendEmail(Emailaddress$*255,Message$*10000;Subject$*255,Invoicefile$*255)''

*EmailAddress$ - the Destination Email Address
*Message$ - the Message$ to send
*Subject$ - the subject
*InvoiceFile$ - the filename of a file to attach. This is the BR filename (the function automatically converts it to an OS Filename.)

The function returns 1 when the email was sent successfully, or 0 if it wasn't sent successfully.

In order to use this function, you must have the emailcfg file layout in your layouts folder and you must have a copy of SendEmail.exe which is free and can be downloaded from the internet. Both of these files are included with the latest update of fileio.

You also have to configure fileio with the authentication information for your email server.

To configure your email server, simply run FileIO to get the data crawler, then select the emailcfg file layout and press F5 to edit it. Add a row if the file is empty.

Simply fill in the information the file is asking for in the appropriate fields and save the data, and then test sending an email to make sure it worked.

More information about sendEmail.exe is available from the author's product site here: [http://caspian.dotconf.net/menu/Software/SendEmail/ http://caspian.dotconf.net/menu/Software/SendEmail/]

==== fnClientEnv$ ====

This function returns the value of a Windows Environment Variable on the client under Client Server.

''fnClientEnv$*255(EnvKey$)''

*EnvKey$ is the name of the Windows Environment Variable to check on the client.

The function returns the value of the entered environment variable.

==== fnClientServer ====

This function returns true if you're currently running in Client Server mode, and false if you're running in the old "native" mode.

==== fnEmpty & fnEmptyS ====
These functions test if the passed in array is empty or not..

The syntax is:

''fnEmpty(mat Numeric)''

or

''fnEmptyS(mat String$)''

Example:

def fnSomeFunction(String$,mat Array$; mat OtherArray)
if fnEmpty(mat OtherArray) then
! Arrays were empty.
end if
fnend

==== fnReadScreenSize ====
This function reads the screen size of the given window (or window 0 if a window wasn't passed.) This is useful for centering a window on the screen, or for making sure window 0 is big enough for the child window you're trying to create.

The syntax is:

''fnReadScreenSize(&Rows,&Cols;Window)''

*Rows & Cols - returns the screen size in rows and columns.
*Window - the window to interrogate. If not given, assumes [[Open_Window#Comments_and_Examples|Window 0]].

==== fnBuildProcFile ====
This function builds a proc file to be executed later. This function and the next simplify the process of executing code in a proc file. It can even be used to spawn a new session of BR.

To use it, call fnBuildProcFile one or more times and specify some lines of code to execute.

''fnBuildProcFile(Command$*255)''

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnRunProcFile ====

This function spawns a new copy of BR and in it, runs the proc file that you've previously built using fnBuildProcFile (above).

'' fnRunProcFile(;NoWait) ''

The optional parameter "NoWait" causes the other session to spawn and run in a new thread. If you don't specify NoWait, the current session pauses and waits for the other session to close before proceeding.

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnLog & fnErrLog ====
These next two functions are functions to aid in logging. When you call either of these two functions, you give them a string that you wish to log. They will open the FileIO Log File and add a record to the end of it containing some user information such as login_name and session$, and the string that you specified. FnErrLog does the same thing as fnLog except it also logs the Error Number and the Line.

The syntax is:

''FnLog(string$)''

*String$ - the Log Message

''FnErrLog(String$)''

*String$ - the Log Message

==== fnLogArray ====

This function logs the given arrays to the log file, logging each field in the arrays. Its useful for recording, for example, an entire data record that is about to be written to a data file.

The syntax is:
''fnLogarray(mat F$,mat f;Message$*512,CallingProgram$*255)''
The first two parameters, of course, are the array to log. The third parameter is an optional message to be recorded along with the array, and the fourth optional parameter is the CallingProgram$ to save in the log along with the message. (The CallingProgram$ parameter can usually be passed as the system function Program$)

==== fnSetLogChanges ====
This function works in conjunction with the next function, and they're for recording just what changed in a data file. When the file is read, you call fnSetLogChanges and record the "before" picture of the file record.

After changes have been made and saved back to disk, you can call fnLogChanges below to record the actual changes.

The syntax is:
''fnSetLogChanges(mat F$,mat F)''

==== fnLogChanges ====
This function is the other half of the function above. It compares the given arrays with the ones set previously in the above function and checks for changes. Then it generates a log message recording information about just the items that changed.

The syntax is:
''fnLogChanges(mat F$,mat F;Message$*1024,CallingProgram$*255,Layout$)''

You need to pass in the same two arrays as before, but this time the modified versions of them.

You can also optionally pass a 1024 byte log message to record with the log entry.

CallingProgram$ again should be passed as the system internal function Program$.

The final parameter allows the passing of a Layout$. If you pass a Layout$, that layout is read and the subscripts are used when making the log message of changes, so that its easier to read. If you pass a layout, it will identify the changed fields by name. If you don't it will identify those fields by relative position number.

==== fnViewLogFile ====
All of the above functions store the information by default into a BR internal file defined in the filelay\logfile layout.

The fnViewLog function uses fnShowData to call the Data Crawler to display the FileIO Log File in a searchable listview.

''fnViewLogFile(;ShowQuit,ShowColumns,ShowExport)''

*ShowQuit - Show a quit button on the UI (if off, ESC will quit).
*ShowColumns - Include a button to allow the user to select which columns to view.
*ShowExport - Include a button to export the log file to CSV.

==== fnReadLockedUsers ====

This function returns a list of all users using the locked data file.

''fnReadLockedUsers(mat Users$)''

*mat Users$ - the list of users is returned here

==== fnDisplayLength ====
This function calculates the display length of a field based on its form spec.

''fnDisplayLength(Spec$)''

*Spec - the Form Spec to return the display length of.

==== fnLength ====
This function calculates the length on disk of a field based on its form spec.

''fnLength(Spec$)''

*Spec$ - the Form Spec to return the length of.

==== fnStandardTime$ ====
Converts Military Time to Standard Time. Returns Standard Time$

''fnStandardTime$(MilitaryTime$;Seconds)''

*MilitaryTime$ - Time in 24 hr format.

==== fnMilitaryTime$ ====
''fnMilitaryTime$(StandardTime$;Seconds)''

*StandardTime$ - Time in AM/PM Format

==== fnCalculateHours ====
Calculates the difference between 2 specified times.

''fnCalculateHours(TimeIn$,TOut$,DaysIN,DaysOut)''

*TimeIn$ - From Time
*TimeOut$ - To Time
*DaysIn - Days Start
*DaysOut - Days End

==== fnBuildTime$ ====
Builds a time in the format used by the above functions.

''fnBuildTime$(H,M,S,P;Military,Seconds)''

*H - Hours
*M - Minutes
*S - Seconds
*P - Boolean indicating AM/PM - 0 is AM, 1 is PM
*Military - Flag indicating weather desired result is in Military Time or not
*Seconds - Flag indicating weather to count seconds or ignore them. (1 means count seconds)

==== fnParseTime ====
Takes a time and pulls out the values

''fnParseTime(T$,&H,&M,&S,&P)''

*T$ - the time to parse
*H - Return value for Hours
*M - Return value for Minutes
*S - Return value for Seconds
*P - Return Value for AM/PM

== FileIO fnSettings (Global Settings Code) ==

The FileIO library can be made to implement certain policies across the board. These are established by creating a file called fileio.ini and typing statements like the following into it. This file is "PROCed", so you don't want to put line numbers in it.

Anything you don't specify in fileio.ini will take its default value, shown below. So you only need to specify the items that you want to be different.

Note, for the boolean settings below, 1 denotes TRUE and 0 denotes FALSE.

let EnforceDupkeys=1 ! Enforce that key number 1 is unique key
let Defaultfilelayoutpath$="filelay\" ! Path To Your File Layouts
let Promptonfilecreate=1 ! Ask User Before Creating New Files
let Createlogfile=0 ! Use Logging
let StartFileNumber=1 ! Set above 300 to avoid conflicts with legacy programs.
let CheckIndex=0 ! Automatically Verify Indexes (slow)
let CompressColumns=0 ! Shrink or Expand Columns in Data Crawler by Default
let MaxColWidth=20 ! Max Default Column Width in Data Crawler
let LogLibrary$="" ! Defaut Log Library, defaults to None
let LogLayout$="" ! Log file layout, defaults to Internal File
let AnimateDatacrawler=1 ! Use ScreenIO Animation for Datacrawler
let TemplatePath$="filelay\template\" ! Default Template Path
let IgnoreLayouts$="" ! List any Ignore Layouts here.
let CloseFileSimple=0 ! Use simple comparison for fnCloseFile

==== EnforceDupkeys ====

Turn on the EnforceDupkeys option to force that the first key listed in your file layouts is a unique key. FileIO will generate the standard BR error for Dupkeys when attempting to create indexes if it is not unique.

==== DefaultFileLayoutPath$ ====

Use the DefaultFileLayoutPath option to specify the path from your programs to your file layout folder. The default is "filelay\". Use this setting if you want to place your file layouts in another folder from the default.

==== PromptOnFileCreate ====

Use the PromptOnFileCreate setting to cause FileIO to display a message box whenever it is attempting to create a new file. This happens during the automatic update procedure, as well as during any attempt to access a file that does not exist. This setting should be turned off in your live system, and only turned on for development purposes. If you use the message box to cancel creating of the new file, then the file is not created, and fileIO or your application will most likely give an error when you attempt to actually access the new file.

It can be useful during development to make sure that you don't accidentally create the wrong files, due to an incorrectly specified path or a typeo in the filename in the layout file. However, in a live system, these things have already been tested, and you generally want the default behavior, because you don't want your users to have the ability to cancel the normal operation of FileIO.

==== CreateLogFile ====

Use this option to specify weather or not to use the FileIO log file. If it is turned on, a log file called FileIO.log in the current directory is created with entries listing all attempts to open a file, automatically update one, or automatically update your indexes.

==== StartFileNumber ====

Use this option to set the starting file number that the fnGetFileNumber and the fnOpen functions use to search for available file numbers. This is so that if you have certian reserved file numbers in your code, you can make sure that FileIO will not use those reserved file numbers, causing a conflict with your already existing programs. The default is 1, which is fine if your software does not have any reserved file numbers.

The allowable BR file numbers are 1-200 and 300-999.

==== CheckIndex ====

This function is used for Partial FileIO Implementations. If all of your software uses FileIO then all of your indexes are kept automatically up to date by the FileIO library and BR's internal file processing systems. However, if some of your programs do not use FileIO, and you use the FileIO library to add a new index file that those other programs do not know about, then its possible for the additional index file to become out of date when the master file is updated by your other programs.

Use this setting to cause FileIO to check the DateTime stamp on all your index files when opening a new file, and automatically update any indexes that may have potentially gotten out of date from other programs.

This option slows down the processing of the fnOpen function, particularly when running under client server over the internet. If you know that every program in your application suite uses FileIO, and that any programs that do not use FileIO still properly update all the indexes that your data file uses, then you can safely leave this setting turned off, and optimize your performance when opening several files using the fileIO system.

==== CompressColumns ====
This instructs the datacrawler to use smaller widths for small columns. If CompressColumns is false, the data crawler will make the column the width of the field or the width of the caption, whichever is wider. If CompressColumns is true, it will use the width of the field, not the caption.

==== MaxColWidth ====
This limits the column width to a set amount. This is applied after CompressColumns above.

==== LogLibrary$ ====
If a library is specified here, then fileio looks for a BR library with the specified name, and attempts to call a library function in it called fnFileIOLog that. This function should expect six parameters, which are Logstring$, Login_Name$, Session$, Days of Date$, Time$, and CallingProgram$, if LogLayout is also nonblank.

If you specify a LogLibrary and LogLayout is blank, then it calls your function giving it only 1 parameter.

It will call your function '''''instead of''''' the normal log file. Use this to implement your own logging functions however you want.

==== LogLayout$ ====
Use this setting to specify an alternate file layout for an alternate file to do the logging in. Base the file layout for this file on the logfile we supply for you in the filelay folder. It should have at least those fields, which our log routine will automatically populate, but you can add other fields if you want (though you will need to manage them yourself).

If you don't specify LogLayout, the default filelay\logfile will be used. This will allow you to also use the fnViewLogFile function to access it.

==== AnimateDataCrawler ====
The sister library [[ScreenIO]] has a feature that allows you to use an animation of a clock in your loading screens in your own programs. If you have [[ScreenIO]] then FileIO will automatically detect it and use it to display a loading animation while the data in the data crawler loads.

Set AnimateDataCrawler to false (0) in your fileio.ini file to bypass the animations if you do have screenio but don't want to see the animations anyway.

==== TemplatePath$ ====
This setting points to the folder that contains the code templates used by the Generate Code button on the main page of the Data Crawler.

==== IgnoreLayouts$ ====
This is a comma delimited list of all layouts that you wish to suppress from appearing on the main page of the data crawler. You can still access these layouts with your code, but they won't be listed in the data crawler for you to access.

Whatever you're using for a log layout, is automatically added to this list.
==== CloseFileSimple ====
The fnCloseFile function closes all the individual handles to a data file that was opened for output using multiple keys.

For BR 4.18 and higher, we support a better algorithm for detecting which files are matches for a given opened file number.

Set CloseFileSimple to true (1) to force it to check the old way.

== FileIO Add-on Packages ==

Many FileIO Add-on packages are currently in the works.

=== ScreenIO Library ===

The [[ScreenIO Library]] is a sister library to the FileIO library. The ScreenIO library requires the FileIO library in order to run.

The ScreenIO library is a complete Rapid Application Design tool that enables you to implement custom screen functions anywhere in your exiting programs.

If you call the ScreenIO Library as a function library, you call a function called fnFM and tell it which screen you wish to use. The ScreenIO library loads your user interface, loads your data files, and preforms all the file maintenance operations you have designed into your screens.

You can find out the latest information about the ScreenIO library in the ScreenIO page.

=== Audit BR ===

The [[AuditBR|Audit BR]] developer tool makes a backup copy of your file layouts. Then you run some code you're trying to test, and finally, run Audit BR again, to get a report showing all the changes to any of your data files automatically.

AuditBR is now included directly in FileIO. To use it, select the layout from the list of layouts in the Datacrawler and press the "Compare" button.

== What’s New (also described above) ==
=== 2018 ===
*Support for dates in any storage formats on disk (v2.48)

=== 2015 ===
*Added Rec to display for fnShowData
*Added FormStatement$ for debugging of form statements inside fileio
*Added mat BadRead$ for debugging of 726 errors when making new layouts
*Fixed a bug causing crash when logging things from long program folders
*fnClientEnv$ - reads a Windows Environment variable on the client using the command shell
*fnAskCombo$ - added an optional parameter to set default selection.

=== 2010 - 2014 ===
*FileIO now caches your file layouts in memory to make it much faster then before when opening the same data file in multiple programs.
*Generate Layout Wizard
*fnShowData
*Improved Logging
*fnViewLogFile
*Import/Export
*Import/Export by Function
*Many other speed increases
*if ScreenIO is present, Datacrawler uses the animation routines
*fnBuildProcFile & fnRunProcFile
*fnGenerateLayout & fnWriteLayout
*fnReadForm$
*fnReadFormAndSubs
*fnGetFileDateTime$
*fnReadLayoutPath$
*fnSortKeys
*fnSetLogChanges
*fnLogChanges
*fnLogArray
*fnReadScreenSize
*fnEmpty
*fnEmptyS
*Many other useful functions that were added to the documentation at earlier dates.

=== Spring 2009 ===

'''''New Functions:'''''

The FileIO Library has been updated in Spring 2009 to provide several new functions:

*fnReadRecordWhere
*fnKey$
*fnBuildKey$
*fnReadUnopenedDescription$
*fnUpdateFile
*fnDisplayLength
*fnLength
*fnReadLayoutHeader
*fnReadEntireLayout

'''''Speed Increases:'''''

Thanks to the BR [[Profiler]], we have increased the speed of FileIO fnOpen function by ten times when running over a LAN and by 100 times when running over the internet using Client Server.

In order to get the new Speed Upgrades, you will need to make sure that you use the latest copy of the [[#fnOpen_Function|fnOpen]] function in each one of your programs that use FileIO.

'''''Network FileIO:'''''
This version of FileIO has been optimized to work better in network situations.

'''''FnSettings: '''''
There are more configuration options in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine.

'''''Automatic Update Speed Fix:'''''
The automatic update proceedure has been made to run more then 100 times faster then before according to our benchmarking tests.

=== Fall 2008 ===
'''''DataCrawler Grid:'''''

By popular request we added a read/write version to the data crawler. This version works exactly the same as the datacrawler did before but it displays all the contents of your data files in a grid instead of a listview.

When you run the fileIO library as a program, it launches a tool known as the [[#DataCrawler|DataCrawler]]. The DataCrawler shows a listview displaying all your layout files in it. If you select one, it builds another listview with all the data in your selected data file.

If you are looking at the first list of all your file layouts, and you press F5, a grid will be build displaying all the data in your data files. You can change any of the records you like, and when you're done, your changes will be saved to the data file. Additionally, you can Add or Delete records using the buttons at the bottom. Any changes you make are not written to the disk until you click the "Save" button. If you press ESC (Cancel) the grid is closed and all changes you made sinse the last save are lost.

This tool is for programmers only. Do not give your end users access to the DataCrawler.

Use the DataCrawler at your own risk. Gabriel Bakker and Sage AX are not responsible for any harm that comes to your data files through the use of this or any other tools we offer.

The DataCrawler is not designed to be used to maintain your data files. It can be used carefully to correct small things in your data files.

'''''Support for Nonstandard Paths:'''''

Many BR Vendors keep different versions of the same data files in different locations. For example, sometimes a BR vendor will use a different Data folder to represent data for different Warehouses, or Customers. In cases like this it is necessary for your programs to specify the path to your data files. They may do so by specifying the optional "PATH" parameter to your data files. See the section [[#fnOpenFile]] for more information.

'''''Support for Nonstandard Layout Files Path:'''''

Old versions of the fileIO library required you to place all your file layouts in a subfolder of your program directory called "filelay". We have now changed the Fileio library to allow you to place your file layouts any place you want. The only requirement is that they are all together in one folder by themselves.

If you use a nonstandard path in the fileIO library, it is necessary to make a change to the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code in your copy of fileio.br.

'''''Prompt on Create:'''''

The FileIO library automatically creates any data files that it can't find. This was done to make it easier to deploy your finished programs - if you had any empty data files you could omit them from the packages and they would be created when they were needed, on the fly.

The current version of the FileIO library contains the same ability. However, it prompts you before creating any data files. This helps to avoid bugs that happen from incorrectly specifying the path to your data files.

However, if you do intend for your data files to be autocreated, then you probably don't want your end users to modify them. Therefore, you can use the PromptOnCreate setting in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code to specify. If this value is set to true, then the fileIO library will prompt you whenever it attempts to Autocreate a data file. If it is set to false, then the fileIO library will create the data files without prompting you, like it always did before.

'''''fnSettings:'''''

The newest version of the FileIO library supports some features that require you to specify Global Settings values. These are done by modifying the contents of the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine at the beginning of the fileIO library.

=== Fall 2006 ===
Many improvements have been made in the FileIO library over the summer. This section is intended to acquaint you with the highlights of those changes. Most of these improvements were built from ideas generated during the discussion at the April conference.

'''''Intermixed String and Numeric Specs:'''''
The File Library has been expanded to allow the reading of data files that contain mixed string and numeric specs. This is to aid those of you who are planning on implementing the FileIO Library on existing data files which may not be organized with strings first and numbers second.

The central idea of the FileIO Library is based upon the reading of your data files into a String and Numeric array. This will enable you to refer to the fields in your file by using a named subscript, saying F$(FM_NAME) to refer, for example, to the farm file’s name field. The advantage to this is that when you change the file layout, all your existing programs will not have to be modified, because they will only be looking at F$(FM_NAME). If the name field changes from the third string field to the fourth, the value of FM_NAME will also change, and you won’t have to worry about updating your data files.

However, in order to support the reading of a data file with intermixed string and numeric specs, the generated form statement will actually calculate the position of any fields that are not in order, so that the file read statement will still return all string fields first (into your string array) and the numeric fields second (into your numeric array). You do not need to worry about this; the library does it for you. All you have to do is read your file and use the data values.

The only thing that is required is making sure that all your string subscript names end with a “$”. This will tell the library that they are strings. Thank you, George, for this suggestion.

'''''Versioning / Automatic Updates:'''''
The file layouts have been expanded to contain a version number. This version number will be used to determine when a file needs to be updated. The version number is the third parameter in the file layout.

Any time you wish to change your file layouts, simply increment this version number. Each time the library attempts to open a data file, the file’s version is checked and compared with the version in the file layout. If the file layout has been changed (if the version in the file layout is greater then the version in the file) then the file will be updated to the latest version. Depending on the file size this may take a couple of moments. A simple progress bar will be displayed on screen while this is happening. The progress bar will be displayed in its own window, so it should not affect anything your programs may have had on screen.

The library uses the following procedure for updating a file. First, the file is copied to a backup file (prefixed by the letter ‘o’ for old). So color.dat would become ocolor.dat, and color.key would become ocolor.key. Then the new file is created and marked with the proper version number. (color.dat, color.key). The old file is opened in read-only mode, and the new file is opened for OutIn. The update routine actually reads through the old file layout, and one record at a time creates a new record, using the new file layout, with the same data, saving it to the new data file.

When it is done upgrading, the progress bar window is closed, and the file is reopened in the fashion you described in your call to fnOpen, and flow returns to your program as though nothing unusual has happened.

If an error occurs during processing, the routine will do what it can to roll your data files back to the previous version, but please make frequent backups of your data files anyway, just to be safe.

'''''Error Checking – If there is a mistake in the file layout:'''''
The routine attempts to discover the cause of the error in the case that one is encountered due to a missing file, a file sharing violation, or an invalid or corrupt file layout. If this should happen, the program is paused, and a text message is printed out explaining the most likely source for the error, including what part of the file layout, if any, may have caused the error.

You may then examine the printed text, and the contents of the BR system variables ERR and LINE to determine the problem. If you type “GO”, the next line will be execute “system”, ending your program.

If the file was in the middle of an upgrade when the error happened, it will be automatically rolled back to the previous version, so that when you fix the problem and try to run your program again, the file will again attempt to update from the beginning, and you won’t have to worry about corrupted data.

However, please backup your data before upgrading your data files anyway, just to be safe.

'''''Implementation of Keys / Creation of New Data Files:'''''
The library has been expanded to automatically create all new data files, and to automatically update any existing files. This means that in the file layout header, two new fields that were previously ignored are no longer ignored. The RECL value that you specify in your file layout will be used, along with the description/definition of your keys file. When you open a new file (or update an existing one), the library will calculate the proper kps and kln by evaluating the key description. This key description must match up with subscript values from the data elements in your file, and more then one may be specified, but they must be separated with slashes (/). If I wanted my Farm File to be keyed based on CODE and NAME, the proper key description would be:

farm.key, CODE/NAME

The library will then look up the position and length on disk of the CODE and NAME fields and put them together to create the proper keys during an update or creation of a new file.

'''''DataCrawler:'''''
Perhaps the most exciting new addition to the library is the addition of a programming tool I like to call a DataCrawler. If you run the FileIO Library directly as a program, instead of using it as a library, it will function as a DataCrawler. The DataCrawler requires a New Gui version of BR, as it requires a ListView to be able to properly and easily display the data in your files.

If you run it in an older version of BR you will get a message, telling you to run it in a newer copy. If you run it in a New Gui version of BR with CONFIG GUI OFF, then GUI will be turned temporarily on for the use of the DataCrawler and then turned off again when you are finished. If you run it in a New Gui version of BR with GUI ON, it will just run normally.

When you run the DataCrawler, first you will see a ListView displaying every file layout it can find in the filelay folder. If you select a file, the DataCrawler will open a large ListView with as many columns as there are fields in the file. The Column Headings will come from the element descriptions in your data files, and the column widths will come from the displayed width of the fields. There will be a row for every record in your data file, and you can resize the column widths, and scroll around the data file to view the raw data of your BR data files on disk.

If you are dealing with a particularly enormous data file (50,000+ records) it can take a moment to populate the ListView with the data in your data file. You may hit ESC to stop loading if you like, and view only the already loaded records.

If you would like to look up a particular record (based only upon the primary key for the data file), you may press F4. This will give you a window which asks you to input the key or partial key. When you press enter, the file will be reloaded, starting at the key you specified and continuing on to the end of the file, or until you press ESC. The records you are looking for should appear at the top of the ListView.

To reset the ListView and look at the contents of the entire file again, simply press F4, and enter a blank (“”) key.

Finally, as with any ListView, you may resort your data by clicking on any of the column headings. Then you can use the slider bar at the right to scroll down to the record you desire.

This is a programming tool and is not designed to be used by an end user. This tool will open your file in read-only mode. It will not allow you to modify the data; I leave that as an exercise for the reader. However, it will update any datafiles you view to the latest version (if they need to be updated) when it opens them, just as any other program that uses the library will do.

== Appendix (Examples)==

=== Example.br ===
00010 ! example.br - This program is an example of for the data reading simplification
00020 ! Copyright April 2006 by Gabriel Bakker
00030 ! Distributed open source as a Christmas gift to brag members
00040 !
00100 execute "config gui off"
01020 DIM form$(1)*255
01030 DIM color$(1)*255,color(1)
01040 DIM colorcat$(1)*255,colorcat(1)
02020 library "fileio": fnopenfile, fnreaddescription$
04000 !
04010 Openfiles: ! Open your files here
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)
06000 ! gosub WriteFiles ! If you want to test this line, make sure to drop flag from 4030
07000 !
07010 MainBit: ! This'un here's tha Main Bit
07030 RESTORE #ColorFile:
07100 ReadNextcolor: ! Read next record
07120 read #ColorFile, using form$(ColorFile) : mat Color$, mat Color eof EndReadColor
07180 PRINT Color$(co_name)&" ("&Color$(co_html)&") is a member of the '";
07190 PRINT trim$(fnReadDescription$(ColorcatFile,cc_Name,Color$(co_category),mat Colorcat$,mat Colorcat,mat form$))&"' category."
07290 goto ReadNextColor
07300 EndReadcolor: ! Finished with Color File
08000 STOP
25000 !
25010 WriteFiles: ! Uncalled routine to demonstrate writing files
25105 let color$(co_code)="GD" !:
let color$(co_Name)="Gold" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFD700"
25110 write #colorfile, using form$(colorfile): mat color$, mat color
25115 let color$(co_code)="LV" !:
let color$(co_Name)="Lavender" !:
let color$(co_Category)="BL" !:
let color$(co_html)="E6E6FA"
25120 write #colorfile, using form$(colorfile): mat color$, mat color
25125 let color$(co_Code)="OR" !:
let color$(co_Name)="Orange" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFA500"
25130 write #colorfile, using form$(colorfile): mat color$, mat color
25205 let colorcat$(cc_Code)="YL" !:
let colorcat$(cc_Name)="Yellows" !:
let colorcat$(cc_html)="FFFF00"
25210 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25215 let colorcat$(cc_Code)="BL" !:
let colorcat$(cc_Name)="Blues" !:
let colorcat$(cc_html)="0000FF"
25220 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25300 return
40000 !
40010 Open: ! ***** Function to call library openfile and proc subs
40020 def fnOpen(FILENAME$, MAT F$, MAT F, MAT FORM$;INPUTONLY,KEYNUM,___,INDEX)
40025 dim _FileIOSubs$(1)*50
40030 let fnopen=fnopenfile(FILENAME$, MAT F$, MAT F, MAT FORM$,INPUTONLY,KEYNUM,MAT _FileIOSubs$)
40040 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
40090 fnend
50000 !
60000 Ignore: Continue

Color File Layout
color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

ColorCat File Layout
colorcat.dat, CC_, 0
colorcat.key, CODE
recl=127
===================================================
CODE$, Category Code, C 6
NAME$, English Name for Color, V 30
HTML$, HTML Code for the Color, C 6

Example Layout showing multiple keys (price)
price.dat, PR_, 0
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2

[[Category:Utilities_Third_Party]]

FileIO Library

2024-09-11T13:24:42Z

Gordon.dye: /* How it Works */

The '''FileIO''' Library began as a project to find a way to reduce the headache associated with making changes to data files. In my experiences working for [[BRC]], I had to make a change to the commun file, a data file that stores information about communication with EDI VANs. I added some new fields, and removed a couple of old fields, and then I began searching through the BRC program suite to find and modify each program that referenced this data file in order to update it with the proper new form statement. This task quickly became daunting as I noticed that out of BRC’s program suite of over 600 programs, more than one third of them referenced the commun file. With 223 programs to modify, the task was given up as hopeless and tabled indefinitely.

I am happy to announce that we have solved this problem. When I have to make a change to a data file layout for my customers today, I can complete the task in under 1 minute, and not a single program needs to be changed in order to continue working with the new file layout. In fact, I don’t even have to update my customer’s data files, as the FileIO library takes care of this for me as well.

The trick is to define your file layouts in an ASCII text file layout file that I will tell you about in a minute. The FileIO Library will actually parse through your file layouts, and it will instruct your programs how to read the data file, so that you don’t have to. It will also automatically detect when you make changes to the file layout, and it will update your customer’s data files on the fly to make sure they have the latest version. Finally, it even contains a DataCrawler that you can use to examine the contents of any of your BR data files in a raw format.

For more information about the FileIO Library visit the [http://www.sageax.com/products/fileio-library/ Sage AX Website]

To download the latest copy of FileIO, click [http://www.sageax.com/downloads/FileIO.zip here.]

== Method of Operation ==
The file IO library parses a formatted text file layout and uses this information to structure the opening and initializing of the reading of a file “object”. The word object here is used to refer to all the data in a given record layout in one of your files. This library is easy to use, and provided you follow some simple standards, it will simplify your life immensely.

Your programs will need to define one array for all [[Form|file layout form statements]] and add a snippet of code (given below) to the program for interfacing with with the library. For each file you will need to define a couple of arrays and use the library to open them. From that point on access to data is simple and direct.

=== File Object Arrays ===

First, in your program you must create two arrays to store the file information. If we are dealing with the Color File these would be MAT COLOR$ and MAT COLOR. One will store all the string information about a color, and the other will store all the numeric data. Our working example will involve two files: a Color File and a Color Category File. You should dimension these to:

01030 DIM color$(1)*1000,color(1)
01040 DIM colorcat$(1)*1000,colorcat(1)

We're dimensioning the string arrays to 1000. This is the length of one field in the color file. It needs to be at least as big as the largest string field in the data file.

However, it is recommended to make sure the length is long enough to handle any field you might eventually add to the file at any point in the future. BR supports multi-line textboxes, so I sometimes add long memo fields to my data files that might be 400 or 800 or even 1000 characters long, therefore 1000 is the length I use now in all my new development.

But anything will work as long as its long enough to handle the largest data field in your file.

=== Forms Array ===

Your programs will need a string variable array to store the form statements associated with reading files. This form statements array will be dynamically generated or expanded whenever the a file is opened. It will say:

01234 DIM form$(1)*255

This form statement will be compiled by the FileIO open statement. BR limits all form statements to 255 bytes, so 255 is sufficient to hold the compiled Forms$ statements.

=== Library Linkage ===

You will also need the library statement:

02020 library "fileio.br": fnopenfile, fnreaddescription$

=== fnOpen Function ===

Now, add a snippet of code to interface with the library.

Because BR libraries do not share global variables with the programs they are called from, we will need to execute a proc file whenever we open a file to set the names of all our variables after we return. Add the following snippet of code into your program. It will create an FnOpen function that calls the library and runs the proc file. The $$$ at the end of the procfile name tells the procfile to self-destruct after execution. Since this procfile is used simply to return variable information back from the library to the main program, we don’t need it sitting around collecting dust.

99010 OPEN: ! ***** Function To Call Library Openfile And Proc Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
99030 dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
99050 if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
99060 fnend

Or, for those with [[Lexi]]:
OPEN: ! ***** Function To Call Library Openfile And Proc Subs
def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
fnend

=== Using FileIO in Your Programs ===
Now you are ready to process files. 
'''''You simply open the files by saying:'''''

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

'''''read each file as follows:'''''

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
'''''and access the data:'''''

30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name)

=== How it Works ===
The above statements tell the File Library to look in the filelay folder to find the file layout for the Color File, and READ it to find out what the Color File looks like. Then it OPENs the Color File, and sets MAT COLOR$ and MAT COLOR to the correct number of elements to hold an entire color record. Finally, it will define several variables that we can use as pointers (subscripts) into these arrays to access the data read into the 2 arrays, and it will assign the file handle to a variable called "colorfile".

The second open above will do the same thing to the color category file, except the 1 parameter value tells the function to open readonly. The array subscripts populate procedure (passed back from Fileio) will be executed, thereby assigning values to the subscript names in the calling program. So, if I had a file layout such as the following:

color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

Then the functions would do the same thing as the following individual lines of code (assuming the next available file handle was 5):

DIM FORM$(5)*255
DIM COLOR$(9)*1023, COLOR(1)
OPEN #5: “Name=color.dat, kfname=color.key”,internal,outin,keyed
LET FORM$(5)=”form C 6,V 30,V 6,C 6”
LET FORM$(5)=CFORM$(FORM$(5))
LET COLORFILE=5
CO_CODE=1
CO_NAME=2
CO_CATEGORY=3
CO_HTML=4

The data is used by referencing the file array, with the subscript name, so the color’s description becomes color$(co_Name).

In the old days, if we wanted to change the file layout of our file, all of the programs that used that file would have to be changed one at a time to use the new file layout. Also, if the order of the fields changed, then all the programs would have to also be changed to use the new fields.

But now, using this function, we can change the file layout all we want. If we later want to insert a field into the file layout before color name, I won’t have to look at this program again; this program will just work fine, because the library maps the subscripts to the actual fields.

Also, the code is easier to read and maintain.

=== Example ===
The whole thing looks like this:

01025 ! Dimension the Arrays
01030 DIM color$(1)*1023,color(1)
01040 DIM colorcat$(1)*1023,colorcat(1)
01050 DIM form$(1)*255
02000 !
02020 library "fileio.br": fnopenfile, fnreaddescription$
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$) ! Open the file
05000 !
30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore ! Read the file
30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name) ! Use the data by referincing it in the file arrays
80000 !
90000 ! Every program using fileio needs the following code
99010 OPEN: ! ***** Function To Call Library Openfile And Generate Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths)
99030 dim _FileIOSubs$(1)*800
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$)
99050 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
99060 fnend

== File Layouts ==
Now lets inspect the anatomy of a properly formatted file layout. These should be placed in a subdirectory called filelay.

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...
<hr>
price.dat, PR_, 1

The first line contains the name of the Farm File, a unique string to prefix all of your subscript pointers, and the file version number. The subscript value is to ensure that the program knows the difference between the Farm File’s Farm Code, and the Route File’s Route Code. (One will be RT_CODE and the other is FM_CODE). These are separated by a comma. Spacing does not matter, so adjust your spacing so that it looks nice.

The Version number is used to determine when the data has changed, and an update needs to be made to your data file. Your file layouts should all start at version 0, and each time you want to make a change, you may increment this value by 1.

Each time you open a file with the FILEIO library, it reads the file version number of the file on disk (using the BR version() function), and then it compares it to the version number in your file layout. If your file layout has a higher version number then your existing data file, then the library opens the backup of the file layout for the version of the data file that exists on disk. It makes a backup copy of the existing data file, and creates a new file with the proper version number. Then it reads your records one at a time, and copies all the data from the old file into the new file one field at a time. If a field is dropped from the file layout, that data gets lost. If fields are rearranged, the data is copied and saved in the new file in the new positions. If a new field is added, it starts out blank (or 0).

If you look in the filelay folder, you will notice a version folder. This contains several files ending with a number. For example you may see a color.0, and a color.1 file.

If you run the fnopen function and it can not find your data file (usually because this is a new file and it hasn’t been created yet), ''the library will automatically create your file,'' based on the information you give in the first part of the file layout.

Also, whenever you make changes to your file layout, the function library will automatically update the data files on disk for you. It does this by renaming the old file, creating a new one with the new version number, and then copying the data from the old one to the new one a record at a time.

Any time it creates a file, or updates the file on disk, it creates a backup of the file ''layout''. The first time you run a program that tries to read your new data file, it will create the data file for you and make a backup of the layout, and if the number in your file layout is 0, then it will create, for example, a filelay\version\price.0 file, a backup of your file layout that the library uses to figure out what has changed the next time you try to update the file.

If you wish to make any changes to this data file, first you increment the version number, (in this case make the 0 into a 1). Then change the file layout all you want. You may rearrange fields, add new fields, add or remove keys, or change the record length.

The only step necessary for having your data files updated is to increment the version number every time you make a change to the file layout.

You may make any changes you like to the file layouts, but do not change the names of your existing subscripts. If you change the subscript name, not only will all the programs that reference that subscript be broken, but additionally, the routine will not understand that you are changing the name. It will think you are dropping the old field and adding a new field and any data stored in this location will be lost when the file is updated.

price.key, FARM

The second line contains the name of the first key, and a definition telling what the key is based on. These are separated by a comma. The key definition is made up of each of the subscript names in this file that form the keyfields for the file. When the library is called to open a file, if the file does not exist, or if it needs to be updated, a new one will be created. The function will read these subscript names that form your key definitions, and it will calculate the proper key position (KPS=) and length (KLN=) values. Then the create routine will use this information with the Index command to create the new key files.

price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127

Notice that the third key is based on three different fields. These are separated by a “/”. It is important that you use a “/” to separate your keys when you are building a key out of more then one field, because the function uses this “/” to help it make the proper BR syntax for defining complex key fields.

Also, note the "-U" at the end of the fieldname in the 4th key. This indicates that the "Description" part of that key is case insensitive. This translates to using the "U" on part of your key spec in Business Rules.

The file can have as many keys as you want. The function will keep parsing key file names until it reaches the next part of the layout. It opens any OutIn files with all keys so that any changes you may make to the data stored on disk will be properly reflected in all the key files.

The optional RECL= Parameter is read and used whenever a new file is created or an old one is updated. If it is not specified, the record length is calculated from the fields in the layout.

===================================================

The next line in the file is skipped by the parsing routine, and its purpose is to make the file layouts more readable to a programmer.

 
FARM$, Farm Code (or blank), C 4

Following the file and key structure, the fields are defined. There are three parameters on each field definition line, and you make one line for each field in your file layout. The first parameter is the subscript name that you will use in your program to refer to this data element. Place a $ at the end of the subscript name for all string elements. Don’t place anything at the end of the subscript name for numeric elements. Note that each of these names will be prefixed by the second parameter of the very first line of this layout.

The second parameter is the description. This description is for the benefit of the programmer, so when the programmer is reading the file layouts, (s)he can tell which field does what. The spaces are ignored, so you may include as many spaces as you wish to make the layout look good. It does seem like good general guidelines would be to limit your layout lines to 255 characters and your descriptions to 80.

The description is also used by the built in DataCrawler, a program that reads any of your data files and displays the entire contents in raw form in a listview. The Descriptions become the headings for each column in the listview.

Those descriptions are also used for the default captions for your fields if you use ScreenIO, a library for building GUI programs that itself builds off of fileio.

The third parameter is the form statement, which is pretty straightforward. Any items with a form statement of type “X” will be ignored, except that the length will still be used to calculate the position on disk of all remaining fields in the record. The library will take X fields into consideration when building the form statement, but not at any other time.

The fourth parameter is optionally a [[#Support for Dates|Disk Date Format]]. You can specify DATE(Julian) if you're storing your dates in Julian format on disk. Or you can specify DATE(cymd) or DATE(ymd) or DATE(mdy) or any other valid date spec here, and FileIO will treat this field like a date.

Your programs will still have to unpack it for you, fileio can't do that because fileio doesn't read the file for you.

However, the data crawler, the automatic updates, and screenIO, are all compatible with these dates specified in your file layout.

If the fourth parameter is anything other then DATE(format), then its treated as a comment and ignored.

The fifth and all later columns, if any, are treated as comments and ignored.

! default cost is normally zero
Comment line text must begin with an exclamation point, but it may be indented. Comment lines may appear anywhere (vertically) and are ignored. 
Blank lines are ignored as well.

#eof#
additional comments...
After the last field definition, an ''optional'' #eof# line may be specified, in which case any lines after that will be ignored.

 
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...

And that’s all there is to it.

=== Support for Dates ===
As of V2.48, file layouts support dates in any storage formats on disk. Whether you store your dates in Julian or in YMD or MDY or any other format, specify so in the 4th column of your file layouts, using the FileIO Date Keyword. ex: DATE(Julian) or DATE(YMD) or any other valid BR Date Format.

[[File:Dates0.png]]

When this is specified, it enables the FileIO data exploration tool (Data Crawler) to display the dates in human readable format. This works for both Viewing, and for Editing.

The new Date functionality also supports the File Layout Upgrade facility, allowing you to change the format of your dates on disk and FileIO will handle it automatically, upgrading the field to use the new date format for you.

It works also for Exporting your data files to CSV, and is supported automatically in the FileIO functions that do those exports. It converts the dates on export to a standard format (Default: m/d/cy) that you can specify in your FileIO.Ini File.

And it extends ScreenIO's date features to all date fields, no matter what format they're stored in. (Previously, ScreenIO's advanced date features only worked for dates stored in Julian on disk.)

This update adds two new ini file options:
CODE: SELECT ALL
DateFormatExport$='m/d/cy' ! Format of Dates when Exporting to CSV
DateFormatDisplay$='m/d/cy' ! Format of Dates when displaying in Data Crawler

You can use these to specify your preferred Date format for Viewing/Editing, and your preferred Date format for Exporting.

Remember, you can see the full list of FileIO ini file options, by looking in the source code at the top of FileIO.

There is a new optional parameter for all layout reading functions, mat NDateSpec$ and mat SDateSpec$ which correspond with the other arrays, to let you know which fields are date fields, so that you can develop routines in your programs to automatically pack and unpack the dates.

Important Note: Using FileIO, the reading of the data file is still done directly in your programs. So this does not change how your existing programs work. It does not unpack the dates for you in your programs. You still have to do all that.

For this reason, upgrading to the new Date processing will not break any of your current code.

=== Debugging Tips ===

When you're making new layouts, a missing comma can cause FileIO to parse the layout wrong and give you errors. Here are a couple tips to help ensure your layouts are error free before using them in your programs.

*Use the Data Crawler to test your layout. The data crawler is the simplest way to test your new layout without writing any code. It opens it and accesses the file in a very simple and straight forward manor to help identify any errors in the layout that you might have.

*If you have trouble with the form statement, you can't see whats in it because FileIO uses CForm$ to compile your form statement to make your programs run faster. But here's a way to tell what the original form statement was that FileIO generated when it put the strings first and numbers last in your program: Open the file in the Data Crawler. When you get an error, type "Print FormStatement$" to see the original form statement.

This works even if your file is working fine. Any time the file is opened with the data crawler, you can press CTRL-A and then type PRINT FormStatement$ and it will print out the uncompiled form statement for the file.

== Utilities ==

Now that you have your file layouts defined, you have access to several powerful utilities right out of the box using Fileio. Additionally, several more utilities are available as [[#FileIO_Add-on_Packages|Add-Ons]], including our most popular development tool [[Screenio|ScreenIO]]. You can read more about them in their section below.

But for now, lets take a look at some of the wonderful free utilities that come built into Fileio.

Some of these utilities are accessible from your code via library functions, but the primary way you access any of them is by simply loading the FileIO Library and running it directly.

=== DataCrawler ===
The data crawler is the original utility of FileIO. This utility shows you first a list of all data files allowing you to select one.

Select a data file and press enter, and FileIO will then display a listview containing all the data in the data file. This list is sized based on the size of your main BR window (window 0) automatically to take up the full size available to it, so if you want to see more, try [[Open Window|opening window 0]] larger before running FileIO.

At the top of the window is a filter box, and you can type anything you want in there and click "Refresh" and it will reread the data file, shortening the list to show only those records that match (case insensitive) what you have typed.

If you have ScreenIO installed, then FileIO's data crawler will take advantage of the included Animation Engine in ScreenIO to animate a loading window while the listview is displaying. If you don't have ScreenIO then FileIO will simply load the listview.

If you don't want to wait for the entire file to load, press ESC to stop the load process.

If the file is empty, FileIO will display a message box letting you know.

This tool is very useful for sorting out data errors. It will allow you to look inside any data file you have a layout for and directly view the data there.

At the bottom of the Data Crawler are several buttons. There's a Jump button that repositions the file by a key you specify and then loads the list with the data from that key on down to the end of the file.

There is a "Columns" button which you can use to decide which columns should show up on the listview. Fewer columns means faster loading so sometimes for large files I press ESC immediately when the file first starts loading to cancel the load. Then I click "Columns" and check only the columns I want to see. Finally I press the "Refresh" button to trigger it to read the file again and this time it loads much faster then before.

Next you'll find an Export button which starts the process for exporting a file to CSV. You can read more on that in the next section. And next to that is a Quit button.

In this example, we loaded the file "Read Only" so it put everything in a listview. But there are times when its useful to fix data errors this way too, especially during development. So if you want to directly edit your data file, on the first page select the file you want to edit and instead of pressing "Enter" or clicking "View", this time press "F5". F5 is the secret Edit button that loads a data file into a grid instead.

You can use the grid to change records, delete them or add them, and in addition to the buttons listed above, it also has an "Import" button for importing a CSV file into this data file.

Any changes you make to the data file are not saved until you click the "Save" button (which also only appears when you're in Edit mode).

In the 01/2015 release of FileIO, each records rec # is displayed in the listview, to aid in debugging bad data problems.

==== Debugging Tip ====
Any time you're viewing a file layout in the Data Crawler, you can see the Uncompiled Form Statement by pressing CTRL-A to get to an ATTN prompt, and then entering the command:

print FormStatement$

and it will print out the original form statement.

==== Another Debugging Tip ====

The FileIO Datacrawler ignores records that it cannot read. This is to allow for data files that have multiple record layouts in one data file. You make a custom layout for each record type and the data crawler shows just the records that match that type in the file.

However that becomes a problem when you're making a layout to work with an existing data file. Error 726 indicates that something minor in the file layout doesn't match the data on the disk, but these errors are ignored so you might see either an empty data file, or a data file with some records missing. If that happens, you need to see the missing records in order to figure out what is wrong with your layout. '''''It's very important that you don't try to use a file layout that isn't quite working right. Make sure your layout works and can read every record of a file that it should read before using it.'''''

To see the records that could not be read in a file, run the data crawler on the layout, then press CTRL-A to get an ATTN prompt. From there, enter the command

print mat BadRead$

and it will print all the records that were ignored because the file layout didn't match them. It prints out the raw data from the file.

==== Function Access to use Data Crawler in your programs ====
You can use the data crawler in your own programs by using one of the following functions:
* [[#fnDataCrawler|fnDataCrawler]] - Open a Listview showing the data file
* [[#fnDataEdit|fnDataEdit]] - Display the data in an editable grid
* [[#fnShowData|fnShowData]] - This function does the same thing as the above two, but with many many more options allowing you to customize exactly what appears and exactly what they're allowed to change.

Note: its not recommended to allow your customers to use the data crawler to access your data files directly. There's no way to specify validations or do anything complicated, so unless you're careful, there are lots of ways your customers could use this tool to do damage to your data files. It is a programmer tool only.

If you do decide to use it for your end users, be careful how you implement it.

=== Import/Export to CSV ===

You can use FileIO to export your data files to CSV or import from CSV into your data file. To do this, you want to run the data crawler and select the file layout you're looking for. Then, view it (or press F5 to edit if you want to import something). Click on the Export button and it will ask you to select a file. Once that is selected it will ask a couple other simple questions, and when you've specified the options to your satisfaction, click the Export! button. A new CSV file will be created.

Import is even more simple. To import, you must be in Edit mode (press F5 to select the file instead of the enter key) and then simply select the Import button. It will ask you again to choose the file, and then it will ask you if it should update all files by Record Number (if record number is recorded in the CSV file) or by Key (if the file has keys) or to just Add all information to the file. Select what you want and press Import and the CSV file is added to the BR data file.

==== Function Access to Import/Export from your programs ====

You can use the following functions to call the Import and Export functionality from your code.

*[[#fnCSVImport|fnCSVImport]]
*[[#fnCSVExport|fnCSVExport]]

These functions are intended to give you the ability to use our functionality to write your own import and export routines for your customers, because its not a good idea to let your customers run the Data Crawler.

=== Generate Layout Wizard ===

There is also a Generate Layout Wizard utility in FileIO. This utility is there to help you build your file layouts. It is designed to work with a certain style of BR programming that was common in the 80s and 90s. So if your software is written in a style that opens the file directly, and reads/writes the data to a long series of individual variables, the Generate Layout Wizard is for you.

To use it, start by running FileIO. Then, don't select a layout - instead, click on the "Generate Layout" button.

You'll see a screen with a bunch of large text boxes, a small grid, and some buttons.

The first thing you want to do is select the "Browse" button and then select a .wb or .br file that contains a program that reads or writes Most of the File.

When you select one, press the Scan All button and it fileio will search the whole program looking first for all the open strings. It will take the file that is opened the most times and then search for all read statements to that file. It will look for the longest read statement and then find the Form statement associated with that Read statement, and any DIM statements for any variables used.

If you don't like the file its chosen, click the "Open Scratch Pad" button to open the temp work file it uses into the program of your choice (I use myEdit for BRS files). Simply select all the open statements for the file you DO want to build off of, then click the Paste button to paste those open statements into the "Open String" list. After that click "Clear All" to erase what it did on the first search and then click "Scan All" again to rescan the program using this new data file.

You may have to help it a bit, but once it has a proper matching open statement, read statement, form statement and dim statements for any arrays used, press the "Generate Layout" button and it will build a layout for that file.

Finally, load the layout it built and clean up anything if you want, and consider adding better descriptions for each of the fields that you know (as it will use the variable names for both the subscripts AND descriptions in the layout).

When you're all done, click "Done".

==== Functions to Generate Layouts from your code ====

* [[#fnGenerateLayout_.26_fnWriteLayout|fnGenerateLayout]]
* [[#fnGenerateLayout_.26_fnWriteLayout|fnWriteLayout]]

=== Code Templates ===

One more tool FileIO has to help is the ability to generate code based on your file layouts.

Run FileIO and this time select a file layout and press "Generate Code". A window will pop up listing all the "Code Templates" that are available. Select one (and then select a key if it asks you - some templates require extra info). It looks like nothing happened, but the code you generated is now in your clip board. Paste it somewhere and take a look at it!

Code Templates help us to standardize our ways of doing things, which eventually leads to more and more powerful tools we can use. Code Templates also help ensure we use cleaner code by doing some of the busy-work of writing clean code for us.

==== Writing Code Templates ====
FileIO ships with several basic code templates. If you want to add your own, take a look in the filelay\templates folder (configurable in fileio.ini) and look at basic.brs. Copy it to your own program and then modify it to have your own code templates in it. Write me at gabriel.bakker@gmail.com with any questions. I want to help.

And if you write good code templates, its easy to share them with the BR community. Anyone can download your templates and place them in this folder and they'll instantly be available for use.

== FileIO Function Reference ==
''The FileIO Library contains a number of other useful functions.'' The following functions are available and you are welcome to use them:

=== Primary Functions ===

==== fnOpen ====
fnOpen is the primary function that opens a file, and it’s used like so:

''def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, DontSortSubs, Path$*255, Mat Descr$, Mat FieldWidths, SupressPrompt, IgnoreErrors, SuppressLog)''

Note that all of the parameters after MAT Form$ are optional. If you need to specify a parameter in the middle of the optional parameter group, just list zeroes and empty strings for the intervening unused parameters.

*FileName$ - The filename of the file layout for the file you’re reading.
*MAT F$ - The array that will be used to hold the string data for the file.
*MAT F – The array that will hold the numeric data for the file.
*MAT Form$ - An array of form statements.
*InputOnly – 1 means open for input only. 0 means open for OutIn and open every key file associated with the given data file (this is because all key files need to be open for the keys to be updated on an output) (defaults to 0). Files opened for input process considerably faster than files opened for output. Furthermore when files are opened for input only, alternate key files are ''not'' opened.
*KeyNum – This tells the function of which key to return the file handle (defaults to 1). Specify -1 to force the file to open Relative, without using its keys. If a file has no keys, it will always be opened Relative.
*DontSortSubs – The function by default, when compiling the Form statement, will sort the string and numeric subs in order to allow for reading the data into an array, and this parameter would turn this functionality off. However, if you are trying to read your data without reading it into an array, you are missing out on some serious efficiencies. You should normally leave this option turned off (0). This is a totally unsupported feature, and should always be set to 0, if it is specified at all.
*Path$ - The path to your data files. This optional parameter can be passed in by the calling function. It is prefixed to the beginning of the paths given in the file layout files. It is useful when your data files can be in different locations depending on the state of your program.
*mat Description$ - This optional parameter provides a way to read the description for each field from the original file layout. If the parameter is not provided, no description data will be returned.
*mat Fieldwidths – This optional parameter will return an array of the calculated display field widths. This number will always be at least large enough to contain the data for this field.
*SuppressPrompt - This optional parameter can be used to suppress the prompt normally given when fileIO creates a file. It can have three values. A value of 0, the default, uses the setting stored in your FileIO fnSettings routine to determine weather or not to prompt on Creation of a new file. A nonzero value always suppresses the prompt. A value of 1 indicates never to create a file if the file doesn't exist. A value of 2 automatically creates the file if the file doesn't exist.
*IgnoreErrors - Normally when fileio opens a data file, if there are errors trying to open the file, it prints them out to the debug console and pauses so that you can try to find out whats going wrong. If you specify 1 for "IgnoreErrors" it will cause Fileio to log those errors instead, and continue loading your program. This will result in the fnOpen file function returning Zero instead of the opened file number, so if you use IgnoreErrors, you need to test to make sure that fnOpen returned a file number before you try to access the file.
*SuppressLog - this optional parameter can be used to suppress writing to the log file for this one specific open statement. I use it for files that will be opened all the time, for example, the menu data file on one of my customers systems. Without this boolean parameter, his log file is quickly filled up with useless information any time his employees look at his menu. I specify this optional parameter to suppress logging anything about the menu file so that I can more easily find the actual programs they've used when looking in the logfile.

'''''Note: When using fnOpenFile, you really want to call your local function fnOpen, which in turn calls fnOpenFile for you.''''' FnOpenFile is for internal use only.

Example:

Let FFILE=FNOPEN(“FARM”,MAT FARM$,MAT FARM,MAT FORM$,0,2)
Let RFILE=FNOPEN(“ROUTE”,MAT ROUTE$,MAT ROUTE,MAT FORM$,1,3)
Let CFILE=FNOPEN(“CUSTOMER”,MAT CUSTOMER$,MAT CUSTOMER,MAT FORM$)

assuming:
farm.dat has 3 keys: farm.ky1, farm.ky2, farm.ky3
route.dat has 4 keys: route.ky1 … route.ky4
customer.dat has 2 keys: customer.ky1, customer.ky2

This will perform the following opens and set the following variables:

OPEN #1: “Name=Farm.Dat, kfname=farm.ky2”,internal,outin,keyed
OPEN #2: “Name=Farm.Dat, kfname=farm.ky1”,internal,outin,keyed
OPEN #3: “Name=Farm.Dat, kfname=farm.ky3”,internal,outin,keyed
OPEN #4: “Name=Route.Dat, kfname=route.ky3”,internal,input,keyed
OPEN #5: “Name=Customer.Dat,kfname=customer.ky1”,internal,outin,keyed
OPEN #6: “Name=Customer.Dat,kfname=customer.ky2”,internal,outin,keyed
LET FFILE=1
LET RFILE=4
LET CFILE=5

This will also resize the arrays, set the form statement, and create all the subscripts to make accessing the data clear and simple, as in the above example. The KEYNUM parameter is where you list the key file you would like to use for reading and writing. The extra keys are opened to ensure that all keys get updated properly when the file is changed.

Example:
DIM FORM$(1),PRICE$(1)*255,PRICE(1),
DIM DESCRIPTION$(1)*80,FIELDWIDTHS(1)

Let PRICEFILE=FNOPEN(“PRICE”,MAT PRICE$,MAT PRICE,MAT FORM$,0,2,0,"",MAT DESCRIPTION$)

Assuming the Price File layout (filelay\price) contains:

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30

This will perform the following opens and set the following variables:

OPEN #1: “Name=Price.Dat, kfname=Price.ky2”,internal,outin,keyed
OPEN #2: “Name=Price.Dat, kfname=Price.ky1”,internal,outin,keyed
OPEN #3: “Name=Price.Dat, kfname=Price.ky3”,internal,outin,keyed
let PRICEFILE=1
let PR_FARM=1
let PR_ITEM=2
let PR_GRADE=3
let PR_DESCR=4
let PR_PRICE=1
let PR_COST=2
let PR_XOPRICE=3
let PR_XOCOST=4
let PR_MOPRICE=5
let PR_MOCOST=6
let PR_VOPRICE=7
let PR_VOCOST=8
MAT FORM$(1)
MAT PRICE$(4)
MAT PRICE(8)
MAT DESCRIPTION$(12)
MAT FIELDWIDTHS(12)
let FORM$(1)=CFORM$(”form C 4,C 4,C 4,POS 74,C 30,POS 50,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2”)
let Description$(1)= “Farm Code (or blank)”
let Description$(2) = “Item Code”
let Description$(3) = “Quality”
let Description$(4) = “Description of Price Rule”
let Description$(5) = “Default Price”
let Description$(6) = “Default Cost”
let Description$(7) = “Default Christmas Price”
let Description$(8) = “Default Christmas Cost”
let Description$(9) = “Default Mothers D Price”
let Description$(10) = “Default Mothers D Cost”
let Description$(11) = “Default Valentine Price”
let Description$(12) = “Default Valentine Cost”
let FieldWidths(1) = 4
let FieldWidths(2) = 4
let FieldWidths(3) = 4
let FieldWidths(4) = 30
let FieldWidths(5) = 8
let FieldWidths(6) = 8
let FieldWidths(7) = 8
let FieldWidths(8) = 8
let FieldWidths(9) = 8
let FieldWidths(10) = 8
let FieldWidths(11) = 8
let FieldWidths(12) = 8

There are a few things I’d like to point out about the example above. First, you will notice that the form statement jumps around to put all the strings first, and then the numbers last. This is why it has a “POS 74, C 30,POS 50”. Then notice that the subscripts for the string variables are 1 .. 4, and the subscripts for the numbers are 1 .. 8. Finally, the order of the Description and FieldWidth fields also match the sorted positioning of the Form Statement.

The reason that we sort our form statements is so that BR will allow us to read the file into arrays by saying:

Read #pricefile, using form$(pricefile) : mat price$, mat price

Without resorting, the above statement would give a conversion error as BR attempted to put the PR_PRICE field inside mat price$(4). However, because we have reordered the form statement, we are able to read them safely into two arrays, and then we will be able to use the values without caring what position they are in the file, by simply saying PRICE$(PR_DESCRIPTION) when we want the description, and PRICE(PR_PRICE) when we want the pr_Price field.

Another thing you may notice about the above example is that it gives the calculated display length for the numeric fields as 8, when on the disk (and in the file layout) they are listed as BH 3.2. The reason for this is the program looks at the BH 3, and figures that a number that takes up 3 bytes on disk has a potential maximum size of 256**3 or 16,777,216, and therefore will need up to 8 characters of screen display space to view.

Finally, note that any field with a form statement of X is ignored by the library, except that the blank space is used when building the FORM statement.

==== fnCloseFile ====
This function will close the specified file number and all keys that were opened with the file. The purpose of this function is to facilitate the closing of the extra keys that are opened when you open a file for OutIn with the library. There is no need to use this for files opened for input because it is easier to just close the file directly. Secondary keys are not opened by FileIO for files opened for input only.

You must give the function the name of the file layout. It uses this information to determine how many keys were opened, and how many it must therefore close.

Then it basically starts at the file number you gave it, and closes the next X files that were opened with the same file name as this, where X is the number of keys associated with this file.

The syntax is:

''fnCloseFile(filenumber,filelay$;path$)''

*FileNumber – The filenumber of the file you are trying to close.
*FileLay$ - The name of the file layout for this file. This is used to determine how many keys the file would have been opened with and therefore how many we now need to close.
*Path$ - Optional Alternate Path. Use to close files that were opened using the open file's optional alternate path parameter.

==== fnGetFileNumber ====
FnGetFileNumber is a simple function to find a valid unused file handle. If you use this function in all of your programs, they will become much more portable, as you will never have to worry about your file handles fighting with each other. The function will return 0 if no free file number was found (but with 999 of them available now, I have never seen it happen).

''fnGetFileNumber(;X,Count)''

*X – This optional parameter will specify where to start looking.
*Count - This optional parameter will specify how many file numbers to find in a row. If count is 3, then fnGetFileNumber will return the first filenumber in the first gap of three unused file numbers that it finds.

=== File Reading Helper Functions ===

These functions perform various useful calculations to aid in interacting with data files when you're using fileio.

==== fnBuildKey$ ====
This function will return the key for a given record in a data file. It actually reads the file layout and builds the key to match the layout.

''FnBuildKey$(Layout$, Mat F$, Mat F; Keynum)''

*Layout$ - the name of the data file to build the key for.
*Mat F$ - the string array of the file object
*Mat F - the numeric array of the file object
*KeyNum - This optional parameter specifies which of the key files in the given layout the key should be built for.

To use this, you want some code like in the following example:

mat customer$=("") : mat Customer=(0)
let customer$(cu_name)=CustName$
let customer$(cu_phone)=CustPhone$
read #customer, using form$(Customer), key=fnBuildKey$("customer",mat Customer$,mat Customer,2) : mat Customer$, mat Customer nokey KeyNotFound
! The above code assumes that the second key of the Customer file is based on the Name and Phone fields.

By using this logic you are able to avoid directly specifying the key in your code - which means that even if the key changes in the future, as long as your code specifies enough information, it will still find the correct key. In our example, even if we dropped the phone number from the key in the future, or even if we expand the length of the Customer Name field, our code would still work and fnBuildKey$ would still build the correct key without us having to look at or change our code again.

This kind of reasoning is central to the fileio system, which, when implemented properly, ensures that you can change your data files in any way you need to in the future, without breaking your existing programs.

==== fnUniqueKey ====
This function tests to see if a given key is unique to the specified file. This function is very useful for situations where you need to ensure that the user-entered key is unique.

''fnUniqueKey(Fl,key$*255)''

*FL – The file number of the opened file.
*Key$ - This is the key to test. If this key is the key for a preexisting record in the file, the function will return false. If this key can not be found in the file, the function will return true.

==== fnMakeUniqueKey$ ====
This function generates a unique key for a given file. This is useful if you do not care what the key is, but it needs to be unique. I use this function in situations where the user never needs to know what the given key is.

This function reads the key length for the given file. Then it returns a string that is the right length, which is generated by counting in binary until a key is found that does not appear in the file. The first key found for a 4 byte key field would be chr$(0)&chr$(0)&chr$(0)&chr$(0). If that key was already in use in the file, the function would return chr$(0)&chr$(0)&chr$(0)&chr$(1). If that one was also in use, it would then try chr$(0)&chr$(0)&chr$(0)&chr$(2), and so on until it found one that wasn’t in use.

''FnMakeUniqueKey$(fl)''

*FL – This is the file number of the opened file for the desired key.

==== fnKey$ ====
This function formats the key for the given file number. All it does is ensure the key is the correct length. You should use fnBuildKey$ instead to properly build the correct key for the record you want to read.

''FnKey$(FileNumber, Key$)''

*FileNumber - the file number we are formatting the key for
*Key$ - the key we are trying to format.

==== fnNotInFile ====
This function will determine if a non-key element in a line is unique. It works almost exactly like fnUniqueKey specified above, except that it allows you to enter the subscript value of the element you are checking for uniqueness. You can use this to look for uniqueness in any field, not just in the key field. Additionally, the search engine used by this function looks for a partial match, and will only return true if the given string is not found anywhere in the specified element for the given file.

''fnNotInFile(string$*100,filename$,sub)''

*String$ - Value to check for uniqueness in this file.
*Filename$ - This is the name of the file layout of the file you want to check. This file does not have to be open in order for you to search it, because the function will open it for you.
*Sub – This is the subscript value of the element you are checking.

==== fnSortKeys ====
This function takes an array of Primary Keys indicating records in the data file, and resorts it into the order you would have expected using one of the other keys for your data file.

For example: Lets say you had a customer file, and the first key was Customer Code and the second key was Customer Last Name. This function would take an array of Customer Codes and sort it into Last Name order.

This function requires the file to already be opened (which is usually the case when you have an array of keys from that file).

''fnSortKeys(mat Keys$,Layout$,DataFile,mat F$,mat F,mat Form$;KeyNum)''

*mat Keys$ - the array of keys. These keys are based on whatever key the file was opened with in DataFile.
*Layout$ - the file layout for the file.
*DataFile - the open file number matching the key file that matches mat Keys$.
*mat F$ - array sized to hold the strings from the data file. This is the array you get back from fnOpen.
*mat F - array sized to hold the numerics from the data file. This is the array you get back from fnOpen.
*mat Form$ - array of form statements, that you get back from fnOpen.
*KeyNum - This is the key that we'll sort based on. If not given, the first key listed in the layout is assumed.

=== File Reading Functions ===

These functions actually read information from your data file and return it. These functions can be used to simplify the logic in your programs for many common tasks.

==== fnReadAllKeys ====
This function will read through a file, returning the specified element(s) from each record into (a) dynamically dimensioned array(s). For example, I could tell it to give me the Inventory Code for every inventory item in my database in one array, while placing the Inventory Description (name) for each item into the corresponding position in another array.

''fnReadAllKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$;sub2,mat out2$)''

*Fl – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array
*mat out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

For example:

FnReadAllKeys(InventFile,mat Invent$,mat Invent,mat Form$,IN_Code,mat InvtList$,IN_Name,mat InvtNames$)

==== fnReadMatchingKeys ====

This function will read through a file, returning the specified element(s) from each record where the key matches the specified key into (a) dynamically dimensioned array(s). This function is the same as the above function except this one will filter the results, returning only those records where the key matches the specified key.

''fnReadMatchingKeys(Fl,mat f$,mat f,mat fm$,key$,keysub,sub1,mat out1$;sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - Only records where the key field matches key$ will be returned.
*Keysub – This tells the function which element is the key element for this particular file number.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadAllNewKeys ====

This function will read through a file, returning the specified element(s) from each record that isn’t already there into (a) dynamically dimensioned array(s). This function is the same as the above function, except this one will filter the results returning only those records that don’t already exist in the array (eliminating duplicates).

''FnReadAllNewKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$; dont_reset,sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Dont_reset – By default the array will clear the contents of the arrays that are passed in. This Boolean flag will instruct the function to not empty the passed in arrays.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadFilterKeys ====

This function by Mikhail Zheleznov is a modification of the above functions. Like its predecessors, it reads an entire file, populating the specified arrays with data from all or some of the records in the file. The given subscripts specify which fields to return from each record. The key given specifies search criteria for the records. The filter specifies filtering criteria that can be preformed on the data before it is returned.

''FnReadFilterKeys(Fl,Mat F$,Mat F,Mat Fm$,Key$,Keyfld,Sub1,Mat Out1$;Filter$,Filter_Sub,Readlarger,Sub2,Mat Out2$, Sub3, Mat Out3$, Sub4,Mat Out4$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - The key to search for in the read statements
*Keyfld – the subscript of the key field in the data file. This must match the key field specified in the data file otherwise the function won’t work.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Filter$ – This optional parameter identifies matches to search for in the records. It works in conjunction with Filter_Sub
*Filter_Sub – This parameter specifies which field to look for in the records for matches to Filter$. Only records which have Filter$ in the specified field will be returned.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.
*Sub3 – Subscript of the element to return in the third array. This is optional. If it is specified, you must give MAT out3$, or BR will return an error.
*MAT out3$ - Array in which to return the third (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub3 is given (non-zero). This parameter will not be used if Sub3 is not given or is given as 0.
*Sub4 – Subscript of the element to return in the fourth array. This is optional. If it is specified, you must give MAT out4$, or BR will return an error.
*mat out4$ - Array in which to return the fourth (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub4 is given (non-zero). This parameter will not be used if Sub4 is not given or is given as 0.

This function was written by Mikhail Zheleznov for the fileIO library.

==== fnReadDescription$ ====
''fnReadDescription$(Fl,Subscript,key$,mat F$,mat F,mat Form$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout) (RT_NAME, which should equal 2 after opening routefile (unless we change the file layout later)).
*key$ - Item that should match a key in this file somewhere (in this case it is the route code from the farm record).
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading they have to be dimensioned properly, which is why we use our colorcat$ and our colorcat for these parameters.
*mat Form$ - This will need to be our array of form statements, so the function can read the file properly.

Lets take a look at how this function works:

In the example program I used above, I am reading the Color File to get details about each color. The color file contains a colorcat code field, but I want to display the colorcat description. The colorcat file contains a few details about a color category, and it is indexed based on colorcat code:

route.dat, RT_
route.key, CODE
recl=512
===================================================
CODE, Routing Code, C 6
NAME, Routing Name Description, C 30
MOFT, T/A/C (truck/air/courier), C 1
SHIPPINGDAY, Day of Week for Shipping, C 7

Now, as you know, in the above example, we have already opened the ColorCat File, and we have opened and read a Color record.

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
30180 LET ccode$=color$(CO_CODE) !:
LET Name$=color$(CO_NAME)

Now all that’s left to do is to take the Color File’s ColorCat code and use it to look up the ColorCat File’s description.

30190 LET ColorCat$ = fnReadDescription$(ColorCatFile, CC_NAME, Color$(CO_CATEGORY),
mat ColorCat$, mat ColorCat, mat form$)

==== fnReadUnopenedDescription$ ====
This function accomplishes the same thing as fnReadDescription except that it opens the data file for you. It is slower then FnReadDescription$, but it is easier to use.

''FnReadUnopenedDescription$(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the value of the key field in the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2, so sometimes it is a good idea to design your data files so that string field number two is a descriptive field, like Name or Description.

This function only works on the first key file for each data file. This function is a convenience function but it is slow because it opens the file and closes it for each call. Opening a file is one of the most time consuming program operations.

==== fnReadNumber ====

fnReadNumber does the same thing that ReadDescription does except it reads a numeric field instead of a description.

Lets take a look at how this function works:

''fnReadNumber(Fl,subscript,key$,mat F$,mat F,mat fm$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout).
*Key$ - Item that should match a key in this file somewhere.
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading. They have to be dimensioned properly by [[FileIO_Library#fnOpenFile|fnOpen]].
*mat Fm$ - This will need to be our array of form statements, so the function can read the file properly.

==== fnReadUnopenedNumber ====
This function accomplishes the same thing as fnReadNumber except that it opens the data file for you. It is slower then FnReadNumber, but it is easier to use.

''fnReadUnopenedNumber(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the key of the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2.

==== fnReadRelativeDescription$ ====
This function is the same as fnReadDescription$ but for Relative Files.

''fnReadRelativeDescription$(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat F,mat form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedDescription$ ====
This is the same as ReadUnopenedDescription$ but for Relative Files.

''fnReadRelUnopenedDescription(Layout$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRelativeNumber ====
This is the same as fnReadNumber but for Relative Files.

''fnReadRelativeNumber(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat f,mat Form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedNumber ====
This is the same as fnReadUnopenedNumber but for Relative Files.

''fnReadRelUnopenedNumber(LayoutName$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRecordWhere$ ====
This function returns the record where the given element matches the given value. It does not depend on any key files, and it can be used to locate a record based on any element. However, it loops through the entire data file to do this and it could be a bit slow for large data files. This function opens the file for you, so the file does not have to be already opened.

''FnReadRecordWhere$(Layout$,SearchSub,SearchKey$*255,ReturnSub)''

*Layout$ - the layout of the file we are searching
*SearchSub - Subscript of the element to look in
*SearchKey$ - The value we are looking for
*ReturnSub - Subscript of the element to return

=== FileIO Utility Functions ===
==== fnDataCrawler ====
This function launches the Data Crawler as a function, so you can make your own programs link to it. Special thanks to Mikhail Zheleznov for turning the DataCrawler into a library function.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnDataEdit ====
This function is the same as fnDataCrawler only it opens a Grid for editing.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnShowData ====

This function builds a list or a grid in a floating window that is tied to a data file. It uses the same function that the datacrawler uses, but its much more customizable. All other datacrawler functions are just wrappers for this one.

The first parameter is the only required parameter.

''def library fnShowData(FileLay$;Edit,sRow,sCol,Rows,Cols,KeyNumber,Caption$*127,Path$*255,KeyMatch$*255,SearchMatch$*255,CallingProgram$*255,mat Records,mat IncludeCols$,mat IncludeUI$,mat ColumnDescription$,mat ColumnWidths,mat ColumnForms$,DisplayField$*80,mat FilterFields$,mat FilterForm$,mat FilterCompare$,mat FilterCaption$,mat FilterDefaults$,mat FilterKey)''

*FileLay$ - the file layout you want to display
*Edit - 1 for Edit (Grid) and 0 for View (Listview)
*sRow, sCol - the start position. if not given, its centered. If given but out of bounds, they'll be automatically adjusted to fit the grid on the screen.
*Rows, Cols - the size. If not given, defaults to fullscreen. If given but not big enough to fit the UI elements you request, they're automatically adjusted to fit everthing.
*KeyNumber - the Key to use when reading the data, used with other parameters. If not given, the file is read Relative for faster performance. Required if KeyMatch$ is given.
*Caption$ - the Caption to display, defaults to FileIO's Datacrawler
*Path$ - Alternate path to use for data files (Prepended to the name found in the layout)
*KeyMatch$ - Show only records that match this key. You can use Partial Keys. If this parameter is given, you must also give KeyNumber (above).
*SearchMatch$ - Show only records that contain this substring in them anywhere
*CallingProgram$ - used for logging purposes, pass in the system function Program$
*mat Records - Show only these records in the Grid. Use it to control exactly what the user sees.
*mat IncludeCols$ - Show only these columns. These column names must match the subscript names from the file layout.
*mat IncludeUI$ - Which UI Options to show. Build this array with one element for each optional UI element to include. Explanations of UI elements follow:
**"ColumnsButton" - adds a Select Columns button that the user can use to modify which columns appear on the list.
**"ExportButton" - adds an Export to CSV button that exports the data to a CSV file.
**"ImportButton" - adds an Import from CSV button that imports from the CSV file.
**"AddButton" - adds a button that can be used to add records to the data file.
**"SaveButton" - adds a button allowing the user to save changes
**"DeleteButton" - adds a button allowing the user to delete a row
**"KeyButton" - adds a button allowing the user to jump to a specified position by key or by record number (depending on if the file is opened keyed or not)
**"QuitButton" - adds a Quit button to the screen (the Esc key also quits)
**"Search" - adds a case insensitive search box to the screen.
**"Border" - adds a border around the screen
**"Caption" - adds a caption. (If you specify a caption, this is automatically turned on. If you don't specify a caption but turn on caption here, then FileIO uses the default FileIO data crawler caption.
**"Recl" - adds the Recl to the caption
**"Position" - adds the positions to the field descriptions in the column headings.
*mat ColumnDescription$ - Show these captions. If blank, use the descriptions from the layout
*mat ColumnWidths - Use these widths for the data, if not given, calculate from the file layout
*mat ColumnForms$ - Display Format for the data, including DATE and FMT and PIC
*mat DisplayField$ - Counter Field to display on the Loading Window. If its a field with an associated DATE ColumnForms$ value, that column form will be used when displaying the Counter Field. It can be any of the following:
**REC - this will display the current "REC/LREC" data in the loading window.
**READCOUNT - this will display the "Record Count / LREC" in the loading window.
**FINDCOUNT - this will display the number of records that match the current search criteria by itself in the loading window.
**A Field Name - one of your field names will display that field value in the loading window
**A string literal - anything else will display as a string in the loading window, so you could put something like "Loading, please wait" here and it will display.
*mat FilterFields$ - Contains the subscript of the field to compare to
*mat FilterForm$ - Contains the format of the field to compare to
*mat FilterCompare$ - Contains the comparison type ("<>" or ">" or "=" or ">=" or "*") (* means do a substring search)
*mat FilterCaption$ - The caption for the filter box
*mat FilterDefaults$ - The default value for the filter information
*mat FilterKey - The action to use when filtering the data this way (0 means simple exclude, 1 means start here, -1 means stop here)
**The final five arrays can be used to add user filter boxes to the data grid. You need one element in each array for every custom user filter box on the screen.

==== fnBeginAudit ====

The [[AuditBR|FileIO Compare]] routine is available and can be called from within your programs. To do so, call fnBeginAudit to mark the Start of the compare, then do whatever you need, then run fnCompare to compare everything that has changed between when you ran fnBeginAudit and when you ran fnCompare.

See [[AuditBR#fnBeginAudit|the documentation]] for more details.

==== fnCompare ====

See [[AuditBR#fnCompare|the documentation]] for more details.

==== fnCSVImport ====

This function calls the FileIO Import routine, the same one that you get from the Datacrawlers Import Button.

''fnCsvImport(Layout$*64;SuppressDialog,FileName$*300,ImportModeKey)''

*Layout$ - The file layout to import into
*SupressDialog - 1 to Supress the Import Dialog
*FileName$ - the name of the CSV file (Required if Dialog is Suppressed)
*ImportModeKey - the Import Mode Key (Required if Dialog is Suppressed)
**-1 - Add all records to the file
**0 - Update by Record Number (The file must contain a RecNum column and it must be first)
**1+ - Any positive number means Update by that Key (as listed in the layout).

==== fnCSVExport ====

This function exports a data file to a CSV file.

''fnCsvExport(Layout$*64;SuppressDialog,Filename$*300,IncludeRecNums,KeyNumber,StartKey$,KeyMatch$,Startrec,mat Records,SearchMatch$)''

*Layout$ - The File Layout to Export
*SuppressDialog - (1 to Suppress the Export Dialog, 0 to show it)
*Filename$ - the output file name (Required if SuppressDialog is 1)
*IncludeRecNums - Include a column with the Record Numbers in it
*KeyNumber - Use this key when reading the data for export
*StartKey$ - Start with the record that matches StartKey$
*KeyMatch$ - Export only the record(s) that match KeyMatch$
*StartRec - Start with this Record Number
*mat Records - Export only these records
*SearchMatch$ - Export only records containing this search string anywhere in them

==== fnExportListViewCsv ====

Exports the contents of the specified Listview in CSV format.

''fnExportListViewCsv(Window,Spec$;GenFileName,Delim$,FileName$*255)''

*Window - The Window containing the listview.
*Spec$ - The Spec identifying the listview.
*GenFileName - Flag telling weather or not to generate the file name.
*Delim$ - Delimiter to use. Comma is default.
*Filename$ - Filename to use

==== fnGenerateLayout & fnWriteLayout ====

This function calls on the Generate File Layout Wizard to generate and save the layout indicated by the parameters you give it. You must give it the same valid parameters that you would have come up with if you worked through the layout wizard the normal way, by running FileIO directly and choosing "Generate Layout".

You can also bypass the automatic parsing and generate a layout by specifying all the data directly and using fnWriteLayout.

''fnGenerateLayout(mat OpenStrings$, ReadString$*999, FormString$*20000, DimString$*999; DisplayFile)''
''

*mat OpenString$ - array of all the open strings for the given file from one of your old programs.
*mat ReadString$ - solid read statement from one of your old programs reading the entire record, (or at least everything you want in the layout).
*mat FormString$ - the form statement that goes with the ReadString$ (practice using the Generate Layout Wizard the normal way for details)
*mat DimString$ - the string containing Dim statements for each array mentioned in ReadString$. We need this to know how big the arrays are.
*DisplayFile - if True (1), it will Display the new layout in notepad when its done creating it. If false (0), it will simply create the file.

fnGenerateLayout takes all the above information and parses it into a layout, then calls fnWriteLayout to actually write the layout.

If you already know the information you want to put in the layout, its more direct to call fnWriteLayout below.

''fnWriteLayout(Name$,FileName$*127,VER,PRE$,MAT KFNAME$,MAT KDESCRIPTION$,MAT SUBS$,MAT DESCR$,MAT FORM$;RECL,MAT EXTRA$,DISPLAYFILE)''

*Name$ - the name of the new layout
*FileName$*127 - the name of the data file
*Ver - the version of the data file
*Pre$ - the prefix to use for the data file
*mat KfName$ - array of all the keys for the file
*mat Kdescription$ - array of the subscripts that each key is based on
*mat Subs$ - the subscript for each field in the file
*mat Descr$ - the descriptions for each field in the file
*mat Form$ - the form specs for each field in the file
*Recl - (optional) the record length of the file
*mat Extra$ - (optional) Additonal Information for each field in the file, placed in the Comments column of the new layout. This column is ignored by standard fileio processing.
DisplayFile - if True, open the file in Notepad after it has been created.

==== fnSubstituteStringCode ====
A Large Text Field that is searched. Code is run and any resulting variables are set, if they exist inside String enclosed between Substitute Chars (default []), then they will be replaced with the values derived by the code.

''fnSubstituteStringCode(&String$,Code$*2048;SubstituteChar$)''

*String$ - the string to be searched
*Code$ - code to be run. The resulting variables can be substituted into String
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnSubstituteString ====
A Large Text Field that is searched. Any matching fields in the passed in record will be substituted into their places. For example, if the string contained [cu_name] and you ran substitutions on the Customer file, then [cu_name] would be replaced by the name in the actual Customer record.

''fnSubstituteString(&String$,Filelayout$,mat F$,mat F;SubstituteChar$)''

*String$ - the string to be searched
*FileLayout$ - the layout to be searched
*mat F$ - the record to be used for substitution
*mat F - the record to be used for substitution
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnShowMessage ====
Displays a message to the user, in a child window. Returns the child window number, so that you can close it when you're done with the message.

''WindowNumber=fnShowMessage(Message$*54)''

*Message - the Message to display to the user

=== File System Utility Functions ===
These functions perform other tasks that aid with interacting with the file system.

==== fnGetFileDateTime$ ====
This does a directory listing to determine the Last Modified Date and Time of the given file. You pass it a file name, not a file layout, and it can be used on any file. Its not limited to BR internal files.

The syntax is:

''let FileDate$=fnGetFileDateTime$(Filename$*255)''

==== fnProgressBar ====
There's a Progress Bar that FileIO uses when copying or updating data files. You can use it in your own functions by calling fnProgressBar inside the main loop of the process that you want to display the progress bar over, and by calling fnCloseBar when you're done.

''fnProgressBar(Percent;Color$,ProgressAfter,ProgressThreshhold,UpdateThreshhold,Caption$*255,MessageRow$*255)''

*Percent - Percentage Complete expressed as a float between 0 and 1
*Color$ - HTML Color Code of BR Color Attribute to color the Progress Bar. Defaults to Green.
*ProgressAfter - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*ProgressThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*UpdateThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*Caption$ - Optional message to display above the progress bar.
*MessageRow$ - Optional message to display on the progress bar.

==== fnCloseBar ====

''fnCloseBar''

Call this function to close the progress bar window when your task is done running.

==== fnCopyFile ====

''fnCopyFile(FromFile$*255,ToFile$*255)''

*FromFile$ - The file to copy.
*ToFile$ - The destination file name including path.

This function copies any file, by opening it as an external file and reading and writing the data to the destination file. The advantage of this technique, over using the BR copy command, is this routine is more reliable when run on client server where you may be transferring large files from one side to the other over the internet.

This fnCopyFile also has a progress bar that displays as the file is transferred, so the user knows your software is busy.

This function works over Client Server. Under Client Server, specify @: at the beginning of your filename, to specify that the file is on the client. If the file is on the server, simply leave the @: off. See the chapter on [[Copy#Client_Server|using BR's copy command under Client Server]] for more details on the "@:".

This function's parameters and syntax are modeled off of the built in BR copy command, and like that one, this should work for local transfers, LAN transfers, or even internet transfers. This function will work better for internet transfers then the built in BR Copy Command, however.

==== fnCopyDataFiles ====

''fnCopyDataFiles(DestinationFolder$*255)''

*DestinationFolder$ - the folder to copy your data files to.

This function reads your file layouts and makes a copy of every data file (and key file) in your system to the destination folder, utilizing fnCopyFile above, for better performance and reliability when running over the internet, as well as a progress bar for each individual file.

It also displays a listview while its copying so you can watch the progress while its transferring your data files.

This can be used for making backups of your BR data, or for transferring the latest data onto a laptop for access to it while you're on the road away from the internet.

==== fnReIndex ====

This function reindexes a single data file

''fnReIndex(DataFile$*255;CallingProgram$*255,IndexNum,Path$*25)''

*Datafile$ - the file layout of the file to index
*CallingProgram$ - used for logging, pass Program$ in here
*IndexNum - The index to rebuild - if not given, rebuilds all indexes
*Path$ - the optional alternate path to use for rebuilding the data file.

==== fnReIndexAllFiles ====

This function reindexes all your data files. It doesn't require any parameters.

''fnReIndexAllFiles''

==== fnUpdateFile ====
This function checks and Updates a data file if it needs to be updated, by opening and then closing the data file.

''fnUpdateFile(FileLayout$)''

*FileLayout$ - The name of the file to update

==== fnRemoveDeletes ====

This function, written by Susan Smith, removes deleted records by copying the file with the -D option.

''fnRemoveDeletes(LayoutName$*255;Path$*255,CallingProgram$*255)''

*LayoutName$ - the file layout
*Path$ - Optional Alternate Path
*CallingPRogram$ - used for logging, pass Program$ in here

=== Layout Interrogation ===
Layout interrogation functions are provided for convenience and to enable future dictionary changes without disrupting any programs that interrogate it.

==== fnMakeSubProc ====
This function obtains the subscript assignments that were assigned by fnOpen according to the file layout. The fnMakeSubProc$ routine obtains the subscript assignments without actually opening the file. This is useful when a file record is passed as arrays into a library function in another program, or when you chained to another program and you need to know how to reach the data in the arrays without actually reopening the file.

''fnMakeSubProc(filelay$;mat Subscripts$)''

*FileLay$ - The name of the file layout from which to read the subscripts.
*mat Subscripts$ - If you give this optional array, fnMakeSubProc passes the subscripts back in this array rather then in the subs.$$$ file. This is much faster and helps avoid sharing conflicts.

When this routine returns, you can set the subscripts in your program by executing every element of the Subscripts$ array in a for/next loop.

If you did not pass in a subscripts array, then the a procedure file named subs.$$$ is created. If you proc that file, the proper subscripts will be set.

==== fnReadLayoutArrays ====
This function reads the fields in a file layout into arrays. You call it like the following

''fnReadLayoutArrays(filelay$,&prefix$;mat SSubs$, mat NSubs$, mat SSpec$, mat NSpec$,mat SDescription$, mat NDescription$,Mat Spos,Mat Npos)''

*filelay$ - the name of the layout to read
*prefix$ - the return value for the prefix for the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

This function call would read the fields from the layout in filelay$, and it would return the prefix to prefix$. The Subs would be returned in mat SSubs$ and mat NSubs$.

The Spec statements are returned in mat SSpec$ and mat NSpec$ and the Descriptions are returned in mat SDescription$ and mat NDescription$. The start positions on disk of each element are returned in mat SPos and mat NPos.

All the arrays are optional. If you don’t pass them the information they are supposed to record is simply not returned.

==== fnReadLayoutHeader ====
This function reads the header for a given file layout.

''fnReadLayoutHeader(Layoutname$*255;&Filename$,Mat Keys$,Mat KeyDescription$)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file

==== fnReadEntireLayout ====
This function reads the entire layout by calling fnReadLayoutHeader and fnReadLayoutArrays.

''fnReadEntireLayout(Layoutname$*255;&Filename$,&Prefix$,Mat Keys$,Mat KeyDescription$,Mat Ssubs$,Mat Nsubs$,Mat Sspec$,Mat Nspec$,Mat Sdescription$,Mat Ndescription$,Mat Spos,Mat Npos)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*prefix$ - the return value for the prefix for the file
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

==== fnReadSubs ====
This function reads the subscripts from a layout into Subs arrays.

''fnReadSubs(Layout$,mat SSubs$,mat NSubs$,&Prefix$)''

*Layout$ - the file layout name
*mat SSubs$ - the String Subscript Names
*mat NSubs$ - the Number Subscript Names
*Prefix$ - the files Prefix

==== fnReadKeyFiles ====
This function reads the list of key files from the layout.

''fnReadKeyFiles(Layout$,mat Keys$)''

*Layout$ - The file layout
*mat Keys$ - output array, the keys are returned here.

==== fnLayoutExtension$ ====

This function returns the layout extension being used.

==== fnReadLayouts ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''FnReadLayouts(mat Dirlist$)''

*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all the file layouts that FileIO can find.

==== fnDirVersionHistoryFiles ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''fnDirVersionHistoryFiles(Layout$,mat DirList$;BypassExtension$)''
*Layout$ - Which layout to look up version history of
*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all previous versions from history of the requested layout.

==== fnReadLayoutPath$ ====
This function doesn't actually interrogate your layouts. Instead, it interrogates your settings and returns the path specified for your layout files. This would usually be "filelay\" but you can change it in [[#fnSettings|fileio.ini.]]

It has no parameters.

''let Path$=fnReadLayoutPath$''

==== fnDoesLayoutExist ====
This function returns true if the given file layout exists. It returns false if the layout does not exist.

''FnDoesLayoutExist(layout$)''

*Layout$ - Layout to test for

==== fnReadForm$ (uncompiled) ====
Sometimes you need to know the original form statement that fileio is using to read your data file, most often when you're debugging your file layout, and you're getting some problem when reading the file. The form statement that fileio normally returns is compiled using CFORM$ to save space in the array, and to make the execution of your read statements faster. You can use this function to return the original form statement for the file.

The syntax is:

''let FormStatement$=fnReadForm$*10000(FileLayout$)''

Remember to dimension FormStatement to something huge! fnReadForm$ can return up to 10,000 characters.

==== fnReadFormAndSubs ====

This function does the same as above but it also reads the subscripts from the file into an array.

''let fnReadFormAndSubs(Layout$,mat Subs$,&ReadForm$,&StringSize,&NumberSize)''

Note that unlike most of our functions, all the above parameters are required.

The layout is the layout you're interrogating. The Array will be populated with the subscripts after the function. The ReadForm$ variable will be filled with the form statement for the file. Remember to dimension it large enough. StringSize and NumberSize will contain the number of string fields and numeric fields in the file.

Mat Subs$ will be returned, strings first, numbers last, matching the form statement that is returned. So Subs$(1) is the first string subscript and Subs$(StringSize+1) is the first Numeric subscript.

==== fnClearLayoutCache ====

fnClearLayoutCash (v2.3+) clears out the cache of layout name and data to get realtime Updates to File Layouts.

=== Other Useful Functions (non-layout related) ===

==== fnAskCombo ====

Opens a window with a combo box and returns the users selection.

''fnAskCombo$*255(mat Description$;Caption$*60,Default$*255)''

*mat Description$ - contains the combo box choices
*Caption$ - contains the optional caption for the window
*Default$ - the text of the item in mat Description$ that you want to be selected by default

==== fnSendEmail ====

This function sends an email and an optional attachment to the email address specified.

''fnSendEmail(Emailaddress$*255,Message$*10000;Subject$*255,Invoicefile$*255)''

*EmailAddress$ - the Destination Email Address
*Message$ - the Message$ to send
*Subject$ - the subject
*InvoiceFile$ - the filename of a file to attach. This is the BR filename (the function automatically converts it to an OS Filename.)

The function returns 1 when the email was sent successfully, or 0 if it wasn't sent successfully.

In order to use this function, you must have the emailcfg file layout in your layouts folder and you must have a copy of SendEmail.exe which is free and can be downloaded from the internet. Both of these files are included with the latest update of fileio.

You also have to configure fileio with the authentication information for your email server.

To configure your email server, simply run FileIO to get the data crawler, then select the emailcfg file layout and press F5 to edit it. Add a row if the file is empty.

Simply fill in the information the file is asking for in the appropriate fields and save the data, and then test sending an email to make sure it worked.

More information about sendEmail.exe is available from the author's product site here: [http://caspian.dotconf.net/menu/Software/SendEmail/ http://caspian.dotconf.net/menu/Software/SendEmail/]

==== fnClientEnv$ ====

This function returns the value of a Windows Environment Variable on the client under Client Server.

''fnClientEnv$*255(EnvKey$)''

*EnvKey$ is the name of the Windows Environment Variable to check on the client.

The function returns the value of the entered environment variable.

==== fnClientServer ====

This function returns true if you're currently running in Client Server mode, and false if you're running in the old "native" mode.

==== fnEmpty & fnEmptyS ====
These functions test if the passed in array is empty or not..

The syntax is:

''fnEmpty(mat Numeric)''

or

''fnEmptyS(mat String$)''

Example:

def fnSomeFunction(String$,mat Array$; mat OtherArray)
if fnEmpty(mat OtherArray) then
! Arrays were empty.
end if
fnend

==== fnReadScreenSize ====
This function reads the screen size of the given window (or window 0 if a window wasn't passed.) This is useful for centering a window on the screen, or for making sure window 0 is big enough for the child window you're trying to create.

The syntax is:

''fnReadScreenSize(&Rows,&Cols;Window)''

*Rows & Cols - returns the screen size in rows and columns.
*Window - the window to interrogate. If not given, assumes [[Open_Window#Comments_and_Examples|Window 0]].

==== fnBuildProcFile ====
This function builds a proc file to be executed later. This function and the next simplify the process of executing code in a proc file. It can even be used to spawn a new session of BR.

To use it, call fnBuildProcFile one or more times and specify some lines of code to execute.

''fnBuildProcFile(Command$*255)''

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnRunProcFile ====

This function spawns a new copy of BR and in it, runs the proc file that you've previously built using fnBuildProcFile (above).

'' fnRunProcFile(;NoWait) ''

The optional parameter "NoWait" causes the other session to spawn and run in a new thread. If you don't specify NoWait, the current session pauses and waits for the other session to close before proceeding.

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnLog & fnErrLog ====
These next two functions are functions to aid in logging. When you call either of these two functions, you give them a string that you wish to log. They will open the FileIO Log File and add a record to the end of it containing some user information such as login_name and session$, and the string that you specified. FnErrLog does the same thing as fnLog except it also logs the Error Number and the Line.

The syntax is:

''FnLog(string$)''

*String$ - the Log Message

''FnErrLog(String$)''

*String$ - the Log Message

==== fnLogArray ====

This function logs the given arrays to the log file, logging each field in the arrays. Its useful for recording, for example, an entire data record that is about to be written to a data file.

The syntax is:
''fnLogarray(mat F$,mat f;Message$*512,CallingProgram$*255)''
The first two parameters, of course, are the array to log. The third parameter is an optional message to be recorded along with the array, and the fourth optional parameter is the CallingProgram$ to save in the log along with the message. (The CallingProgram$ parameter can usually be passed as the system function Program$)

==== fnSetLogChanges ====
This function works in conjunction with the next function, and they're for recording just what changed in a data file. When the file is read, you call fnSetLogChanges and record the "before" picture of the file record.

After changes have been made and saved back to disk, you can call fnLogChanges below to record the actual changes.

The syntax is:
''fnSetLogChanges(mat F$,mat F)''

==== fnLogChanges ====
This function is the other half of the function above. It compares the given arrays with the ones set previously in the above function and checks for changes. Then it generates a log message recording information about just the items that changed.

The syntax is:
''fnLogChanges(mat F$,mat F;Message$*1024,CallingProgram$*255,Layout$)''

You need to pass in the same two arrays as before, but this time the modified versions of them.

You can also optionally pass a 1024 byte log message to record with the log entry.

CallingProgram$ again should be passed as the system internal function Program$.

The final parameter allows the passing of a Layout$. If you pass a Layout$, that layout is read and the subscripts are used when making the log message of changes, so that its easier to read. If you pass a layout, it will identify the changed fields by name. If you don't it will identify those fields by relative position number.

==== fnViewLogFile ====
All of the above functions store the information by default into a BR internal file defined in the filelay\logfile layout.

The fnViewLog function uses fnShowData to call the Data Crawler to display the FileIO Log File in a searchable listview.

''fnViewLogFile(;ShowQuit,ShowColumns,ShowExport)''

*ShowQuit - Show a quit button on the UI (if off, ESC will quit).
*ShowColumns - Include a button to allow the user to select which columns to view.
*ShowExport - Include a button to export the log file to CSV.

==== fnReadLockedUsers ====

This function returns a list of all users using the locked data file.

''fnReadLockedUsers(mat Users$)''

*mat Users$ - the list of users is returned here

==== fnDisplayLength ====
This function calculates the display length of a field based on its form spec.

''fnDisplayLength(Spec$)''

*Spec - the Form Spec to return the display length of.

==== fnLength ====
This function calculates the length on disk of a field based on its form spec.

''fnLength(Spec$)''

*Spec$ - the Form Spec to return the length of.

==== fnStandardTime$ ====
Converts Military Time to Standard Time. Returns Standard Time$

''fnStandardTime$(MilitaryTime$;Seconds)''

*MilitaryTime$ - Time in 24 hr format.

==== fnMilitaryTime$ ====
''fnMilitaryTime$(StandardTime$;Seconds)''

*StandardTime$ - Time in AM/PM Format

==== fnCalculateHours ====
Calculates the difference between 2 specified times.

''fnCalculateHours(TimeIn$,TOut$,DaysIN,DaysOut)''

*TimeIn$ - From Time
*TimeOut$ - To Time
*DaysIn - Days Start
*DaysOut - Days End

==== fnBuildTime$ ====
Builds a time in the format used by the above functions.

''fnBuildTime$(H,M,S,P;Military,Seconds)''

*H - Hours
*M - Minutes
*S - Seconds
*P - Boolean indicating AM/PM - 0 is AM, 1 is PM
*Military - Flag indicating weather desired result is in Military Time or not
*Seconds - Flag indicating weather to count seconds or ignore them. (1 means count seconds)

==== fnParseTime ====
Takes a time and pulls out the values

''fnParseTime(T$,&H,&M,&S,&P)''

*T$ - the time to parse
*H - Return value for Hours
*M - Return value for Minutes
*S - Return value for Seconds
*P - Return Value for AM/PM

== FileIO fnSettings (Global Settings Code) ==

The FileIO library can be made to implement certain policies across the board. These are established by creating a file called fileio.ini and typing statements like the following into it. This file is "PROCed", so you don't want to put line numbers in it.

Anything you don't specify in fileio.ini will take its default value, shown below. So you only need to specify the items that you want to be different.

Note, for the boolean settings below, 1 denotes TRUE and 0 denotes FALSE.

let EnforceDupkeys=1 ! Enforce that key number 1 is unique key
let Defaultfilelayoutpath$="filelay\" ! Path To Your File Layouts
let Promptonfilecreate=1 ! Ask User Before Creating New Files
let Createlogfile=0 ! Use Logging
let StartFileNumber=1 ! Set above 300 to avoid conflicts with legacy programs.
let CheckIndex=0 ! Automatically Verify Indexes (slow)
let CompressColumns=0 ! Shrink or Expand Columns in Data Crawler by Default
let MaxColWidth=20 ! Max Default Column Width in Data Crawler
let LogLibrary$="" ! Defaut Log Library, defaults to None
let LogLayout$="" ! Log file layout, defaults to Internal File
let AnimateDatacrawler=1 ! Use ScreenIO Animation for Datacrawler
let TemplatePath$="filelay\template\" ! Default Template Path
let IgnoreLayouts$="" ! List any Ignore Layouts here.
let CloseFileSimple=0 ! Use simple comparison for fnCloseFile

==== EnforceDupkeys ====

Turn on the EnforceDupkeys option to force that the first key listed in your file layouts is a unique key. FileIO will generate the standard BR error for Dupkeys when attempting to create indexes if it is not unique.

==== DefaultFileLayoutPath$ ====

Use the DefaultFileLayoutPath option to specify the path from your programs to your file layout folder. The default is "filelay\". Use this setting if you want to place your file layouts in another folder from the default.

==== PromptOnFileCreate ====

Use the PromptOnFileCreate setting to cause FileIO to display a message box whenever it is attempting to create a new file. This happens during the automatic update procedure, as well as during any attempt to access a file that does not exist. This setting should be turned off in your live system, and only turned on for development purposes. If you use the message box to cancel creating of the new file, then the file is not created, and fileIO or your application will most likely give an error when you attempt to actually access the new file.

It can be useful during development to make sure that you don't accidentally create the wrong files, due to an incorrectly specified path or a typeo in the filename in the layout file. However, in a live system, these things have already been tested, and you generally want the default behavior, because you don't want your users to have the ability to cancel the normal operation of FileIO.

==== CreateLogFile ====

Use this option to specify weather or not to use the FileIO log file. If it is turned on, a log file called FileIO.log in the current directory is created with entries listing all attempts to open a file, automatically update one, or automatically update your indexes.

==== StartFileNumber ====

Use this option to set the starting file number that the fnGetFileNumber and the fnOpen functions use to search for available file numbers. This is so that if you have certian reserved file numbers in your code, you can make sure that FileIO will not use those reserved file numbers, causing a conflict with your already existing programs. The default is 1, which is fine if your software does not have any reserved file numbers.

The allowable BR file numbers are 1-200 and 300-999.

==== CheckIndex ====

This function is used for Partial FileIO Implementations. If all of your software uses FileIO then all of your indexes are kept automatically up to date by the FileIO library and BR's internal file processing systems. However, if some of your programs do not use FileIO, and you use the FileIO library to add a new index file that those other programs do not know about, then its possible for the additional index file to become out of date when the master file is updated by your other programs.

Use this setting to cause FileIO to check the DateTime stamp on all your index files when opening a new file, and automatically update any indexes that may have potentially gotten out of date from other programs.

This option slows down the processing of the fnOpen function, particularly when running under client server over the internet. If you know that every program in your application suite uses FileIO, and that any programs that do not use FileIO still properly update all the indexes that your data file uses, then you can safely leave this setting turned off, and optimize your performance when opening several files using the fileIO system.

==== CompressColumns ====
This instructs the datacrawler to use smaller widths for small columns. If CompressColumns is false, the data crawler will make the column the width of the field or the width of the caption, whichever is wider. If CompressColumns is true, it will use the width of the field, not the caption.

==== MaxColWidth ====
This limits the column width to a set amount. This is applied after CompressColumns above.

==== LogLibrary$ ====
If a library is specified here, then fileio looks for a BR library with the specified name, and attempts to call a library function in it called fnFileIOLog that. This function should expect six parameters, which are Logstring$, Login_Name$, Session$, Days of Date$, Time$, and CallingProgram$, if LogLayout is also nonblank.

If you specify a LogLibrary and LogLayout is blank, then it calls your function giving it only 1 parameter.

It will call your function '''''instead of''''' the normal log file. Use this to implement your own logging functions however you want.

==== LogLayout$ ====
Use this setting to specify an alternate file layout for an alternate file to do the logging in. Base the file layout for this file on the logfile we supply for you in the filelay folder. It should have at least those fields, which our log routine will automatically populate, but you can add other fields if you want (though you will need to manage them yourself).

If you don't specify LogLayout, the default filelay\logfile will be used. This will allow you to also use the fnViewLogFile function to access it.

==== AnimateDataCrawler ====
The sister library [[ScreenIO]] has a feature that allows you to use an animation of a clock in your loading screens in your own programs. If you have [[ScreenIO]] then FileIO will automatically detect it and use it to display a loading animation while the data in the data crawler loads.

Set AnimateDataCrawler to false (0) in your fileio.ini file to bypass the animations if you do have screenio but don't want to see the animations anyway.

==== TemplatePath$ ====
This setting points to the folder that contains the code templates used by the Generate Code button on the main page of the Data Crawler.

==== IgnoreLayouts$ ====
This is a comma delimited list of all layouts that you wish to suppress from appearing on the main page of the data crawler. You can still access these layouts with your code, but they won't be listed in the data crawler for you to access.

Whatever you're using for a log layout, is automatically added to this list.
==== CloseFileSimple ====
The fnCloseFile function closes all the individual handles to a data file that was opened for output using multiple keys.

For BR 4.18 and higher, we support a better algorithm for detecting which files are matches for a given opened file number.

Set CloseFileSimple to true (1) to force it to check the old way.

== FileIO Add-on Packages ==

Many FileIO Add-on packages are currently in the works.

=== ScreenIO Library ===

The [[ScreenIO Library]] is a sister library to the FileIO library. The ScreenIO library requires the FileIO library in order to run.

The ScreenIO library is a complete Rapid Application Design tool that enables you to implement custom screen functions anywhere in your exiting programs.

If you call the ScreenIO Library as a function library, you call a function called fnFM and tell it which screen you wish to use. The ScreenIO library loads your user interface, loads your data files, and preforms all the file maintenance operations you have designed into your screens.

You can find out the latest information about the ScreenIO library in the ScreenIO page.

=== Audit BR ===

The [[AuditBR|Audit BR]] developer tool makes a backup copy of your file layouts. Then you run some code you're trying to test, and finally, run Audit BR again, to get a report showing all the changes to any of your data files automatically.

AuditBR is now included directly in FileIO. To use it, select the layout from the list of layouts in the Datacrawler and press the "Compare" button.

== What’s New (also described above) ==
=== 2018 ===
*Support for dates in any storage formats on disk (v2.48)

=== 2015 ===
*Added Rec to display for fnShowData
*Added FormStatement$ for debugging of form statements inside fileio
*Added mat BadRead$ for debugging of 726 errors when making new layouts
*Fixed a bug causing crash when logging things from long program folders
*fnClientEnv$ - reads a Windows Environment variable on the client using the command shell
*fnAskCombo$ - added an optional parameter to set default selection.

=== 2010 - 2014 ===
*FileIO now caches your file layouts in memory to make it much faster then before when opening the same data file in multiple programs.
*Generate Layout Wizard
*fnShowData
*Improved Logging
*fnViewLogFile
*Import/Export
*Import/Export by Function
*Many other speed increases
*if ScreenIO is present, Datacrawler uses the animation routines
*fnBuildProcFile & fnRunProcFile
*fnGenerateLayout & fnWriteLayout
*fnReadForm$
*fnReadFormAndSubs
*fnGetFileDateTime$
*fnReadLayoutPath$
*fnSortKeys
*fnSetLogChanges
*fnLogChanges
*fnLogArray
*fnReadScreenSize
*fnEmpty
*fnEmptyS
*Many other useful functions that were added to the documentation at earlier dates.

=== Spring 2009 ===

'''''New Functions:'''''

The FileIO Library has been updated in Spring 2009 to provide several new functions:

*fnReadRecordWhere
*fnKey$
*fnBuildKey$
*fnReadUnopenedDescription$
*fnUpdateFile
*fnDisplayLength
*fnLength
*fnReadLayoutHeader
*fnReadEntireLayout

'''''Speed Increases:'''''

Thanks to the BR [[Profiler]], we have increased the speed of FileIO fnOpen function by ten times when running over a LAN and by 100 times when running over the internet using Client Server.

In order to get the new Speed Upgrades, you will need to make sure that you use the latest copy of the [[#fnOpen_Function|fnOpen]] function in each one of your programs that use FileIO.

'''''Network FileIO:'''''
This version of FileIO has been optimized to work better in network situations.

'''''FnSettings: '''''
There are more configuration options in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine.

'''''Automatic Update Speed Fix:'''''
The automatic update proceedure has been made to run more then 100 times faster then before according to our benchmarking tests.

=== Fall 2008 ===
'''''DataCrawler Grid:'''''

By popular request we added a read/write version to the data crawler. This version works exactly the same as the datacrawler did before but it displays all the contents of your data files in a grid instead of a listview.

When you run the fileIO library as a program, it launches a tool known as the [[#DataCrawler|DataCrawler]]. The DataCrawler shows a listview displaying all your layout files in it. If you select one, it builds another listview with all the data in your selected data file.

If you are looking at the first list of all your file layouts, and you press F5, a grid will be build displaying all the data in your data files. You can change any of the records you like, and when you're done, your changes will be saved to the data file. Additionally, you can Add or Delete records using the buttons at the bottom. Any changes you make are not written to the disk until you click the "Save" button. If you press ESC (Cancel) the grid is closed and all changes you made sinse the last save are lost.

This tool is for programmers only. Do not give your end users access to the DataCrawler.

Use the DataCrawler at your own risk. Gabriel Bakker and Sage AX are not responsible for any harm that comes to your data files through the use of this or any other tools we offer.

The DataCrawler is not designed to be used to maintain your data files. It can be used carefully to correct small things in your data files.

'''''Support for Nonstandard Paths:'''''

Many BR Vendors keep different versions of the same data files in different locations. For example, sometimes a BR vendor will use a different Data folder to represent data for different Warehouses, or Customers. In cases like this it is necessary for your programs to specify the path to your data files. They may do so by specifying the optional "PATH" parameter to your data files. See the section [[#fnOpenFile]] for more information.

'''''Support for Nonstandard Layout Files Path:'''''

Old versions of the fileIO library required you to place all your file layouts in a subfolder of your program directory called "filelay". We have now changed the Fileio library to allow you to place your file layouts any place you want. The only requirement is that they are all together in one folder by themselves.

If you use a nonstandard path in the fileIO library, it is necessary to make a change to the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code in your copy of fileio.br.

'''''Prompt on Create:'''''

The FileIO library automatically creates any data files that it can't find. This was done to make it easier to deploy your finished programs - if you had any empty data files you could omit them from the packages and they would be created when they were needed, on the fly.

The current version of the FileIO library contains the same ability. However, it prompts you before creating any data files. This helps to avoid bugs that happen from incorrectly specifying the path to your data files.

However, if you do intend for your data files to be autocreated, then you probably don't want your end users to modify them. Therefore, you can use the PromptOnCreate setting in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code to specify. If this value is set to true, then the fileIO library will prompt you whenever it attempts to Autocreate a data file. If it is set to false, then the fileIO library will create the data files without prompting you, like it always did before.

'''''fnSettings:'''''

The newest version of the FileIO library supports some features that require you to specify Global Settings values. These are done by modifying the contents of the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine at the beginning of the fileIO library.

=== Fall 2006 ===
Many improvements have been made in the FileIO library over the summer. This section is intended to acquaint you with the highlights of those changes. Most of these improvements were built from ideas generated during the discussion at the April conference.

'''''Intermixed String and Numeric Specs:'''''
The File Library has been expanded to allow the reading of data files that contain mixed string and numeric specs. This is to aid those of you who are planning on implementing the FileIO Library on existing data files which may not be organized with strings first and numbers second.

The central idea of the FileIO Library is based upon the reading of your data files into a String and Numeric array. This will enable you to refer to the fields in your file by using a named subscript, saying F$(FM_NAME) to refer, for example, to the farm file’s name field. The advantage to this is that when you change the file layout, all your existing programs will not have to be modified, because they will only be looking at F$(FM_NAME). If the name field changes from the third string field to the fourth, the value of FM_NAME will also change, and you won’t have to worry about updating your data files.

However, in order to support the reading of a data file with intermixed string and numeric specs, the generated form statement will actually calculate the position of any fields that are not in order, so that the file read statement will still return all string fields first (into your string array) and the numeric fields second (into your numeric array). You do not need to worry about this; the library does it for you. All you have to do is read your file and use the data values.

The only thing that is required is making sure that all your string subscript names end with a “$”. This will tell the library that they are strings. Thank you, George, for this suggestion.

'''''Versioning / Automatic Updates:'''''
The file layouts have been expanded to contain a version number. This version number will be used to determine when a file needs to be updated. The version number is the third parameter in the file layout.

Any time you wish to change your file layouts, simply increment this version number. Each time the library attempts to open a data file, the file’s version is checked and compared with the version in the file layout. If the file layout has been changed (if the version in the file layout is greater then the version in the file) then the file will be updated to the latest version. Depending on the file size this may take a couple of moments. A simple progress bar will be displayed on screen while this is happening. The progress bar will be displayed in its own window, so it should not affect anything your programs may have had on screen.

The library uses the following procedure for updating a file. First, the file is copied to a backup file (prefixed by the letter ‘o’ for old). So color.dat would become ocolor.dat, and color.key would become ocolor.key. Then the new file is created and marked with the proper version number. (color.dat, color.key). The old file is opened in read-only mode, and the new file is opened for OutIn. The update routine actually reads through the old file layout, and one record at a time creates a new record, using the new file layout, with the same data, saving it to the new data file.

When it is done upgrading, the progress bar window is closed, and the file is reopened in the fashion you described in your call to fnOpen, and flow returns to your program as though nothing unusual has happened.

If an error occurs during processing, the routine will do what it can to roll your data files back to the previous version, but please make frequent backups of your data files anyway, just to be safe.

'''''Error Checking – If there is a mistake in the file layout:'''''
The routine attempts to discover the cause of the error in the case that one is encountered due to a missing file, a file sharing violation, or an invalid or corrupt file layout. If this should happen, the program is paused, and a text message is printed out explaining the most likely source for the error, including what part of the file layout, if any, may have caused the error.

You may then examine the printed text, and the contents of the BR system variables ERR and LINE to determine the problem. If you type “GO”, the next line will be execute “system”, ending your program.

If the file was in the middle of an upgrade when the error happened, it will be automatically rolled back to the previous version, so that when you fix the problem and try to run your program again, the file will again attempt to update from the beginning, and you won’t have to worry about corrupted data.

However, please backup your data before upgrading your data files anyway, just to be safe.

'''''Implementation of Keys / Creation of New Data Files:'''''
The library has been expanded to automatically create all new data files, and to automatically update any existing files. This means that in the file layout header, two new fields that were previously ignored are no longer ignored. The RECL value that you specify in your file layout will be used, along with the description/definition of your keys file. When you open a new file (or update an existing one), the library will calculate the proper kps and kln by evaluating the key description. This key description must match up with subscript values from the data elements in your file, and more then one may be specified, but they must be separated with slashes (/). If I wanted my Farm File to be keyed based on CODE and NAME, the proper key description would be:

farm.key, CODE/NAME

The library will then look up the position and length on disk of the CODE and NAME fields and put them together to create the proper keys during an update or creation of a new file.

'''''DataCrawler:'''''
Perhaps the most exciting new addition to the library is the addition of a programming tool I like to call a DataCrawler. If you run the FileIO Library directly as a program, instead of using it as a library, it will function as a DataCrawler. The DataCrawler requires a New Gui version of BR, as it requires a ListView to be able to properly and easily display the data in your files.

If you run it in an older version of BR you will get a message, telling you to run it in a newer copy. If you run it in a New Gui version of BR with CONFIG GUI OFF, then GUI will be turned temporarily on for the use of the DataCrawler and then turned off again when you are finished. If you run it in a New Gui version of BR with GUI ON, it will just run normally.

When you run the DataCrawler, first you will see a ListView displaying every file layout it can find in the filelay folder. If you select a file, the DataCrawler will open a large ListView with as many columns as there are fields in the file. The Column Headings will come from the element descriptions in your data files, and the column widths will come from the displayed width of the fields. There will be a row for every record in your data file, and you can resize the column widths, and scroll around the data file to view the raw data of your BR data files on disk.

If you are dealing with a particularly enormous data file (50,000+ records) it can take a moment to populate the ListView with the data in your data file. You may hit ESC to stop loading if you like, and view only the already loaded records.

If you would like to look up a particular record (based only upon the primary key for the data file), you may press F4. This will give you a window which asks you to input the key or partial key. When you press enter, the file will be reloaded, starting at the key you specified and continuing on to the end of the file, or until you press ESC. The records you are looking for should appear at the top of the ListView.

To reset the ListView and look at the contents of the entire file again, simply press F4, and enter a blank (“”) key.

Finally, as with any ListView, you may resort your data by clicking on any of the column headings. Then you can use the slider bar at the right to scroll down to the record you desire.

This is a programming tool and is not designed to be used by an end user. This tool will open your file in read-only mode. It will not allow you to modify the data; I leave that as an exercise for the reader. However, it will update any datafiles you view to the latest version (if they need to be updated) when it opens them, just as any other program that uses the library will do.

== Appendix (Examples)==

=== Example.br ===
00010 ! example.br - This program is an example of for the data reading simplification
00020 ! Copyright April 2006 by Gabriel Bakker
00030 ! Distributed open source as a Christmas gift to brag members
00040 !
00100 execute "config gui off"
01020 DIM form$(1)*255
01030 DIM color$(1)*255,color(1)
01040 DIM colorcat$(1)*255,colorcat(1)
02020 library "fileio": fnopenfile, fnreaddescription$
04000 !
04010 Openfiles: ! Open your files here
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)
06000 ! gosub WriteFiles ! If you want to test this line, make sure to drop flag from 4030
07000 !
07010 MainBit: ! This'un here's tha Main Bit
07030 RESTORE #ColorFile:
07100 ReadNextcolor: ! Read next record
07120 read #ColorFile, using form$(ColorFile) : mat Color$, mat Color eof EndReadColor
07180 PRINT Color$(co_name)&" ("&Color$(co_html)&") is a member of the '";
07190 PRINT trim$(fnReadDescription$(ColorcatFile,cc_Name,Color$(co_category),mat Colorcat$,mat Colorcat,mat form$))&"' category."
07290 goto ReadNextColor
07300 EndReadcolor: ! Finished with Color File
08000 STOP
25000 !
25010 WriteFiles: ! Uncalled routine to demonstrate writing files
25105 let color$(co_code)="GD" !:
let color$(co_Name)="Gold" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFD700"
25110 write #colorfile, using form$(colorfile): mat color$, mat color
25115 let color$(co_code)="LV" !:
let color$(co_Name)="Lavender" !:
let color$(co_Category)="BL" !:
let color$(co_html)="E6E6FA"
25120 write #colorfile, using form$(colorfile): mat color$, mat color
25125 let color$(co_Code)="OR" !:
let color$(co_Name)="Orange" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFA500"
25130 write #colorfile, using form$(colorfile): mat color$, mat color
25205 let colorcat$(cc_Code)="YL" !:
let colorcat$(cc_Name)="Yellows" !:
let colorcat$(cc_html)="FFFF00"
25210 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25215 let colorcat$(cc_Code)="BL" !:
let colorcat$(cc_Name)="Blues" !:
let colorcat$(cc_html)="0000FF"
25220 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25300 return
40000 !
40010 Open: ! ***** Function to call library openfile and proc subs
40020 def fnOpen(FILENAME$, MAT F$, MAT F, MAT FORM$;INPUTONLY,KEYNUM,___,INDEX)
40025 dim _FileIOSubs$(1)*50
40030 let fnopen=fnopenfile(FILENAME$, MAT F$, MAT F, MAT FORM$,INPUTONLY,KEYNUM,MAT _FileIOSubs$)
40040 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
40090 fnend
50000 !
60000 Ignore: Continue

Color File Layout
color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

ColorCat File Layout
colorcat.dat, CC_, 0
colorcat.key, CODE
recl=127
===================================================
CODE$, Category Code, C 6
NAME$, English Name for Color, V 30
HTML$, HTML Code for the Color, C 6

Example Layout showing multiple keys (price)
price.dat, PR_, 0
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2

[[Category:Utilities_Third_Party]]

FileIO Library

2024-09-11T13:19:08Z

Gordon.dye: /* How it Works */

The '''FileIO''' Library began as a project to find a way to reduce the headache associated with making changes to data files. In my experiences working for [[BRC]], I had to make a change to the commun file, a data file that stores information about communication with EDI VANs. I added some new fields, and removed a couple of old fields, and then I began searching through the BRC program suite to find and modify each program that referenced this data file in order to update it with the proper new form statement. This task quickly became daunting as I noticed that out of BRC’s program suite of over 600 programs, more than one third of them referenced the commun file. With 223 programs to modify, the task was given up as hopeless and tabled indefinitely.

I am happy to announce that we have solved this problem. When I have to make a change to a data file layout for my customers today, I can complete the task in under 1 minute, and not a single program needs to be changed in order to continue working with the new file layout. In fact, I don’t even have to update my customer’s data files, as the FileIO library takes care of this for me as well.

The trick is to define your file layouts in an ASCII text file layout file that I will tell you about in a minute. The FileIO Library will actually parse through your file layouts, and it will instruct your programs how to read the data file, so that you don’t have to. It will also automatically detect when you make changes to the file layout, and it will update your customer’s data files on the fly to make sure they have the latest version. Finally, it even contains a DataCrawler that you can use to examine the contents of any of your BR data files in a raw format.

For more information about the FileIO Library visit the [http://www.sageax.com/products/fileio-library/ Sage AX Website]

To download the latest copy of FileIO, click [http://www.sageax.com/downloads/FileIO.zip here.]

== Method of Operation ==
The file IO library parses a formatted text file layout and uses this information to structure the opening and initializing of the reading of a file “object”. The word object here is used to refer to all the data in a given record layout in one of your files. This library is easy to use, and provided you follow some simple standards, it will simplify your life immensely.

Your programs will need to define one array for all [[Form|file layout form statements]] and add a snippet of code (given below) to the program for interfacing with with the library. For each file you will need to define a couple of arrays and use the library to open them. From that point on access to data is simple and direct.

=== File Object Arrays ===

First, in your program you must create two arrays to store the file information. If we are dealing with the Color File these would be MAT COLOR$ and MAT COLOR. One will store all the string information about a color, and the other will store all the numeric data. Our working example will involve two files: a Color File and a Color Category File. You should dimension these to:

01030 DIM color$(1)*1000,color(1)
01040 DIM colorcat$(1)*1000,colorcat(1)

We're dimensioning the string arrays to 1000. This is the length of one field in the color file. It needs to be at least as big as the largest string field in the data file.

However, it is recommended to make sure the length is long enough to handle any field you might eventually add to the file at any point in the future. BR supports multi-line textboxes, so I sometimes add long memo fields to my data files that might be 400 or 800 or even 1000 characters long, therefore 1000 is the length I use now in all my new development.

But anything will work as long as its long enough to handle the largest data field in your file.

=== Forms Array ===

Your programs will need a string variable array to store the form statements associated with reading files. This form statements array will be dynamically generated or expanded whenever the a file is opened. It will say:

01234 DIM form$(1)*255

This form statement will be compiled by the FileIO open statement. BR limits all form statements to 255 bytes, so 255 is sufficient to hold the compiled Forms$ statements.

=== Library Linkage ===

You will also need the library statement:

02020 library "fileio.br": fnopenfile, fnreaddescription$

=== fnOpen Function ===

Now, add a snippet of code to interface with the library.

Because BR libraries do not share global variables with the programs they are called from, we will need to execute a proc file whenever we open a file to set the names of all our variables after we return. Add the following snippet of code into your program. It will create an FnOpen function that calls the library and runs the proc file. The $$$ at the end of the procfile name tells the procfile to self-destruct after execution. Since this procfile is used simply to return variable information back from the library to the main program, we don’t need it sitting around collecting dust.

99010 OPEN: ! ***** Function To Call Library Openfile And Proc Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
99030 dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
99050 if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
99060 fnend

Or, for those with [[Lexi]]:
OPEN: ! ***** Function To Call Library Openfile And Proc Subs
def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
fnend

=== Using FileIO in Your Programs ===
Now you are ready to process files. 
'''''You simply open the files by saying:'''''

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

'''''read each file as follows:'''''

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
'''''and access the data:'''''

30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name)

=== How it Works ===
The above statements tell the File Library to look in the filelay folder to find the file layout for the Color File, and read it to find out what the Color File looks like. Then Open the Color File, and set MAT COLOR$ and MAT COLOR to the correct number of elements to hold an entire color record. Finally, it will define several variables that we can use as pointers (subscripts) into these arrays to access the data we after reading it, and it will place the file handle into a variable called colorfile.

The second open above will do the same thing to the color category file, except the 1 parameter value tells the function to open readonly. The array subscripts populate procedure (passed back from Fileio) will be executed, thereby assigning values to the subscript names in the calling program. So, if I had a file layout such as the following:

color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

Then the functions would do the same thing as the following individual lines of code (assuming the next available file handle was 5):

DIM FORM$(5)*255
DIM COLOR$(9)*1023, COLOR(1)
OPEN #5: “Name=color.dat, kfname=color.key”,internal,outin,keyed
LET FORM$(5)=”form C 6,V 30,V 6,C 6”
LET FORM$(5)=CFORM$(FORM$(5))
LET COLORFILE=5
CO_CODE=1
CO_NAME=2
CO_CATEGORY=3
CO_HTML=4

The data is used by referencing the file array, with the subscript name, so the color’s description becomes color$(co_Name).

In the old days, if we wanted to change the file layout of our file, all of the programs that used that file would have to be changed one at a time to use the new file layout. Also, if the order of the fields changed, then all the programs would have to also be changed to use the new fields.

But now, using this function, we can change the file layout all we want. If we later want to insert a field into the file layout before color name, I won’t have to look at this program again; this program will just work fine, because the library maps the subscripts to the actual fields.

Also, the code is easier to read and maintain.

=== Example ===
The whole thing looks like this:

01025 ! Dimension the Arrays
01030 DIM color$(1)*1023,color(1)
01040 DIM colorcat$(1)*1023,colorcat(1)
01050 DIM form$(1)*255
02000 !
02020 library "fileio.br": fnopenfile, fnreaddescription$
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$) ! Open the file
05000 !
30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore ! Read the file
30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name) ! Use the data by referincing it in the file arrays
80000 !
90000 ! Every program using fileio needs the following code
99010 OPEN: ! ***** Function To Call Library Openfile And Generate Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths)
99030 dim _FileIOSubs$(1)*800
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$)
99050 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
99060 fnend

== File Layouts ==
Now lets inspect the anatomy of a properly formatted file layout. These should be placed in a subdirectory called filelay.

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...
<hr>
price.dat, PR_, 1

The first line contains the name of the Farm File, a unique string to prefix all of your subscript pointers, and the file version number. The subscript value is to ensure that the program knows the difference between the Farm File’s Farm Code, and the Route File’s Route Code. (One will be RT_CODE and the other is FM_CODE). These are separated by a comma. Spacing does not matter, so adjust your spacing so that it looks nice.

The Version number is used to determine when the data has changed, and an update needs to be made to your data file. Your file layouts should all start at version 0, and each time you want to make a change, you may increment this value by 1.

Each time you open a file with the FILEIO library, it reads the file version number of the file on disk (using the BR version() function), and then it compares it to the version number in your file layout. If your file layout has a higher version number then your existing data file, then the library opens the backup of the file layout for the version of the data file that exists on disk. It makes a backup copy of the existing data file, and creates a new file with the proper version number. Then it reads your records one at a time, and copies all the data from the old file into the new file one field at a time. If a field is dropped from the file layout, that data gets lost. If fields are rearranged, the data is copied and saved in the new file in the new positions. If a new field is added, it starts out blank (or 0).

If you look in the filelay folder, you will notice a version folder. This contains several files ending with a number. For example you may see a color.0, and a color.1 file.

If you run the fnopen function and it can not find your data file (usually because this is a new file and it hasn’t been created yet), ''the library will automatically create your file,'' based on the information you give in the first part of the file layout.

Also, whenever you make changes to your file layout, the function library will automatically update the data files on disk for you. It does this by renaming the old file, creating a new one with the new version number, and then copying the data from the old one to the new one a record at a time.

Any time it creates a file, or updates the file on disk, it creates a backup of the file ''layout''. The first time you run a program that tries to read your new data file, it will create the data file for you and make a backup of the layout, and if the number in your file layout is 0, then it will create, for example, a filelay\version\price.0 file, a backup of your file layout that the library uses to figure out what has changed the next time you try to update the file.

If you wish to make any changes to this data file, first you increment the version number, (in this case make the 0 into a 1). Then change the file layout all you want. You may rearrange fields, add new fields, add or remove keys, or change the record length.

The only step necessary for having your data files updated is to increment the version number every time you make a change to the file layout.

You may make any changes you like to the file layouts, but do not change the names of your existing subscripts. If you change the subscript name, not only will all the programs that reference that subscript be broken, but additionally, the routine will not understand that you are changing the name. It will think you are dropping the old field and adding a new field and any data stored in this location will be lost when the file is updated.

price.key, FARM

The second line contains the name of the first key, and a definition telling what the key is based on. These are separated by a comma. The key definition is made up of each of the subscript names in this file that form the keyfields for the file. When the library is called to open a file, if the file does not exist, or if it needs to be updated, a new one will be created. The function will read these subscript names that form your key definitions, and it will calculate the proper key position (KPS=) and length (KLN=) values. Then the create routine will use this information with the Index command to create the new key files.

price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127

Notice that the third key is based on three different fields. These are separated by a “/”. It is important that you use a “/” to separate your keys when you are building a key out of more then one field, because the function uses this “/” to help it make the proper BR syntax for defining complex key fields.

Also, note the "-U" at the end of the fieldname in the 4th key. This indicates that the "Description" part of that key is case insensitive. This translates to using the "U" on part of your key spec in Business Rules.

The file can have as many keys as you want. The function will keep parsing key file names until it reaches the next part of the layout. It opens any OutIn files with all keys so that any changes you may make to the data stored on disk will be properly reflected in all the key files.

The optional RECL= Parameter is read and used whenever a new file is created or an old one is updated. If it is not specified, the record length is calculated from the fields in the layout.

===================================================

The next line in the file is skipped by the parsing routine, and its purpose is to make the file layouts more readable to a programmer.

 
FARM$, Farm Code (or blank), C 4

Following the file and key structure, the fields are defined. There are three parameters on each field definition line, and you make one line for each field in your file layout. The first parameter is the subscript name that you will use in your program to refer to this data element. Place a $ at the end of the subscript name for all string elements. Don’t place anything at the end of the subscript name for numeric elements. Note that each of these names will be prefixed by the second parameter of the very first line of this layout.

The second parameter is the description. This description is for the benefit of the programmer, so when the programmer is reading the file layouts, (s)he can tell which field does what. The spaces are ignored, so you may include as many spaces as you wish to make the layout look good. It does seem like good general guidelines would be to limit your layout lines to 255 characters and your descriptions to 80.

The description is also used by the built in DataCrawler, a program that reads any of your data files and displays the entire contents in raw form in a listview. The Descriptions become the headings for each column in the listview.

Those descriptions are also used for the default captions for your fields if you use ScreenIO, a library for building GUI programs that itself builds off of fileio.

The third parameter is the form statement, which is pretty straightforward. Any items with a form statement of type “X” will be ignored, except that the length will still be used to calculate the position on disk of all remaining fields in the record. The library will take X fields into consideration when building the form statement, but not at any other time.

The fourth parameter is optionally a [[#Support for Dates|Disk Date Format]]. You can specify DATE(Julian) if you're storing your dates in Julian format on disk. Or you can specify DATE(cymd) or DATE(ymd) or DATE(mdy) or any other valid date spec here, and FileIO will treat this field like a date.

Your programs will still have to unpack it for you, fileio can't do that because fileio doesn't read the file for you.

However, the data crawler, the automatic updates, and screenIO, are all compatible with these dates specified in your file layout.

If the fourth parameter is anything other then DATE(format), then its treated as a comment and ignored.

The fifth and all later columns, if any, are treated as comments and ignored.

! default cost is normally zero
Comment line text must begin with an exclamation point, but it may be indented. Comment lines may appear anywhere (vertically) and are ignored. 
Blank lines are ignored as well.

#eof#
additional comments...
After the last field definition, an ''optional'' #eof# line may be specified, in which case any lines after that will be ignored.

 
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...

And that’s all there is to it.

=== Support for Dates ===
As of V2.48, file layouts support dates in any storage formats on disk. Whether you store your dates in Julian or in YMD or MDY or any other format, specify so in the 4th column of your file layouts, using the FileIO Date Keyword. ex: DATE(Julian) or DATE(YMD) or any other valid BR Date Format.

[[File:Dates0.png]]

When this is specified, it enables the FileIO data exploration tool (Data Crawler) to display the dates in human readable format. This works for both Viewing, and for Editing.

The new Date functionality also supports the File Layout Upgrade facility, allowing you to change the format of your dates on disk and FileIO will handle it automatically, upgrading the field to use the new date format for you.

It works also for Exporting your data files to CSV, and is supported automatically in the FileIO functions that do those exports. It converts the dates on export to a standard format (Default: m/d/cy) that you can specify in your FileIO.Ini File.

And it extends ScreenIO's date features to all date fields, no matter what format they're stored in. (Previously, ScreenIO's advanced date features only worked for dates stored in Julian on disk.)

This update adds two new ini file options:
CODE: SELECT ALL
DateFormatExport$='m/d/cy' ! Format of Dates when Exporting to CSV
DateFormatDisplay$='m/d/cy' ! Format of Dates when displaying in Data Crawler

You can use these to specify your preferred Date format for Viewing/Editing, and your preferred Date format for Exporting.

Remember, you can see the full list of FileIO ini file options, by looking in the source code at the top of FileIO.

There is a new optional parameter for all layout reading functions, mat NDateSpec$ and mat SDateSpec$ which correspond with the other arrays, to let you know which fields are date fields, so that you can develop routines in your programs to automatically pack and unpack the dates.

Important Note: Using FileIO, the reading of the data file is still done directly in your programs. So this does not change how your existing programs work. It does not unpack the dates for you in your programs. You still have to do all that.

For this reason, upgrading to the new Date processing will not break any of your current code.

=== Debugging Tips ===

When you're making new layouts, a missing comma can cause FileIO to parse the layout wrong and give you errors. Here are a couple tips to help ensure your layouts are error free before using them in your programs.

*Use the Data Crawler to test your layout. The data crawler is the simplest way to test your new layout without writing any code. It opens it and accesses the file in a very simple and straight forward manor to help identify any errors in the layout that you might have.

*If you have trouble with the form statement, you can't see whats in it because FileIO uses CForm$ to compile your form statement to make your programs run faster. But here's a way to tell what the original form statement was that FileIO generated when it put the strings first and numbers last in your program: Open the file in the Data Crawler. When you get an error, type "Print FormStatement$" to see the original form statement.

This works even if your file is working fine. Any time the file is opened with the data crawler, you can press CTRL-A and then type PRINT FormStatement$ and it will print out the uncompiled form statement for the file.

== Utilities ==

Now that you have your file layouts defined, you have access to several powerful utilities right out of the box using Fileio. Additionally, several more utilities are available as [[#FileIO_Add-on_Packages|Add-Ons]], including our most popular development tool [[Screenio|ScreenIO]]. You can read more about them in their section below.

But for now, lets take a look at some of the wonderful free utilities that come built into Fileio.

Some of these utilities are accessible from your code via library functions, but the primary way you access any of them is by simply loading the FileIO Library and running it directly.

=== DataCrawler ===
The data crawler is the original utility of FileIO. This utility shows you first a list of all data files allowing you to select one.

Select a data file and press enter, and FileIO will then display a listview containing all the data in the data file. This list is sized based on the size of your main BR window (window 0) automatically to take up the full size available to it, so if you want to see more, try [[Open Window|opening window 0]] larger before running FileIO.

At the top of the window is a filter box, and you can type anything you want in there and click "Refresh" and it will reread the data file, shortening the list to show only those records that match (case insensitive) what you have typed.

If you have ScreenIO installed, then FileIO's data crawler will take advantage of the included Animation Engine in ScreenIO to animate a loading window while the listview is displaying. If you don't have ScreenIO then FileIO will simply load the listview.

If you don't want to wait for the entire file to load, press ESC to stop the load process.

If the file is empty, FileIO will display a message box letting you know.

This tool is very useful for sorting out data errors. It will allow you to look inside any data file you have a layout for and directly view the data there.

At the bottom of the Data Crawler are several buttons. There's a Jump button that repositions the file by a key you specify and then loads the list with the data from that key on down to the end of the file.

There is a "Columns" button which you can use to decide which columns should show up on the listview. Fewer columns means faster loading so sometimes for large files I press ESC immediately when the file first starts loading to cancel the load. Then I click "Columns" and check only the columns I want to see. Finally I press the "Refresh" button to trigger it to read the file again and this time it loads much faster then before.

Next you'll find an Export button which starts the process for exporting a file to CSV. You can read more on that in the next section. And next to that is a Quit button.

In this example, we loaded the file "Read Only" so it put everything in a listview. But there are times when its useful to fix data errors this way too, especially during development. So if you want to directly edit your data file, on the first page select the file you want to edit and instead of pressing "Enter" or clicking "View", this time press "F5". F5 is the secret Edit button that loads a data file into a grid instead.

You can use the grid to change records, delete them or add them, and in addition to the buttons listed above, it also has an "Import" button for importing a CSV file into this data file.

Any changes you make to the data file are not saved until you click the "Save" button (which also only appears when you're in Edit mode).

In the 01/2015 release of FileIO, each records rec # is displayed in the listview, to aid in debugging bad data problems.

==== Debugging Tip ====
Any time you're viewing a file layout in the Data Crawler, you can see the Uncompiled Form Statement by pressing CTRL-A to get to an ATTN prompt, and then entering the command:

print FormStatement$

and it will print out the original form statement.

==== Another Debugging Tip ====

The FileIO Datacrawler ignores records that it cannot read. This is to allow for data files that have multiple record layouts in one data file. You make a custom layout for each record type and the data crawler shows just the records that match that type in the file.

However that becomes a problem when you're making a layout to work with an existing data file. Error 726 indicates that something minor in the file layout doesn't match the data on the disk, but these errors are ignored so you might see either an empty data file, or a data file with some records missing. If that happens, you need to see the missing records in order to figure out what is wrong with your layout. '''''It's very important that you don't try to use a file layout that isn't quite working right. Make sure your layout works and can read every record of a file that it should read before using it.'''''

To see the records that could not be read in a file, run the data crawler on the layout, then press CTRL-A to get an ATTN prompt. From there, enter the command

print mat BadRead$

and it will print all the records that were ignored because the file layout didn't match them. It prints out the raw data from the file.

==== Function Access to use Data Crawler in your programs ====
You can use the data crawler in your own programs by using one of the following functions:
* [[#fnDataCrawler|fnDataCrawler]] - Open a Listview showing the data file
* [[#fnDataEdit|fnDataEdit]] - Display the data in an editable grid
* [[#fnShowData|fnShowData]] - This function does the same thing as the above two, but with many many more options allowing you to customize exactly what appears and exactly what they're allowed to change.

Note: its not recommended to allow your customers to use the data crawler to access your data files directly. There's no way to specify validations or do anything complicated, so unless you're careful, there are lots of ways your customers could use this tool to do damage to your data files. It is a programmer tool only.

If you do decide to use it for your end users, be careful how you implement it.

=== Import/Export to CSV ===

You can use FileIO to export your data files to CSV or import from CSV into your data file. To do this, you want to run the data crawler and select the file layout you're looking for. Then, view it (or press F5 to edit if you want to import something). Click on the Export button and it will ask you to select a file. Once that is selected it will ask a couple other simple questions, and when you've specified the options to your satisfaction, click the Export! button. A new CSV file will be created.

Import is even more simple. To import, you must be in Edit mode (press F5 to select the file instead of the enter key) and then simply select the Import button. It will ask you again to choose the file, and then it will ask you if it should update all files by Record Number (if record number is recorded in the CSV file) or by Key (if the file has keys) or to just Add all information to the file. Select what you want and press Import and the CSV file is added to the BR data file.

==== Function Access to Import/Export from your programs ====

You can use the following functions to call the Import and Export functionality from your code.

*[[#fnCSVImport|fnCSVImport]]
*[[#fnCSVExport|fnCSVExport]]

These functions are intended to give you the ability to use our functionality to write your own import and export routines for your customers, because its not a good idea to let your customers run the Data Crawler.

=== Generate Layout Wizard ===

There is also a Generate Layout Wizard utility in FileIO. This utility is there to help you build your file layouts. It is designed to work with a certain style of BR programming that was common in the 80s and 90s. So if your software is written in a style that opens the file directly, and reads/writes the data to a long series of individual variables, the Generate Layout Wizard is for you.

To use it, start by running FileIO. Then, don't select a layout - instead, click on the "Generate Layout" button.

You'll see a screen with a bunch of large text boxes, a small grid, and some buttons.

The first thing you want to do is select the "Browse" button and then select a .wb or .br file that contains a program that reads or writes Most of the File.

When you select one, press the Scan All button and it fileio will search the whole program looking first for all the open strings. It will take the file that is opened the most times and then search for all read statements to that file. It will look for the longest read statement and then find the Form statement associated with that Read statement, and any DIM statements for any variables used.

If you don't like the file its chosen, click the "Open Scratch Pad" button to open the temp work file it uses into the program of your choice (I use myEdit for BRS files). Simply select all the open statements for the file you DO want to build off of, then click the Paste button to paste those open statements into the "Open String" list. After that click "Clear All" to erase what it did on the first search and then click "Scan All" again to rescan the program using this new data file.

You may have to help it a bit, but once it has a proper matching open statement, read statement, form statement and dim statements for any arrays used, press the "Generate Layout" button and it will build a layout for that file.

Finally, load the layout it built and clean up anything if you want, and consider adding better descriptions for each of the fields that you know (as it will use the variable names for both the subscripts AND descriptions in the layout).

When you're all done, click "Done".

==== Functions to Generate Layouts from your code ====

* [[#fnGenerateLayout_.26_fnWriteLayout|fnGenerateLayout]]
* [[#fnGenerateLayout_.26_fnWriteLayout|fnWriteLayout]]

=== Code Templates ===

One more tool FileIO has to help is the ability to generate code based on your file layouts.

Run FileIO and this time select a file layout and press "Generate Code". A window will pop up listing all the "Code Templates" that are available. Select one (and then select a key if it asks you - some templates require extra info). It looks like nothing happened, but the code you generated is now in your clip board. Paste it somewhere and take a look at it!

Code Templates help us to standardize our ways of doing things, which eventually leads to more and more powerful tools we can use. Code Templates also help ensure we use cleaner code by doing some of the busy-work of writing clean code for us.

==== Writing Code Templates ====
FileIO ships with several basic code templates. If you want to add your own, take a look in the filelay\templates folder (configurable in fileio.ini) and look at basic.brs. Copy it to your own program and then modify it to have your own code templates in it. Write me at gabriel.bakker@gmail.com with any questions. I want to help.

And if you write good code templates, its easy to share them with the BR community. Anyone can download your templates and place them in this folder and they'll instantly be available for use.

== FileIO Function Reference ==
''The FileIO Library contains a number of other useful functions.'' The following functions are available and you are welcome to use them:

=== Primary Functions ===

==== fnOpen ====
fnOpen is the primary function that opens a file, and it’s used like so:

''def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, DontSortSubs, Path$*255, Mat Descr$, Mat FieldWidths, SupressPrompt, IgnoreErrors, SuppressLog)''

Note that all of the parameters after MAT Form$ are optional. If you need to specify a parameter in the middle of the optional parameter group, just list zeroes and empty strings for the intervening unused parameters.

*FileName$ - The filename of the file layout for the file you’re reading.
*MAT F$ - The array that will be used to hold the string data for the file.
*MAT F – The array that will hold the numeric data for the file.
*MAT Form$ - An array of form statements.
*InputOnly – 1 means open for input only. 0 means open for OutIn and open every key file associated with the given data file (this is because all key files need to be open for the keys to be updated on an output) (defaults to 0). Files opened for input process considerably faster than files opened for output. Furthermore when files are opened for input only, alternate key files are ''not'' opened.
*KeyNum – This tells the function of which key to return the file handle (defaults to 1). Specify -1 to force the file to open Relative, without using its keys. If a file has no keys, it will always be opened Relative.
*DontSortSubs – The function by default, when compiling the Form statement, will sort the string and numeric subs in order to allow for reading the data into an array, and this parameter would turn this functionality off. However, if you are trying to read your data without reading it into an array, you are missing out on some serious efficiencies. You should normally leave this option turned off (0). This is a totally unsupported feature, and should always be set to 0, if it is specified at all.
*Path$ - The path to your data files. This optional parameter can be passed in by the calling function. It is prefixed to the beginning of the paths given in the file layout files. It is useful when your data files can be in different locations depending on the state of your program.
*mat Description$ - This optional parameter provides a way to read the description for each field from the original file layout. If the parameter is not provided, no description data will be returned.
*mat Fieldwidths – This optional parameter will return an array of the calculated display field widths. This number will always be at least large enough to contain the data for this field.
*SuppressPrompt - This optional parameter can be used to suppress the prompt normally given when fileIO creates a file. It can have three values. A value of 0, the default, uses the setting stored in your FileIO fnSettings routine to determine weather or not to prompt on Creation of a new file. A nonzero value always suppresses the prompt. A value of 1 indicates never to create a file if the file doesn't exist. A value of 2 automatically creates the file if the file doesn't exist.
*IgnoreErrors - Normally when fileio opens a data file, if there are errors trying to open the file, it prints them out to the debug console and pauses so that you can try to find out whats going wrong. If you specify 1 for "IgnoreErrors" it will cause Fileio to log those errors instead, and continue loading your program. This will result in the fnOpen file function returning Zero instead of the opened file number, so if you use IgnoreErrors, you need to test to make sure that fnOpen returned a file number before you try to access the file.
*SuppressLog - this optional parameter can be used to suppress writing to the log file for this one specific open statement. I use it for files that will be opened all the time, for example, the menu data file on one of my customers systems. Without this boolean parameter, his log file is quickly filled up with useless information any time his employees look at his menu. I specify this optional parameter to suppress logging anything about the menu file so that I can more easily find the actual programs they've used when looking in the logfile.

'''''Note: When using fnOpenFile, you really want to call your local function fnOpen, which in turn calls fnOpenFile for you.''''' FnOpenFile is for internal use only.

Example:

Let FFILE=FNOPEN(“FARM”,MAT FARM$,MAT FARM,MAT FORM$,0,2)
Let RFILE=FNOPEN(“ROUTE”,MAT ROUTE$,MAT ROUTE,MAT FORM$,1,3)
Let CFILE=FNOPEN(“CUSTOMER”,MAT CUSTOMER$,MAT CUSTOMER,MAT FORM$)

assuming:
farm.dat has 3 keys: farm.ky1, farm.ky2, farm.ky3
route.dat has 4 keys: route.ky1 … route.ky4
customer.dat has 2 keys: customer.ky1, customer.ky2

This will perform the following opens and set the following variables:

OPEN #1: “Name=Farm.Dat, kfname=farm.ky2”,internal,outin,keyed
OPEN #2: “Name=Farm.Dat, kfname=farm.ky1”,internal,outin,keyed
OPEN #3: “Name=Farm.Dat, kfname=farm.ky3”,internal,outin,keyed
OPEN #4: “Name=Route.Dat, kfname=route.ky3”,internal,input,keyed
OPEN #5: “Name=Customer.Dat,kfname=customer.ky1”,internal,outin,keyed
OPEN #6: “Name=Customer.Dat,kfname=customer.ky2”,internal,outin,keyed
LET FFILE=1
LET RFILE=4
LET CFILE=5

This will also resize the arrays, set the form statement, and create all the subscripts to make accessing the data clear and simple, as in the above example. The KEYNUM parameter is where you list the key file you would like to use for reading and writing. The extra keys are opened to ensure that all keys get updated properly when the file is changed.

Example:
DIM FORM$(1),PRICE$(1)*255,PRICE(1),
DIM DESCRIPTION$(1)*80,FIELDWIDTHS(1)

Let PRICEFILE=FNOPEN(“PRICE”,MAT PRICE$,MAT PRICE,MAT FORM$,0,2,0,"",MAT DESCRIPTION$)

Assuming the Price File layout (filelay\price) contains:

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30

This will perform the following opens and set the following variables:

OPEN #1: “Name=Price.Dat, kfname=Price.ky2”,internal,outin,keyed
OPEN #2: “Name=Price.Dat, kfname=Price.ky1”,internal,outin,keyed
OPEN #3: “Name=Price.Dat, kfname=Price.ky3”,internal,outin,keyed
let PRICEFILE=1
let PR_FARM=1
let PR_ITEM=2
let PR_GRADE=3
let PR_DESCR=4
let PR_PRICE=1
let PR_COST=2
let PR_XOPRICE=3
let PR_XOCOST=4
let PR_MOPRICE=5
let PR_MOCOST=6
let PR_VOPRICE=7
let PR_VOCOST=8
MAT FORM$(1)
MAT PRICE$(4)
MAT PRICE(8)
MAT DESCRIPTION$(12)
MAT FIELDWIDTHS(12)
let FORM$(1)=CFORM$(”form C 4,C 4,C 4,POS 74,C 30,POS 50,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2”)
let Description$(1)= “Farm Code (or blank)”
let Description$(2) = “Item Code”
let Description$(3) = “Quality”
let Description$(4) = “Description of Price Rule”
let Description$(5) = “Default Price”
let Description$(6) = “Default Cost”
let Description$(7) = “Default Christmas Price”
let Description$(8) = “Default Christmas Cost”
let Description$(9) = “Default Mothers D Price”
let Description$(10) = “Default Mothers D Cost”
let Description$(11) = “Default Valentine Price”
let Description$(12) = “Default Valentine Cost”
let FieldWidths(1) = 4
let FieldWidths(2) = 4
let FieldWidths(3) = 4
let FieldWidths(4) = 30
let FieldWidths(5) = 8
let FieldWidths(6) = 8
let FieldWidths(7) = 8
let FieldWidths(8) = 8
let FieldWidths(9) = 8
let FieldWidths(10) = 8
let FieldWidths(11) = 8
let FieldWidths(12) = 8

There are a few things I’d like to point out about the example above. First, you will notice that the form statement jumps around to put all the strings first, and then the numbers last. This is why it has a “POS 74, C 30,POS 50”. Then notice that the subscripts for the string variables are 1 .. 4, and the subscripts for the numbers are 1 .. 8. Finally, the order of the Description and FieldWidth fields also match the sorted positioning of the Form Statement.

The reason that we sort our form statements is so that BR will allow us to read the file into arrays by saying:

Read #pricefile, using form$(pricefile) : mat price$, mat price

Without resorting, the above statement would give a conversion error as BR attempted to put the PR_PRICE field inside mat price$(4). However, because we have reordered the form statement, we are able to read them safely into two arrays, and then we will be able to use the values without caring what position they are in the file, by simply saying PRICE$(PR_DESCRIPTION) when we want the description, and PRICE(PR_PRICE) when we want the pr_Price field.

Another thing you may notice about the above example is that it gives the calculated display length for the numeric fields as 8, when on the disk (and in the file layout) they are listed as BH 3.2. The reason for this is the program looks at the BH 3, and figures that a number that takes up 3 bytes on disk has a potential maximum size of 256**3 or 16,777,216, and therefore will need up to 8 characters of screen display space to view.

Finally, note that any field with a form statement of X is ignored by the library, except that the blank space is used when building the FORM statement.

==== fnCloseFile ====
This function will close the specified file number and all keys that were opened with the file. The purpose of this function is to facilitate the closing of the extra keys that are opened when you open a file for OutIn with the library. There is no need to use this for files opened for input because it is easier to just close the file directly. Secondary keys are not opened by FileIO for files opened for input only.

You must give the function the name of the file layout. It uses this information to determine how many keys were opened, and how many it must therefore close.

Then it basically starts at the file number you gave it, and closes the next X files that were opened with the same file name as this, where X is the number of keys associated with this file.

The syntax is:

''fnCloseFile(filenumber,filelay$;path$)''

*FileNumber – The filenumber of the file you are trying to close.
*FileLay$ - The name of the file layout for this file. This is used to determine how many keys the file would have been opened with and therefore how many we now need to close.
*Path$ - Optional Alternate Path. Use to close files that were opened using the open file's optional alternate path parameter.

==== fnGetFileNumber ====
FnGetFileNumber is a simple function to find a valid unused file handle. If you use this function in all of your programs, they will become much more portable, as you will never have to worry about your file handles fighting with each other. The function will return 0 if no free file number was found (but with 999 of them available now, I have never seen it happen).

''fnGetFileNumber(;X,Count)''

*X – This optional parameter will specify where to start looking.
*Count - This optional parameter will specify how many file numbers to find in a row. If count is 3, then fnGetFileNumber will return the first filenumber in the first gap of three unused file numbers that it finds.

=== File Reading Helper Functions ===

These functions perform various useful calculations to aid in interacting with data files when you're using fileio.

==== fnBuildKey$ ====
This function will return the key for a given record in a data file. It actually reads the file layout and builds the key to match the layout.

''FnBuildKey$(Layout$, Mat F$, Mat F; Keynum)''

*Layout$ - the name of the data file to build the key for.
*Mat F$ - the string array of the file object
*Mat F - the numeric array of the file object
*KeyNum - This optional parameter specifies which of the key files in the given layout the key should be built for.

To use this, you want some code like in the following example:

mat customer$=("") : mat Customer=(0)
let customer$(cu_name)=CustName$
let customer$(cu_phone)=CustPhone$
read #customer, using form$(Customer), key=fnBuildKey$("customer",mat Customer$,mat Customer,2) : mat Customer$, mat Customer nokey KeyNotFound
! The above code assumes that the second key of the Customer file is based on the Name and Phone fields.

By using this logic you are able to avoid directly specifying the key in your code - which means that even if the key changes in the future, as long as your code specifies enough information, it will still find the correct key. In our example, even if we dropped the phone number from the key in the future, or even if we expand the length of the Customer Name field, our code would still work and fnBuildKey$ would still build the correct key without us having to look at or change our code again.

This kind of reasoning is central to the fileio system, which, when implemented properly, ensures that you can change your data files in any way you need to in the future, without breaking your existing programs.

==== fnUniqueKey ====
This function tests to see if a given key is unique to the specified file. This function is very useful for situations where you need to ensure that the user-entered key is unique.

''fnUniqueKey(Fl,key$*255)''

*FL – The file number of the opened file.
*Key$ - This is the key to test. If this key is the key for a preexisting record in the file, the function will return false. If this key can not be found in the file, the function will return true.

==== fnMakeUniqueKey$ ====
This function generates a unique key for a given file. This is useful if you do not care what the key is, but it needs to be unique. I use this function in situations where the user never needs to know what the given key is.

This function reads the key length for the given file. Then it returns a string that is the right length, which is generated by counting in binary until a key is found that does not appear in the file. The first key found for a 4 byte key field would be chr$(0)&chr$(0)&chr$(0)&chr$(0). If that key was already in use in the file, the function would return chr$(0)&chr$(0)&chr$(0)&chr$(1). If that one was also in use, it would then try chr$(0)&chr$(0)&chr$(0)&chr$(2), and so on until it found one that wasn’t in use.

''FnMakeUniqueKey$(fl)''

*FL – This is the file number of the opened file for the desired key.

==== fnKey$ ====
This function formats the key for the given file number. All it does is ensure the key is the correct length. You should use fnBuildKey$ instead to properly build the correct key for the record you want to read.

''FnKey$(FileNumber, Key$)''

*FileNumber - the file number we are formatting the key for
*Key$ - the key we are trying to format.

==== fnNotInFile ====
This function will determine if a non-key element in a line is unique. It works almost exactly like fnUniqueKey specified above, except that it allows you to enter the subscript value of the element you are checking for uniqueness. You can use this to look for uniqueness in any field, not just in the key field. Additionally, the search engine used by this function looks for a partial match, and will only return true if the given string is not found anywhere in the specified element for the given file.

''fnNotInFile(string$*100,filename$,sub)''

*String$ - Value to check for uniqueness in this file.
*Filename$ - This is the name of the file layout of the file you want to check. This file does not have to be open in order for you to search it, because the function will open it for you.
*Sub – This is the subscript value of the element you are checking.

==== fnSortKeys ====
This function takes an array of Primary Keys indicating records in the data file, and resorts it into the order you would have expected using one of the other keys for your data file.

For example: Lets say you had a customer file, and the first key was Customer Code and the second key was Customer Last Name. This function would take an array of Customer Codes and sort it into Last Name order.

This function requires the file to already be opened (which is usually the case when you have an array of keys from that file).

''fnSortKeys(mat Keys$,Layout$,DataFile,mat F$,mat F,mat Form$;KeyNum)''

*mat Keys$ - the array of keys. These keys are based on whatever key the file was opened with in DataFile.
*Layout$ - the file layout for the file.
*DataFile - the open file number matching the key file that matches mat Keys$.
*mat F$ - array sized to hold the strings from the data file. This is the array you get back from fnOpen.
*mat F - array sized to hold the numerics from the data file. This is the array you get back from fnOpen.
*mat Form$ - array of form statements, that you get back from fnOpen.
*KeyNum - This is the key that we'll sort based on. If not given, the first key listed in the layout is assumed.

=== File Reading Functions ===

These functions actually read information from your data file and return it. These functions can be used to simplify the logic in your programs for many common tasks.

==== fnReadAllKeys ====
This function will read through a file, returning the specified element(s) from each record into (a) dynamically dimensioned array(s). For example, I could tell it to give me the Inventory Code for every inventory item in my database in one array, while placing the Inventory Description (name) for each item into the corresponding position in another array.

''fnReadAllKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$;sub2,mat out2$)''

*Fl – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array
*mat out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

For example:

FnReadAllKeys(InventFile,mat Invent$,mat Invent,mat Form$,IN_Code,mat InvtList$,IN_Name,mat InvtNames$)

==== fnReadMatchingKeys ====

This function will read through a file, returning the specified element(s) from each record where the key matches the specified key into (a) dynamically dimensioned array(s). This function is the same as the above function except this one will filter the results, returning only those records where the key matches the specified key.

''fnReadMatchingKeys(Fl,mat f$,mat f,mat fm$,key$,keysub,sub1,mat out1$;sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - Only records where the key field matches key$ will be returned.
*Keysub – This tells the function which element is the key element for this particular file number.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadAllNewKeys ====

This function will read through a file, returning the specified element(s) from each record that isn’t already there into (a) dynamically dimensioned array(s). This function is the same as the above function, except this one will filter the results returning only those records that don’t already exist in the array (eliminating duplicates).

''FnReadAllNewKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$; dont_reset,sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Dont_reset – By default the array will clear the contents of the arrays that are passed in. This Boolean flag will instruct the function to not empty the passed in arrays.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadFilterKeys ====

This function by Mikhail Zheleznov is a modification of the above functions. Like its predecessors, it reads an entire file, populating the specified arrays with data from all or some of the records in the file. The given subscripts specify which fields to return from each record. The key given specifies search criteria for the records. The filter specifies filtering criteria that can be preformed on the data before it is returned.

''FnReadFilterKeys(Fl,Mat F$,Mat F,Mat Fm$,Key$,Keyfld,Sub1,Mat Out1$;Filter$,Filter_Sub,Readlarger,Sub2,Mat Out2$, Sub3, Mat Out3$, Sub4,Mat Out4$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - The key to search for in the read statements
*Keyfld – the subscript of the key field in the data file. This must match the key field specified in the data file otherwise the function won’t work.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Filter$ – This optional parameter identifies matches to search for in the records. It works in conjunction with Filter_Sub
*Filter_Sub – This parameter specifies which field to look for in the records for matches to Filter$. Only records which have Filter$ in the specified field will be returned.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.
*Sub3 – Subscript of the element to return in the third array. This is optional. If it is specified, you must give MAT out3$, or BR will return an error.
*MAT out3$ - Array in which to return the third (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub3 is given (non-zero). This parameter will not be used if Sub3 is not given or is given as 0.
*Sub4 – Subscript of the element to return in the fourth array. This is optional. If it is specified, you must give MAT out4$, or BR will return an error.
*mat out4$ - Array in which to return the fourth (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub4 is given (non-zero). This parameter will not be used if Sub4 is not given or is given as 0.

This function was written by Mikhail Zheleznov for the fileIO library.

==== fnReadDescription$ ====
''fnReadDescription$(Fl,Subscript,key$,mat F$,mat F,mat Form$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout) (RT_NAME, which should equal 2 after opening routefile (unless we change the file layout later)).
*key$ - Item that should match a key in this file somewhere (in this case it is the route code from the farm record).
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading they have to be dimensioned properly, which is why we use our colorcat$ and our colorcat for these parameters.
*mat Form$ - This will need to be our array of form statements, so the function can read the file properly.

Lets take a look at how this function works:

In the example program I used above, I am reading the Color File to get details about each color. The color file contains a colorcat code field, but I want to display the colorcat description. The colorcat file contains a few details about a color category, and it is indexed based on colorcat code:

route.dat, RT_
route.key, CODE
recl=512
===================================================
CODE, Routing Code, C 6
NAME, Routing Name Description, C 30
MOFT, T/A/C (truck/air/courier), C 1
SHIPPINGDAY, Day of Week for Shipping, C 7

Now, as you know, in the above example, we have already opened the ColorCat File, and we have opened and read a Color record.

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
30180 LET ccode$=color$(CO_CODE) !:
LET Name$=color$(CO_NAME)

Now all that’s left to do is to take the Color File’s ColorCat code and use it to look up the ColorCat File’s description.

30190 LET ColorCat$ = fnReadDescription$(ColorCatFile, CC_NAME, Color$(CO_CATEGORY),
mat ColorCat$, mat ColorCat, mat form$)

==== fnReadUnopenedDescription$ ====
This function accomplishes the same thing as fnReadDescription except that it opens the data file for you. It is slower then FnReadDescription$, but it is easier to use.

''FnReadUnopenedDescription$(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the value of the key field in the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2, so sometimes it is a good idea to design your data files so that string field number two is a descriptive field, like Name or Description.

This function only works on the first key file for each data file. This function is a convenience function but it is slow because it opens the file and closes it for each call. Opening a file is one of the most time consuming program operations.

==== fnReadNumber ====

fnReadNumber does the same thing that ReadDescription does except it reads a numeric field instead of a description.

Lets take a look at how this function works:

''fnReadNumber(Fl,subscript,key$,mat F$,mat F,mat fm$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout).
*Key$ - Item that should match a key in this file somewhere.
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading. They have to be dimensioned properly by [[FileIO_Library#fnOpenFile|fnOpen]].
*mat Fm$ - This will need to be our array of form statements, so the function can read the file properly.

==== fnReadUnopenedNumber ====
This function accomplishes the same thing as fnReadNumber except that it opens the data file for you. It is slower then FnReadNumber, but it is easier to use.

''fnReadUnopenedNumber(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the key of the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2.

==== fnReadRelativeDescription$ ====
This function is the same as fnReadDescription$ but for Relative Files.

''fnReadRelativeDescription$(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat F,mat form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedDescription$ ====
This is the same as ReadUnopenedDescription$ but for Relative Files.

''fnReadRelUnopenedDescription(Layout$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRelativeNumber ====
This is the same as fnReadNumber but for Relative Files.

''fnReadRelativeNumber(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat f,mat Form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedNumber ====
This is the same as fnReadUnopenedNumber but for Relative Files.

''fnReadRelUnopenedNumber(LayoutName$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRecordWhere$ ====
This function returns the record where the given element matches the given value. It does not depend on any key files, and it can be used to locate a record based on any element. However, it loops through the entire data file to do this and it could be a bit slow for large data files. This function opens the file for you, so the file does not have to be already opened.

''FnReadRecordWhere$(Layout$,SearchSub,SearchKey$*255,ReturnSub)''

*Layout$ - the layout of the file we are searching
*SearchSub - Subscript of the element to look in
*SearchKey$ - The value we are looking for
*ReturnSub - Subscript of the element to return

=== FileIO Utility Functions ===
==== fnDataCrawler ====
This function launches the Data Crawler as a function, so you can make your own programs link to it. Special thanks to Mikhail Zheleznov for turning the DataCrawler into a library function.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnDataEdit ====
This function is the same as fnDataCrawler only it opens a Grid for editing.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnShowData ====

This function builds a list or a grid in a floating window that is tied to a data file. It uses the same function that the datacrawler uses, but its much more customizable. All other datacrawler functions are just wrappers for this one.

The first parameter is the only required parameter.

''def library fnShowData(FileLay$;Edit,sRow,sCol,Rows,Cols,KeyNumber,Caption$*127,Path$*255,KeyMatch$*255,SearchMatch$*255,CallingProgram$*255,mat Records,mat IncludeCols$,mat IncludeUI$,mat ColumnDescription$,mat ColumnWidths,mat ColumnForms$,DisplayField$*80,mat FilterFields$,mat FilterForm$,mat FilterCompare$,mat FilterCaption$,mat FilterDefaults$,mat FilterKey)''

*FileLay$ - the file layout you want to display
*Edit - 1 for Edit (Grid) and 0 for View (Listview)
*sRow, sCol - the start position. if not given, its centered. If given but out of bounds, they'll be automatically adjusted to fit the grid on the screen.
*Rows, Cols - the size. If not given, defaults to fullscreen. If given but not big enough to fit the UI elements you request, they're automatically adjusted to fit everthing.
*KeyNumber - the Key to use when reading the data, used with other parameters. If not given, the file is read Relative for faster performance. Required if KeyMatch$ is given.
*Caption$ - the Caption to display, defaults to FileIO's Datacrawler
*Path$ - Alternate path to use for data files (Prepended to the name found in the layout)
*KeyMatch$ - Show only records that match this key. You can use Partial Keys. If this parameter is given, you must also give KeyNumber (above).
*SearchMatch$ - Show only records that contain this substring in them anywhere
*CallingProgram$ - used for logging purposes, pass in the system function Program$
*mat Records - Show only these records in the Grid. Use it to control exactly what the user sees.
*mat IncludeCols$ - Show only these columns. These column names must match the subscript names from the file layout.
*mat IncludeUI$ - Which UI Options to show. Build this array with one element for each optional UI element to include. Explanations of UI elements follow:
**"ColumnsButton" - adds a Select Columns button that the user can use to modify which columns appear on the list.
**"ExportButton" - adds an Export to CSV button that exports the data to a CSV file.
**"ImportButton" - adds an Import from CSV button that imports from the CSV file.
**"AddButton" - adds a button that can be used to add records to the data file.
**"SaveButton" - adds a button allowing the user to save changes
**"DeleteButton" - adds a button allowing the user to delete a row
**"KeyButton" - adds a button allowing the user to jump to a specified position by key or by record number (depending on if the file is opened keyed or not)
**"QuitButton" - adds a Quit button to the screen (the Esc key also quits)
**"Search" - adds a case insensitive search box to the screen.
**"Border" - adds a border around the screen
**"Caption" - adds a caption. (If you specify a caption, this is automatically turned on. If you don't specify a caption but turn on caption here, then FileIO uses the default FileIO data crawler caption.
**"Recl" - adds the Recl to the caption
**"Position" - adds the positions to the field descriptions in the column headings.
*mat ColumnDescription$ - Show these captions. If blank, use the descriptions from the layout
*mat ColumnWidths - Use these widths for the data, if not given, calculate from the file layout
*mat ColumnForms$ - Display Format for the data, including DATE and FMT and PIC
*mat DisplayField$ - Counter Field to display on the Loading Window. If its a field with an associated DATE ColumnForms$ value, that column form will be used when displaying the Counter Field. It can be any of the following:
**REC - this will display the current "REC/LREC" data in the loading window.
**READCOUNT - this will display the "Record Count / LREC" in the loading window.
**FINDCOUNT - this will display the number of records that match the current search criteria by itself in the loading window.
**A Field Name - one of your field names will display that field value in the loading window
**A string literal - anything else will display as a string in the loading window, so you could put something like "Loading, please wait" here and it will display.
*mat FilterFields$ - Contains the subscript of the field to compare to
*mat FilterForm$ - Contains the format of the field to compare to
*mat FilterCompare$ - Contains the comparison type ("<>" or ">" or "=" or ">=" or "*") (* means do a substring search)
*mat FilterCaption$ - The caption for the filter box
*mat FilterDefaults$ - The default value for the filter information
*mat FilterKey - The action to use when filtering the data this way (0 means simple exclude, 1 means start here, -1 means stop here)
**The final five arrays can be used to add user filter boxes to the data grid. You need one element in each array for every custom user filter box on the screen.

==== fnBeginAudit ====

The [[AuditBR|FileIO Compare]] routine is available and can be called from within your programs. To do so, call fnBeginAudit to mark the Start of the compare, then do whatever you need, then run fnCompare to compare everything that has changed between when you ran fnBeginAudit and when you ran fnCompare.

See [[AuditBR#fnBeginAudit|the documentation]] for more details.

==== fnCompare ====

See [[AuditBR#fnCompare|the documentation]] for more details.

==== fnCSVImport ====

This function calls the FileIO Import routine, the same one that you get from the Datacrawlers Import Button.

''fnCsvImport(Layout$*64;SuppressDialog,FileName$*300,ImportModeKey)''

*Layout$ - The file layout to import into
*SupressDialog - 1 to Supress the Import Dialog
*FileName$ - the name of the CSV file (Required if Dialog is Suppressed)
*ImportModeKey - the Import Mode Key (Required if Dialog is Suppressed)
**-1 - Add all records to the file
**0 - Update by Record Number (The file must contain a RecNum column and it must be first)
**1+ - Any positive number means Update by that Key (as listed in the layout).

==== fnCSVExport ====

This function exports a data file to a CSV file.

''fnCsvExport(Layout$*64;SuppressDialog,Filename$*300,IncludeRecNums,KeyNumber,StartKey$,KeyMatch$,Startrec,mat Records,SearchMatch$)''

*Layout$ - The File Layout to Export
*SuppressDialog - (1 to Suppress the Export Dialog, 0 to show it)
*Filename$ - the output file name (Required if SuppressDialog is 1)
*IncludeRecNums - Include a column with the Record Numbers in it
*KeyNumber - Use this key when reading the data for export
*StartKey$ - Start with the record that matches StartKey$
*KeyMatch$ - Export only the record(s) that match KeyMatch$
*StartRec - Start with this Record Number
*mat Records - Export only these records
*SearchMatch$ - Export only records containing this search string anywhere in them

==== fnExportListViewCsv ====

Exports the contents of the specified Listview in CSV format.

''fnExportListViewCsv(Window,Spec$;GenFileName,Delim$,FileName$*255)''

*Window - The Window containing the listview.
*Spec$ - The Spec identifying the listview.
*GenFileName - Flag telling weather or not to generate the file name.
*Delim$ - Delimiter to use. Comma is default.
*Filename$ - Filename to use

==== fnGenerateLayout & fnWriteLayout ====

This function calls on the Generate File Layout Wizard to generate and save the layout indicated by the parameters you give it. You must give it the same valid parameters that you would have come up with if you worked through the layout wizard the normal way, by running FileIO directly and choosing "Generate Layout".

You can also bypass the automatic parsing and generate a layout by specifying all the data directly and using fnWriteLayout.

''fnGenerateLayout(mat OpenStrings$, ReadString$*999, FormString$*20000, DimString$*999; DisplayFile)''
''

*mat OpenString$ - array of all the open strings for the given file from one of your old programs.
*mat ReadString$ - solid read statement from one of your old programs reading the entire record, (or at least everything you want in the layout).
*mat FormString$ - the form statement that goes with the ReadString$ (practice using the Generate Layout Wizard the normal way for details)
*mat DimString$ - the string containing Dim statements for each array mentioned in ReadString$. We need this to know how big the arrays are.
*DisplayFile - if True (1), it will Display the new layout in notepad when its done creating it. If false (0), it will simply create the file.

fnGenerateLayout takes all the above information and parses it into a layout, then calls fnWriteLayout to actually write the layout.

If you already know the information you want to put in the layout, its more direct to call fnWriteLayout below.

''fnWriteLayout(Name$,FileName$*127,VER,PRE$,MAT KFNAME$,MAT KDESCRIPTION$,MAT SUBS$,MAT DESCR$,MAT FORM$;RECL,MAT EXTRA$,DISPLAYFILE)''

*Name$ - the name of the new layout
*FileName$*127 - the name of the data file
*Ver - the version of the data file
*Pre$ - the prefix to use for the data file
*mat KfName$ - array of all the keys for the file
*mat Kdescription$ - array of the subscripts that each key is based on
*mat Subs$ - the subscript for each field in the file
*mat Descr$ - the descriptions for each field in the file
*mat Form$ - the form specs for each field in the file
*Recl - (optional) the record length of the file
*mat Extra$ - (optional) Additonal Information for each field in the file, placed in the Comments column of the new layout. This column is ignored by standard fileio processing.
DisplayFile - if True, open the file in Notepad after it has been created.

==== fnSubstituteStringCode ====
A Large Text Field that is searched. Code is run and any resulting variables are set, if they exist inside String enclosed between Substitute Chars (default []), then they will be replaced with the values derived by the code.

''fnSubstituteStringCode(&String$,Code$*2048;SubstituteChar$)''

*String$ - the string to be searched
*Code$ - code to be run. The resulting variables can be substituted into String
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnSubstituteString ====
A Large Text Field that is searched. Any matching fields in the passed in record will be substituted into their places. For example, if the string contained [cu_name] and you ran substitutions on the Customer file, then [cu_name] would be replaced by the name in the actual Customer record.

''fnSubstituteString(&String$,Filelayout$,mat F$,mat F;SubstituteChar$)''

*String$ - the string to be searched
*FileLayout$ - the layout to be searched
*mat F$ - the record to be used for substitution
*mat F - the record to be used for substitution
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnShowMessage ====
Displays a message to the user, in a child window. Returns the child window number, so that you can close it when you're done with the message.

''WindowNumber=fnShowMessage(Message$*54)''

*Message - the Message to display to the user

=== File System Utility Functions ===
These functions perform other tasks that aid with interacting with the file system.

==== fnGetFileDateTime$ ====
This does a directory listing to determine the Last Modified Date and Time of the given file. You pass it a file name, not a file layout, and it can be used on any file. Its not limited to BR internal files.

The syntax is:

''let FileDate$=fnGetFileDateTime$(Filename$*255)''

==== fnProgressBar ====
There's a Progress Bar that FileIO uses when copying or updating data files. You can use it in your own functions by calling fnProgressBar inside the main loop of the process that you want to display the progress bar over, and by calling fnCloseBar when you're done.

''fnProgressBar(Percent;Color$,ProgressAfter,ProgressThreshhold,UpdateThreshhold,Caption$*255,MessageRow$*255)''

*Percent - Percentage Complete expressed as a float between 0 and 1
*Color$ - HTML Color Code of BR Color Attribute to color the Progress Bar. Defaults to Green.
*ProgressAfter - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*ProgressThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*UpdateThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*Caption$ - Optional message to display above the progress bar.
*MessageRow$ - Optional message to display on the progress bar.

==== fnCloseBar ====

''fnCloseBar''

Call this function to close the progress bar window when your task is done running.

==== fnCopyFile ====

''fnCopyFile(FromFile$*255,ToFile$*255)''

*FromFile$ - The file to copy.
*ToFile$ - The destination file name including path.

This function copies any file, by opening it as an external file and reading and writing the data to the destination file. The advantage of this technique, over using the BR copy command, is this routine is more reliable when run on client server where you may be transferring large files from one side to the other over the internet.

This fnCopyFile also has a progress bar that displays as the file is transferred, so the user knows your software is busy.

This function works over Client Server. Under Client Server, specify @: at the beginning of your filename, to specify that the file is on the client. If the file is on the server, simply leave the @: off. See the chapter on [[Copy#Client_Server|using BR's copy command under Client Server]] for more details on the "@:".

This function's parameters and syntax are modeled off of the built in BR copy command, and like that one, this should work for local transfers, LAN transfers, or even internet transfers. This function will work better for internet transfers then the built in BR Copy Command, however.

==== fnCopyDataFiles ====

''fnCopyDataFiles(DestinationFolder$*255)''

*DestinationFolder$ - the folder to copy your data files to.

This function reads your file layouts and makes a copy of every data file (and key file) in your system to the destination folder, utilizing fnCopyFile above, for better performance and reliability when running over the internet, as well as a progress bar for each individual file.

It also displays a listview while its copying so you can watch the progress while its transferring your data files.

This can be used for making backups of your BR data, or for transferring the latest data onto a laptop for access to it while you're on the road away from the internet.

==== fnReIndex ====

This function reindexes a single data file

''fnReIndex(DataFile$*255;CallingProgram$*255,IndexNum,Path$*25)''

*Datafile$ - the file layout of the file to index
*CallingProgram$ - used for logging, pass Program$ in here
*IndexNum - The index to rebuild - if not given, rebuilds all indexes
*Path$ - the optional alternate path to use for rebuilding the data file.

==== fnReIndexAllFiles ====

This function reindexes all your data files. It doesn't require any parameters.

''fnReIndexAllFiles''

==== fnUpdateFile ====
This function checks and Updates a data file if it needs to be updated, by opening and then closing the data file.

''fnUpdateFile(FileLayout$)''

*FileLayout$ - The name of the file to update

==== fnRemoveDeletes ====

This function, written by Susan Smith, removes deleted records by copying the file with the -D option.

''fnRemoveDeletes(LayoutName$*255;Path$*255,CallingProgram$*255)''

*LayoutName$ - the file layout
*Path$ - Optional Alternate Path
*CallingPRogram$ - used for logging, pass Program$ in here

=== Layout Interrogation ===
Layout interrogation functions are provided for convenience and to enable future dictionary changes without disrupting any programs that interrogate it.

==== fnMakeSubProc ====
This function obtains the subscript assignments that were assigned by fnOpen according to the file layout. The fnMakeSubProc$ routine obtains the subscript assignments without actually opening the file. This is useful when a file record is passed as arrays into a library function in another program, or when you chained to another program and you need to know how to reach the data in the arrays without actually reopening the file.

''fnMakeSubProc(filelay$;mat Subscripts$)''

*FileLay$ - The name of the file layout from which to read the subscripts.
*mat Subscripts$ - If you give this optional array, fnMakeSubProc passes the subscripts back in this array rather then in the subs.$$$ file. This is much faster and helps avoid sharing conflicts.

When this routine returns, you can set the subscripts in your program by executing every element of the Subscripts$ array in a for/next loop.

If you did not pass in a subscripts array, then the a procedure file named subs.$$$ is created. If you proc that file, the proper subscripts will be set.

==== fnReadLayoutArrays ====
This function reads the fields in a file layout into arrays. You call it like the following

''fnReadLayoutArrays(filelay$,&prefix$;mat SSubs$, mat NSubs$, mat SSpec$, mat NSpec$,mat SDescription$, mat NDescription$,Mat Spos,Mat Npos)''

*filelay$ - the name of the layout to read
*prefix$ - the return value for the prefix for the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

This function call would read the fields from the layout in filelay$, and it would return the prefix to prefix$. The Subs would be returned in mat SSubs$ and mat NSubs$.

The Spec statements are returned in mat SSpec$ and mat NSpec$ and the Descriptions are returned in mat SDescription$ and mat NDescription$. The start positions on disk of each element are returned in mat SPos and mat NPos.

All the arrays are optional. If you don’t pass them the information they are supposed to record is simply not returned.

==== fnReadLayoutHeader ====
This function reads the header for a given file layout.

''fnReadLayoutHeader(Layoutname$*255;&Filename$,Mat Keys$,Mat KeyDescription$)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file

==== fnReadEntireLayout ====
This function reads the entire layout by calling fnReadLayoutHeader and fnReadLayoutArrays.

''fnReadEntireLayout(Layoutname$*255;&Filename$,&Prefix$,Mat Keys$,Mat KeyDescription$,Mat Ssubs$,Mat Nsubs$,Mat Sspec$,Mat Nspec$,Mat Sdescription$,Mat Ndescription$,Mat Spos,Mat Npos)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*prefix$ - the return value for the prefix for the file
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

==== fnReadSubs ====
This function reads the subscripts from a layout into Subs arrays.

''fnReadSubs(Layout$,mat SSubs$,mat NSubs$,&Prefix$)''

*Layout$ - the file layout name
*mat SSubs$ - the String Subscript Names
*mat NSubs$ - the Number Subscript Names
*Prefix$ - the files Prefix

==== fnReadKeyFiles ====
This function reads the list of key files from the layout.

''fnReadKeyFiles(Layout$,mat Keys$)''

*Layout$ - The file layout
*mat Keys$ - output array, the keys are returned here.

==== fnLayoutExtension$ ====

This function returns the layout extension being used.

==== fnReadLayouts ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''FnReadLayouts(mat Dirlist$)''

*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all the file layouts that FileIO can find.

==== fnDirVersionHistoryFiles ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''fnDirVersionHistoryFiles(Layout$,mat DirList$;BypassExtension$)''
*Layout$ - Which layout to look up version history of
*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all previous versions from history of the requested layout.

==== fnReadLayoutPath$ ====
This function doesn't actually interrogate your layouts. Instead, it interrogates your settings and returns the path specified for your layout files. This would usually be "filelay\" but you can change it in [[#fnSettings|fileio.ini.]]

It has no parameters.

''let Path$=fnReadLayoutPath$''

==== fnDoesLayoutExist ====
This function returns true if the given file layout exists. It returns false if the layout does not exist.

''FnDoesLayoutExist(layout$)''

*Layout$ - Layout to test for

==== fnReadForm$ (uncompiled) ====
Sometimes you need to know the original form statement that fileio is using to read your data file, most often when you're debugging your file layout, and you're getting some problem when reading the file. The form statement that fileio normally returns is compiled using CFORM$ to save space in the array, and to make the execution of your read statements faster. You can use this function to return the original form statement for the file.

The syntax is:

''let FormStatement$=fnReadForm$*10000(FileLayout$)''

Remember to dimension FormStatement to something huge! fnReadForm$ can return up to 10,000 characters.

==== fnReadFormAndSubs ====

This function does the same as above but it also reads the subscripts from the file into an array.

''let fnReadFormAndSubs(Layout$,mat Subs$,&ReadForm$,&StringSize,&NumberSize)''

Note that unlike most of our functions, all the above parameters are required.

The layout is the layout you're interrogating. The Array will be populated with the subscripts after the function. The ReadForm$ variable will be filled with the form statement for the file. Remember to dimension it large enough. StringSize and NumberSize will contain the number of string fields and numeric fields in the file.

Mat Subs$ will be returned, strings first, numbers last, matching the form statement that is returned. So Subs$(1) is the first string subscript and Subs$(StringSize+1) is the first Numeric subscript.

==== fnClearLayoutCache ====

fnClearLayoutCash (v2.3+) clears out the cache of layout name and data to get realtime Updates to File Layouts.

=== Other Useful Functions (non-layout related) ===

==== fnAskCombo ====

Opens a window with a combo box and returns the users selection.

''fnAskCombo$*255(mat Description$;Caption$*60,Default$*255)''

*mat Description$ - contains the combo box choices
*Caption$ - contains the optional caption for the window
*Default$ - the text of the item in mat Description$ that you want to be selected by default

==== fnSendEmail ====

This function sends an email and an optional attachment to the email address specified.

''fnSendEmail(Emailaddress$*255,Message$*10000;Subject$*255,Invoicefile$*255)''

*EmailAddress$ - the Destination Email Address
*Message$ - the Message$ to send
*Subject$ - the subject
*InvoiceFile$ - the filename of a file to attach. This is the BR filename (the function automatically converts it to an OS Filename.)

The function returns 1 when the email was sent successfully, or 0 if it wasn't sent successfully.

In order to use this function, you must have the emailcfg file layout in your layouts folder and you must have a copy of SendEmail.exe which is free and can be downloaded from the internet. Both of these files are included with the latest update of fileio.

You also have to configure fileio with the authentication information for your email server.

To configure your email server, simply run FileIO to get the data crawler, then select the emailcfg file layout and press F5 to edit it. Add a row if the file is empty.

Simply fill in the information the file is asking for in the appropriate fields and save the data, and then test sending an email to make sure it worked.

More information about sendEmail.exe is available from the author's product site here: [http://caspian.dotconf.net/menu/Software/SendEmail/ http://caspian.dotconf.net/menu/Software/SendEmail/]

==== fnClientEnv$ ====

This function returns the value of a Windows Environment Variable on the client under Client Server.

''fnClientEnv$*255(EnvKey$)''

*EnvKey$ is the name of the Windows Environment Variable to check on the client.

The function returns the value of the entered environment variable.

==== fnClientServer ====

This function returns true if you're currently running in Client Server mode, and false if you're running in the old "native" mode.

==== fnEmpty & fnEmptyS ====
These functions test if the passed in array is empty or not..

The syntax is:

''fnEmpty(mat Numeric)''

or

''fnEmptyS(mat String$)''

Example:

def fnSomeFunction(String$,mat Array$; mat OtherArray)
if fnEmpty(mat OtherArray) then
! Arrays were empty.
end if
fnend

==== fnReadScreenSize ====
This function reads the screen size of the given window (or window 0 if a window wasn't passed.) This is useful for centering a window on the screen, or for making sure window 0 is big enough for the child window you're trying to create.

The syntax is:

''fnReadScreenSize(&Rows,&Cols;Window)''

*Rows & Cols - returns the screen size in rows and columns.
*Window - the window to interrogate. If not given, assumes [[Open_Window#Comments_and_Examples|Window 0]].

==== fnBuildProcFile ====
This function builds a proc file to be executed later. This function and the next simplify the process of executing code in a proc file. It can even be used to spawn a new session of BR.

To use it, call fnBuildProcFile one or more times and specify some lines of code to execute.

''fnBuildProcFile(Command$*255)''

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnRunProcFile ====

This function spawns a new copy of BR and in it, runs the proc file that you've previously built using fnBuildProcFile (above).

'' fnRunProcFile(;NoWait) ''

The optional parameter "NoWait" causes the other session to spawn and run in a new thread. If you don't specify NoWait, the current session pauses and waits for the other session to close before proceeding.

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnLog & fnErrLog ====
These next two functions are functions to aid in logging. When you call either of these two functions, you give them a string that you wish to log. They will open the FileIO Log File and add a record to the end of it containing some user information such as login_name and session$, and the string that you specified. FnErrLog does the same thing as fnLog except it also logs the Error Number and the Line.

The syntax is:

''FnLog(string$)''

*String$ - the Log Message

''FnErrLog(String$)''

*String$ - the Log Message

==== fnLogArray ====

This function logs the given arrays to the log file, logging each field in the arrays. Its useful for recording, for example, an entire data record that is about to be written to a data file.

The syntax is:
''fnLogarray(mat F$,mat f;Message$*512,CallingProgram$*255)''
The first two parameters, of course, are the array to log. The third parameter is an optional message to be recorded along with the array, and the fourth optional parameter is the CallingProgram$ to save in the log along with the message. (The CallingProgram$ parameter can usually be passed as the system function Program$)

==== fnSetLogChanges ====
This function works in conjunction with the next function, and they're for recording just what changed in a data file. When the file is read, you call fnSetLogChanges and record the "before" picture of the file record.

After changes have been made and saved back to disk, you can call fnLogChanges below to record the actual changes.

The syntax is:
''fnSetLogChanges(mat F$,mat F)''

==== fnLogChanges ====
This function is the other half of the function above. It compares the given arrays with the ones set previously in the above function and checks for changes. Then it generates a log message recording information about just the items that changed.

The syntax is:
''fnLogChanges(mat F$,mat F;Message$*1024,CallingProgram$*255,Layout$)''

You need to pass in the same two arrays as before, but this time the modified versions of them.

You can also optionally pass a 1024 byte log message to record with the log entry.

CallingProgram$ again should be passed as the system internal function Program$.

The final parameter allows the passing of a Layout$. If you pass a Layout$, that layout is read and the subscripts are used when making the log message of changes, so that its easier to read. If you pass a layout, it will identify the changed fields by name. If you don't it will identify those fields by relative position number.

==== fnViewLogFile ====
All of the above functions store the information by default into a BR internal file defined in the filelay\logfile layout.

The fnViewLog function uses fnShowData to call the Data Crawler to display the FileIO Log File in a searchable listview.

''fnViewLogFile(;ShowQuit,ShowColumns,ShowExport)''

*ShowQuit - Show a quit button on the UI (if off, ESC will quit).
*ShowColumns - Include a button to allow the user to select which columns to view.
*ShowExport - Include a button to export the log file to CSV.

==== fnReadLockedUsers ====

This function returns a list of all users using the locked data file.

''fnReadLockedUsers(mat Users$)''

*mat Users$ - the list of users is returned here

==== fnDisplayLength ====
This function calculates the display length of a field based on its form spec.

''fnDisplayLength(Spec$)''

*Spec - the Form Spec to return the display length of.

==== fnLength ====
This function calculates the length on disk of a field based on its form spec.

''fnLength(Spec$)''

*Spec$ - the Form Spec to return the length of.

==== fnStandardTime$ ====
Converts Military Time to Standard Time. Returns Standard Time$

''fnStandardTime$(MilitaryTime$;Seconds)''

*MilitaryTime$ - Time in 24 hr format.

==== fnMilitaryTime$ ====
''fnMilitaryTime$(StandardTime$;Seconds)''

*StandardTime$ - Time in AM/PM Format

==== fnCalculateHours ====
Calculates the difference between 2 specified times.

''fnCalculateHours(TimeIn$,TOut$,DaysIN,DaysOut)''

*TimeIn$ - From Time
*TimeOut$ - To Time
*DaysIn - Days Start
*DaysOut - Days End

==== fnBuildTime$ ====
Builds a time in the format used by the above functions.

''fnBuildTime$(H,M,S,P;Military,Seconds)''

*H - Hours
*M - Minutes
*S - Seconds
*P - Boolean indicating AM/PM - 0 is AM, 1 is PM
*Military - Flag indicating weather desired result is in Military Time or not
*Seconds - Flag indicating weather to count seconds or ignore them. (1 means count seconds)

==== fnParseTime ====
Takes a time and pulls out the values

''fnParseTime(T$,&H,&M,&S,&P)''

*T$ - the time to parse
*H - Return value for Hours
*M - Return value for Minutes
*S - Return value for Seconds
*P - Return Value for AM/PM

== FileIO fnSettings (Global Settings Code) ==

The FileIO library can be made to implement certain policies across the board. These are established by creating a file called fileio.ini and typing statements like the following into it. This file is "PROCed", so you don't want to put line numbers in it.

Anything you don't specify in fileio.ini will take its default value, shown below. So you only need to specify the items that you want to be different.

Note, for the boolean settings below, 1 denotes TRUE and 0 denotes FALSE.

let EnforceDupkeys=1 ! Enforce that key number 1 is unique key
let Defaultfilelayoutpath$="filelay\" ! Path To Your File Layouts
let Promptonfilecreate=1 ! Ask User Before Creating New Files
let Createlogfile=0 ! Use Logging
let StartFileNumber=1 ! Set above 300 to avoid conflicts with legacy programs.
let CheckIndex=0 ! Automatically Verify Indexes (slow)
let CompressColumns=0 ! Shrink or Expand Columns in Data Crawler by Default
let MaxColWidth=20 ! Max Default Column Width in Data Crawler
let LogLibrary$="" ! Defaut Log Library, defaults to None
let LogLayout$="" ! Log file layout, defaults to Internal File
let AnimateDatacrawler=1 ! Use ScreenIO Animation for Datacrawler
let TemplatePath$="filelay\template\" ! Default Template Path
let IgnoreLayouts$="" ! List any Ignore Layouts here.
let CloseFileSimple=0 ! Use simple comparison for fnCloseFile

==== EnforceDupkeys ====

Turn on the EnforceDupkeys option to force that the first key listed in your file layouts is a unique key. FileIO will generate the standard BR error for Dupkeys when attempting to create indexes if it is not unique.

==== DefaultFileLayoutPath$ ====

Use the DefaultFileLayoutPath option to specify the path from your programs to your file layout folder. The default is "filelay\". Use this setting if you want to place your file layouts in another folder from the default.

==== PromptOnFileCreate ====

Use the PromptOnFileCreate setting to cause FileIO to display a message box whenever it is attempting to create a new file. This happens during the automatic update procedure, as well as during any attempt to access a file that does not exist. This setting should be turned off in your live system, and only turned on for development purposes. If you use the message box to cancel creating of the new file, then the file is not created, and fileIO or your application will most likely give an error when you attempt to actually access the new file.

It can be useful during development to make sure that you don't accidentally create the wrong files, due to an incorrectly specified path or a typeo in the filename in the layout file. However, in a live system, these things have already been tested, and you generally want the default behavior, because you don't want your users to have the ability to cancel the normal operation of FileIO.

==== CreateLogFile ====

Use this option to specify weather or not to use the FileIO log file. If it is turned on, a log file called FileIO.log in the current directory is created with entries listing all attempts to open a file, automatically update one, or automatically update your indexes.

==== StartFileNumber ====

Use this option to set the starting file number that the fnGetFileNumber and the fnOpen functions use to search for available file numbers. This is so that if you have certian reserved file numbers in your code, you can make sure that FileIO will not use those reserved file numbers, causing a conflict with your already existing programs. The default is 1, which is fine if your software does not have any reserved file numbers.

The allowable BR file numbers are 1-200 and 300-999.

==== CheckIndex ====

This function is used for Partial FileIO Implementations. If all of your software uses FileIO then all of your indexes are kept automatically up to date by the FileIO library and BR's internal file processing systems. However, if some of your programs do not use FileIO, and you use the FileIO library to add a new index file that those other programs do not know about, then its possible for the additional index file to become out of date when the master file is updated by your other programs.

Use this setting to cause FileIO to check the DateTime stamp on all your index files when opening a new file, and automatically update any indexes that may have potentially gotten out of date from other programs.

This option slows down the processing of the fnOpen function, particularly when running under client server over the internet. If you know that every program in your application suite uses FileIO, and that any programs that do not use FileIO still properly update all the indexes that your data file uses, then you can safely leave this setting turned off, and optimize your performance when opening several files using the fileIO system.

==== CompressColumns ====
This instructs the datacrawler to use smaller widths for small columns. If CompressColumns is false, the data crawler will make the column the width of the field or the width of the caption, whichever is wider. If CompressColumns is true, it will use the width of the field, not the caption.

==== MaxColWidth ====
This limits the column width to a set amount. This is applied after CompressColumns above.

==== LogLibrary$ ====
If a library is specified here, then fileio looks for a BR library with the specified name, and attempts to call a library function in it called fnFileIOLog that. This function should expect six parameters, which are Logstring$, Login_Name$, Session$, Days of Date$, Time$, and CallingProgram$, if LogLayout is also nonblank.

If you specify a LogLibrary and LogLayout is blank, then it calls your function giving it only 1 parameter.

It will call your function '''''instead of''''' the normal log file. Use this to implement your own logging functions however you want.

==== LogLayout$ ====
Use this setting to specify an alternate file layout for an alternate file to do the logging in. Base the file layout for this file on the logfile we supply for you in the filelay folder. It should have at least those fields, which our log routine will automatically populate, but you can add other fields if you want (though you will need to manage them yourself).

If you don't specify LogLayout, the default filelay\logfile will be used. This will allow you to also use the fnViewLogFile function to access it.

==== AnimateDataCrawler ====
The sister library [[ScreenIO]] has a feature that allows you to use an animation of a clock in your loading screens in your own programs. If you have [[ScreenIO]] then FileIO will automatically detect it and use it to display a loading animation while the data in the data crawler loads.

Set AnimateDataCrawler to false (0) in your fileio.ini file to bypass the animations if you do have screenio but don't want to see the animations anyway.

==== TemplatePath$ ====
This setting points to the folder that contains the code templates used by the Generate Code button on the main page of the Data Crawler.

==== IgnoreLayouts$ ====
This is a comma delimited list of all layouts that you wish to suppress from appearing on the main page of the data crawler. You can still access these layouts with your code, but they won't be listed in the data crawler for you to access.

Whatever you're using for a log layout, is automatically added to this list.
==== CloseFileSimple ====
The fnCloseFile function closes all the individual handles to a data file that was opened for output using multiple keys.

For BR 4.18 and higher, we support a better algorithm for detecting which files are matches for a given opened file number.

Set CloseFileSimple to true (1) to force it to check the old way.

== FileIO Add-on Packages ==

Many FileIO Add-on packages are currently in the works.

=== ScreenIO Library ===

The [[ScreenIO Library]] is a sister library to the FileIO library. The ScreenIO library requires the FileIO library in order to run.

The ScreenIO library is a complete Rapid Application Design tool that enables you to implement custom screen functions anywhere in your exiting programs.

If you call the ScreenIO Library as a function library, you call a function called fnFM and tell it which screen you wish to use. The ScreenIO library loads your user interface, loads your data files, and preforms all the file maintenance operations you have designed into your screens.

You can find out the latest information about the ScreenIO library in the ScreenIO page.

=== Audit BR ===

The [[AuditBR|Audit BR]] developer tool makes a backup copy of your file layouts. Then you run some code you're trying to test, and finally, run Audit BR again, to get a report showing all the changes to any of your data files automatically.

AuditBR is now included directly in FileIO. To use it, select the layout from the list of layouts in the Datacrawler and press the "Compare" button.

== What’s New (also described above) ==
=== 2018 ===
*Support for dates in any storage formats on disk (v2.48)

=== 2015 ===
*Added Rec to display for fnShowData
*Added FormStatement$ for debugging of form statements inside fileio
*Added mat BadRead$ for debugging of 726 errors when making new layouts
*Fixed a bug causing crash when logging things from long program folders
*fnClientEnv$ - reads a Windows Environment variable on the client using the command shell
*fnAskCombo$ - added an optional parameter to set default selection.

=== 2010 - 2014 ===
*FileIO now caches your file layouts in memory to make it much faster then before when opening the same data file in multiple programs.
*Generate Layout Wizard
*fnShowData
*Improved Logging
*fnViewLogFile
*Import/Export
*Import/Export by Function
*Many other speed increases
*if ScreenIO is present, Datacrawler uses the animation routines
*fnBuildProcFile & fnRunProcFile
*fnGenerateLayout & fnWriteLayout
*fnReadForm$
*fnReadFormAndSubs
*fnGetFileDateTime$
*fnReadLayoutPath$
*fnSortKeys
*fnSetLogChanges
*fnLogChanges
*fnLogArray
*fnReadScreenSize
*fnEmpty
*fnEmptyS
*Many other useful functions that were added to the documentation at earlier dates.

=== Spring 2009 ===

'''''New Functions:'''''

The FileIO Library has been updated in Spring 2009 to provide several new functions:

*fnReadRecordWhere
*fnKey$
*fnBuildKey$
*fnReadUnopenedDescription$
*fnUpdateFile
*fnDisplayLength
*fnLength
*fnReadLayoutHeader
*fnReadEntireLayout

'''''Speed Increases:'''''

Thanks to the BR [[Profiler]], we have increased the speed of FileIO fnOpen function by ten times when running over a LAN and by 100 times when running over the internet using Client Server.

In order to get the new Speed Upgrades, you will need to make sure that you use the latest copy of the [[#fnOpen_Function|fnOpen]] function in each one of your programs that use FileIO.

'''''Network FileIO:'''''
This version of FileIO has been optimized to work better in network situations.

'''''FnSettings: '''''
There are more configuration options in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine.

'''''Automatic Update Speed Fix:'''''
The automatic update proceedure has been made to run more then 100 times faster then before according to our benchmarking tests.

=== Fall 2008 ===
'''''DataCrawler Grid:'''''

By popular request we added a read/write version to the data crawler. This version works exactly the same as the datacrawler did before but it displays all the contents of your data files in a grid instead of a listview.

When you run the fileIO library as a program, it launches a tool known as the [[#DataCrawler|DataCrawler]]. The DataCrawler shows a listview displaying all your layout files in it. If you select one, it builds another listview with all the data in your selected data file.

If you are looking at the first list of all your file layouts, and you press F5, a grid will be build displaying all the data in your data files. You can change any of the records you like, and when you're done, your changes will be saved to the data file. Additionally, you can Add or Delete records using the buttons at the bottom. Any changes you make are not written to the disk until you click the "Save" button. If you press ESC (Cancel) the grid is closed and all changes you made sinse the last save are lost.

This tool is for programmers only. Do not give your end users access to the DataCrawler.

Use the DataCrawler at your own risk. Gabriel Bakker and Sage AX are not responsible for any harm that comes to your data files through the use of this or any other tools we offer.

The DataCrawler is not designed to be used to maintain your data files. It can be used carefully to correct small things in your data files.

'''''Support for Nonstandard Paths:'''''

Many BR Vendors keep different versions of the same data files in different locations. For example, sometimes a BR vendor will use a different Data folder to represent data for different Warehouses, or Customers. In cases like this it is necessary for your programs to specify the path to your data files. They may do so by specifying the optional "PATH" parameter to your data files. See the section [[#fnOpenFile]] for more information.

'''''Support for Nonstandard Layout Files Path:'''''

Old versions of the fileIO library required you to place all your file layouts in a subfolder of your program directory called "filelay". We have now changed the Fileio library to allow you to place your file layouts any place you want. The only requirement is that they are all together in one folder by themselves.

If you use a nonstandard path in the fileIO library, it is necessary to make a change to the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code in your copy of fileio.br.

'''''Prompt on Create:'''''

The FileIO library automatically creates any data files that it can't find. This was done to make it easier to deploy your finished programs - if you had any empty data files you could omit them from the packages and they would be created when they were needed, on the fly.

The current version of the FileIO library contains the same ability. However, it prompts you before creating any data files. This helps to avoid bugs that happen from incorrectly specifying the path to your data files.

However, if you do intend for your data files to be autocreated, then you probably don't want your end users to modify them. Therefore, you can use the PromptOnCreate setting in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code to specify. If this value is set to true, then the fileIO library will prompt you whenever it attempts to Autocreate a data file. If it is set to false, then the fileIO library will create the data files without prompting you, like it always did before.

'''''fnSettings:'''''

The newest version of the FileIO library supports some features that require you to specify Global Settings values. These are done by modifying the contents of the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine at the beginning of the fileIO library.

=== Fall 2006 ===
Many improvements have been made in the FileIO library over the summer. This section is intended to acquaint you with the highlights of those changes. Most of these improvements were built from ideas generated during the discussion at the April conference.

'''''Intermixed String and Numeric Specs:'''''
The File Library has been expanded to allow the reading of data files that contain mixed string and numeric specs. This is to aid those of you who are planning on implementing the FileIO Library on existing data files which may not be organized with strings first and numbers second.

The central idea of the FileIO Library is based upon the reading of your data files into a String and Numeric array. This will enable you to refer to the fields in your file by using a named subscript, saying F$(FM_NAME) to refer, for example, to the farm file’s name field. The advantage to this is that when you change the file layout, all your existing programs will not have to be modified, because they will only be looking at F$(FM_NAME). If the name field changes from the third string field to the fourth, the value of FM_NAME will also change, and you won’t have to worry about updating your data files.

However, in order to support the reading of a data file with intermixed string and numeric specs, the generated form statement will actually calculate the position of any fields that are not in order, so that the file read statement will still return all string fields first (into your string array) and the numeric fields second (into your numeric array). You do not need to worry about this; the library does it for you. All you have to do is read your file and use the data values.

The only thing that is required is making sure that all your string subscript names end with a “$”. This will tell the library that they are strings. Thank you, George, for this suggestion.

'''''Versioning / Automatic Updates:'''''
The file layouts have been expanded to contain a version number. This version number will be used to determine when a file needs to be updated. The version number is the third parameter in the file layout.

Any time you wish to change your file layouts, simply increment this version number. Each time the library attempts to open a data file, the file’s version is checked and compared with the version in the file layout. If the file layout has been changed (if the version in the file layout is greater then the version in the file) then the file will be updated to the latest version. Depending on the file size this may take a couple of moments. A simple progress bar will be displayed on screen while this is happening. The progress bar will be displayed in its own window, so it should not affect anything your programs may have had on screen.

The library uses the following procedure for updating a file. First, the file is copied to a backup file (prefixed by the letter ‘o’ for old). So color.dat would become ocolor.dat, and color.key would become ocolor.key. Then the new file is created and marked with the proper version number. (color.dat, color.key). The old file is opened in read-only mode, and the new file is opened for OutIn. The update routine actually reads through the old file layout, and one record at a time creates a new record, using the new file layout, with the same data, saving it to the new data file.

When it is done upgrading, the progress bar window is closed, and the file is reopened in the fashion you described in your call to fnOpen, and flow returns to your program as though nothing unusual has happened.

If an error occurs during processing, the routine will do what it can to roll your data files back to the previous version, but please make frequent backups of your data files anyway, just to be safe.

'''''Error Checking – If there is a mistake in the file layout:'''''
The routine attempts to discover the cause of the error in the case that one is encountered due to a missing file, a file sharing violation, or an invalid or corrupt file layout. If this should happen, the program is paused, and a text message is printed out explaining the most likely source for the error, including what part of the file layout, if any, may have caused the error.

You may then examine the printed text, and the contents of the BR system variables ERR and LINE to determine the problem. If you type “GO”, the next line will be execute “system”, ending your program.

If the file was in the middle of an upgrade when the error happened, it will be automatically rolled back to the previous version, so that when you fix the problem and try to run your program again, the file will again attempt to update from the beginning, and you won’t have to worry about corrupted data.

However, please backup your data before upgrading your data files anyway, just to be safe.

'''''Implementation of Keys / Creation of New Data Files:'''''
The library has been expanded to automatically create all new data files, and to automatically update any existing files. This means that in the file layout header, two new fields that were previously ignored are no longer ignored. The RECL value that you specify in your file layout will be used, along with the description/definition of your keys file. When you open a new file (or update an existing one), the library will calculate the proper kps and kln by evaluating the key description. This key description must match up with subscript values from the data elements in your file, and more then one may be specified, but they must be separated with slashes (/). If I wanted my Farm File to be keyed based on CODE and NAME, the proper key description would be:

farm.key, CODE/NAME

The library will then look up the position and length on disk of the CODE and NAME fields and put them together to create the proper keys during an update or creation of a new file.

'''''DataCrawler:'''''
Perhaps the most exciting new addition to the library is the addition of a programming tool I like to call a DataCrawler. If you run the FileIO Library directly as a program, instead of using it as a library, it will function as a DataCrawler. The DataCrawler requires a New Gui version of BR, as it requires a ListView to be able to properly and easily display the data in your files.

If you run it in an older version of BR you will get a message, telling you to run it in a newer copy. If you run it in a New Gui version of BR with CONFIG GUI OFF, then GUI will be turned temporarily on for the use of the DataCrawler and then turned off again when you are finished. If you run it in a New Gui version of BR with GUI ON, it will just run normally.

When you run the DataCrawler, first you will see a ListView displaying every file layout it can find in the filelay folder. If you select a file, the DataCrawler will open a large ListView with as many columns as there are fields in the file. The Column Headings will come from the element descriptions in your data files, and the column widths will come from the displayed width of the fields. There will be a row for every record in your data file, and you can resize the column widths, and scroll around the data file to view the raw data of your BR data files on disk.

If you are dealing with a particularly enormous data file (50,000+ records) it can take a moment to populate the ListView with the data in your data file. You may hit ESC to stop loading if you like, and view only the already loaded records.

If you would like to look up a particular record (based only upon the primary key for the data file), you may press F4. This will give you a window which asks you to input the key or partial key. When you press enter, the file will be reloaded, starting at the key you specified and continuing on to the end of the file, or until you press ESC. The records you are looking for should appear at the top of the ListView.

To reset the ListView and look at the contents of the entire file again, simply press F4, and enter a blank (“”) key.

Finally, as with any ListView, you may resort your data by clicking on any of the column headings. Then you can use the slider bar at the right to scroll down to the record you desire.

This is a programming tool and is not designed to be used by an end user. This tool will open your file in read-only mode. It will not allow you to modify the data; I leave that as an exercise for the reader. However, it will update any datafiles you view to the latest version (if they need to be updated) when it opens them, just as any other program that uses the library will do.

== Appendix (Examples)==

=== Example.br ===
00010 ! example.br - This program is an example of for the data reading simplification
00020 ! Copyright April 2006 by Gabriel Bakker
00030 ! Distributed open source as a Christmas gift to brag members
00040 !
00100 execute "config gui off"
01020 DIM form$(1)*255
01030 DIM color$(1)*255,color(1)
01040 DIM colorcat$(1)*255,colorcat(1)
02020 library "fileio": fnopenfile, fnreaddescription$
04000 !
04010 Openfiles: ! Open your files here
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)
06000 ! gosub WriteFiles ! If you want to test this line, make sure to drop flag from 4030
07000 !
07010 MainBit: ! This'un here's tha Main Bit
07030 RESTORE #ColorFile:
07100 ReadNextcolor: ! Read next record
07120 read #ColorFile, using form$(ColorFile) : mat Color$, mat Color eof EndReadColor
07180 PRINT Color$(co_name)&" ("&Color$(co_html)&") is a member of the '";
07190 PRINT trim$(fnReadDescription$(ColorcatFile,cc_Name,Color$(co_category),mat Colorcat$,mat Colorcat,mat form$))&"' category."
07290 goto ReadNextColor
07300 EndReadcolor: ! Finished with Color File
08000 STOP
25000 !
25010 WriteFiles: ! Uncalled routine to demonstrate writing files
25105 let color$(co_code)="GD" !:
let color$(co_Name)="Gold" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFD700"
25110 write #colorfile, using form$(colorfile): mat color$, mat color
25115 let color$(co_code)="LV" !:
let color$(co_Name)="Lavender" !:
let color$(co_Category)="BL" !:
let color$(co_html)="E6E6FA"
25120 write #colorfile, using form$(colorfile): mat color$, mat color
25125 let color$(co_Code)="OR" !:
let color$(co_Name)="Orange" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFA500"
25130 write #colorfile, using form$(colorfile): mat color$, mat color
25205 let colorcat$(cc_Code)="YL" !:
let colorcat$(cc_Name)="Yellows" !:
let colorcat$(cc_html)="FFFF00"
25210 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25215 let colorcat$(cc_Code)="BL" !:
let colorcat$(cc_Name)="Blues" !:
let colorcat$(cc_html)="0000FF"
25220 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25300 return
40000 !
40010 Open: ! ***** Function to call library openfile and proc subs
40020 def fnOpen(FILENAME$, MAT F$, MAT F, MAT FORM$;INPUTONLY,KEYNUM,___,INDEX)
40025 dim _FileIOSubs$(1)*50
40030 let fnopen=fnopenfile(FILENAME$, MAT F$, MAT F, MAT FORM$,INPUTONLY,KEYNUM,MAT _FileIOSubs$)
40040 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
40090 fnend
50000 !
60000 Ignore: Continue

Color File Layout
color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

ColorCat File Layout
colorcat.dat, CC_, 0
colorcat.key, CODE
recl=127
===================================================
CODE$, Category Code, C 6
NAME$, English Name for Color, V 30
HTML$, HTML Code for the Color, C 6

Example Layout showing multiple keys (price)
price.dat, PR_, 0
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2

[[Category:Utilities_Third_Party]]

FileIO Library

2024-09-11T05:32:46Z

Gordon.dye: /* Method of Operation */

The '''FileIO''' Library began as a project to find a way to reduce the headache associated with making changes to data files. In my experiences working for [[BRC]], I had to make a change to the commun file, a data file that stores information about communication with EDI VANs. I added some new fields, and removed a couple of old fields, and then I began searching through the BRC program suite to find and modify each program that referenced this data file in order to update it with the proper new form statement. This task quickly became daunting as I noticed that out of BRC’s program suite of over 600 programs, more than one third of them referenced the commun file. With 223 programs to modify, the task was given up as hopeless and tabled indefinitely.

I am happy to announce that we have solved this problem. When I have to make a change to a data file layout for my customers today, I can complete the task in under 1 minute, and not a single program needs to be changed in order to continue working with the new file layout. In fact, I don’t even have to update my customer’s data files, as the FileIO library takes care of this for me as well.

The trick is to define your file layouts in an ASCII text file layout file that I will tell you about in a minute. The FileIO Library will actually parse through your file layouts, and it will instruct your programs how to read the data file, so that you don’t have to. It will also automatically detect when you make changes to the file layout, and it will update your customer’s data files on the fly to make sure they have the latest version. Finally, it even contains a DataCrawler that you can use to examine the contents of any of your BR data files in a raw format.

For more information about the FileIO Library visit the [http://www.sageax.com/products/fileio-library/ Sage AX Website]

To download the latest copy of FileIO, click [http://www.sageax.com/downloads/FileIO.zip here.]

== Method of Operation ==
The file IO library parses a formatted text file layout and uses this information to structure the opening and initializing of the reading of a file “object”. The word object here is used to refer to all the data in a given record layout in one of your files. This library is easy to use, and provided you follow some simple standards, it will simplify your life immensely.

Your programs will need to define one array for all [[Form|file layout form statements]] and add a snippet of code (given below) to the program for interfacing with with the library. For each file you will need to define a couple of arrays and use the library to open them. From that point on access to data is simple and direct.

=== File Object Arrays ===

First, in your program you must create two arrays to store the file information. If we are dealing with the Color File these would be MAT COLOR$ and MAT COLOR. One will store all the string information about a color, and the other will store all the numeric data. Our working example will involve two files: a Color File and a Color Category File. You should dimension these to:

01030 DIM color$(1)*1000,color(1)
01040 DIM colorcat$(1)*1000,colorcat(1)

We're dimensioning the string arrays to 1000. This is the length of one field in the color file. It needs to be at least as big as the largest string field in the data file.

However, it is recommended to make sure the length is long enough to handle any field you might eventually add to the file at any point in the future. BR supports multi-line textboxes, so I sometimes add long memo fields to my data files that might be 400 or 800 or even 1000 characters long, therefore 1000 is the length I use now in all my new development.

But anything will work as long as its long enough to handle the largest data field in your file.

=== Forms Array ===

Your programs will need a string variable array to store the form statements associated with reading files. This form statements array will be dynamically generated or expanded whenever the a file is opened. It will say:

01234 DIM form$(1)*255

This form statement will be compiled by the FileIO open statement. BR limits all form statements to 255 bytes, so 255 is sufficient to hold the compiled Forms$ statements.

=== Library Linkage ===

You will also need the library statement:

02020 library "fileio.br": fnopenfile, fnreaddescription$

=== fnOpen Function ===

Now, add a snippet of code to interface with the library.

Because BR libraries do not share global variables with the programs they are called from, we will need to execute a proc file whenever we open a file to set the names of all our variables after we return. Add the following snippet of code into your program. It will create an FnOpen function that calls the library and runs the proc file. The $$$ at the end of the procfile name tells the procfile to self-destruct after execution. Since this procfile is used simply to return variable information back from the library to the main program, we don’t need it sitting around collecting dust.

99010 OPEN: ! ***** Function To Call Library Openfile And Proc Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
99030 dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
99050 if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
99060 fnend

Or, for those with [[Lexi]]:
OPEN: ! ***** Function To Call Library Openfile And Proc Subs
def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths,Supress_Prompt,Ignore_Errors,Suppress_Log,___,Index)
dim _FileIOSubs$(1)*800, _Loadedsubs$(1)*80
let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$, Supress_Prompt,Ignore_Errors,Program$,Suppress_Log)
if Srch(_Loadedsubs$,Uprc$(Filename$))<=0 then : mat _Loadedsubs$(Udim(_Loadedsubs$)+1) : let _Loadedsubs$(Udim(_Loadedsubs$))=Uprc$(Filename$) : for Index=1 to Udim(Mat _Fileiosubs$) : execute (_Fileiosubs$(Index)) : next Index
fnend

=== Using FileIO in Your Programs ===
Now you are ready to process files. 
'''''You simply open the files by saying:'''''

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

'''''read each file as follows:'''''

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
'''''and access the data:'''''

30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name)

=== How it Works ===
These statements tell the File Library to look in the filelay folder to find the file layout for the Color File, and read it to find out what the Color File looks like. Then Open the Color File, and set MAT COLOR$ and MAT COLOR to the correct number of elements to hold an entire color record. Finally, it will define several variables that we can use as pointers (subscripts) into these arrays to access the data we after reading it, and it will place the file handle into a variable called colorfile.

The second open above will do the same thing to the color category file, except the 1 parameter tells the function to open readonly. The subscripts array will be executed, creating the subscripts in memory, and the pointers (subscripts) will be set in the calling program. So, if I had a file layout such as the following:

color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

Then the functions would do the same thing as the following individual lines of code (assuming the next available file handle was 5):

DIM FORM$(5)*255
DIM COLOR$(9)*1023, COLOR(1)
OPEN #5: “Name=color.dat, kfname=color.key”,internal,outin,keyed
LET FORM$(5)=”form C 6,V 30,V 6,C 6”
LET FORM$(5)=CFORM$(FORM$(5))
LET COLORFILE=5
CO_CODE=1
CO_NAME=2
CO_CATEGORY=3
CO_HTML=4

The data is used by referencing the file array, with the subscript name, so the color’s description becomes color$(co_Name).

In the old days, if we wanted to change the file layout of our file, all of the programs that used that file would have to be changed one at a time to use the new file layout. Also, if the order of the fields changed, then all the programs would have to also be changed to use the new fields.

But now, using this function, we can change the file layout all we want. If we later want to insert a field into the file layout before color name, I won’t have to look at this program again; this program will just work fine, because the library maps the subscripts to the actual fields.

Also, the code is easier to read and maintain.

=== Example ===
The whole thing looks like this:

01025 ! Dimension the Arrays
01030 DIM color$(1)*1023,color(1)
01040 DIM colorcat$(1)*1023,colorcat(1)
01050 DIM form$(1)*255
02000 !
02020 library "fileio.br": fnopenfile, fnreaddescription$
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$) ! Open the file
05000 !
30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore ! Read the file
30180 LET ColorCode$=color$(co_Code) !:
LET ColorName$=color$(co_Name) ! Use the data by referincing it in the file arrays
80000 !
90000 ! Every program using fileio needs the following code
99010 OPEN: ! ***** Function To Call Library Openfile And Generate Subs
99020 def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, Dont_Sort_Subs, Path$*255, Mat Descr$, Mat Field_Widths)
99030 dim _FileIOSubs$(1)*800
99040 let Fnopen=Fnopenfile(Filename$, Mat F$, Mat F, Mat Form$, Inputonly, Keynum, Dont_Sort_Subs, Path$, Mat Descr$, Mat Field_Widths, Mat _FileIOSubs$)
99050 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
99060 fnend

== File Layouts ==
Now lets inspect the anatomy of a properly formatted file layout. These should be placed in a subdirectory called filelay.

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...
<hr>
price.dat, PR_, 1

The first line contains the name of the Farm File, a unique string to prefix all of your subscript pointers, and the file version number. The subscript value is to ensure that the program knows the difference between the Farm File’s Farm Code, and the Route File’s Route Code. (One will be RT_CODE and the other is FM_CODE). These are separated by a comma. Spacing does not matter, so adjust your spacing so that it looks nice.

The Version number is used to determine when the data has changed, and an update needs to be made to your data file. Your file layouts should all start at version 0, and each time you want to make a change, you may increment this value by 1.

Each time you open a file with the FILEIO library, it reads the file version number of the file on disk (using the BR version() function), and then it compares it to the version number in your file layout. If your file layout has a higher version number then your existing data file, then the library opens the backup of the file layout for the version of the data file that exists on disk. It makes a backup copy of the existing data file, and creates a new file with the proper version number. Then it reads your records one at a time, and copies all the data from the old file into the new file one field at a time. If a field is dropped from the file layout, that data gets lost. If fields are rearranged, the data is copied and saved in the new file in the new positions. If a new field is added, it starts out blank (or 0).

If you look in the filelay folder, you will notice a version folder. This contains several files ending with a number. For example you may see a color.0, and a color.1 file.

If you run the fnopen function and it can not find your data file (usually because this is a new file and it hasn’t been created yet), ''the library will automatically create your file,'' based on the information you give in the first part of the file layout.

Also, whenever you make changes to your file layout, the function library will automatically update the data files on disk for you. It does this by renaming the old file, creating a new one with the new version number, and then copying the data from the old one to the new one a record at a time.

Any time it creates a file, or updates the file on disk, it creates a backup of the file ''layout''. The first time you run a program that tries to read your new data file, it will create the data file for you and make a backup of the layout, and if the number in your file layout is 0, then it will create, for example, a filelay\version\price.0 file, a backup of your file layout that the library uses to figure out what has changed the next time you try to update the file.

If you wish to make any changes to this data file, first you increment the version number, (in this case make the 0 into a 1). Then change the file layout all you want. You may rearrange fields, add new fields, add or remove keys, or change the record length.

The only step necessary for having your data files updated is to increment the version number every time you make a change to the file layout.

You may make any changes you like to the file layouts, but do not change the names of your existing subscripts. If you change the subscript name, not only will all the programs that reference that subscript be broken, but additionally, the routine will not understand that you are changing the name. It will think you are dropping the old field and adding a new field and any data stored in this location will be lost when the file is updated.

price.key, FARM

The second line contains the name of the first key, and a definition telling what the key is based on. These are separated by a comma. The key definition is made up of each of the subscript names in this file that form the keyfields for the file. When the library is called to open a file, if the file does not exist, or if it needs to be updated, a new one will be created. The function will read these subscript names that form your key definitions, and it will calculate the proper key position (KPS=) and length (KLN=) values. Then the create routine will use this information with the Index command to create the new key files.

price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
price.ky4, DESCRIPTION-U/COST
recl=127

Notice that the third key is based on three different fields. These are separated by a “/”. It is important that you use a “/” to separate your keys when you are building a key out of more then one field, because the function uses this “/” to help it make the proper BR syntax for defining complex key fields.

Also, note the "-U" at the end of the fieldname in the 4th key. This indicates that the "Description" part of that key is case insensitive. This translates to using the "U" on part of your key spec in Business Rules.

The file can have as many keys as you want. The function will keep parsing key file names until it reaches the next part of the layout. It opens any OutIn files with all keys so that any changes you may make to the data stored on disk will be properly reflected in all the key files.

The optional RECL= Parameter is read and used whenever a new file is created or an old one is updated. If it is not specified, the record length is calculated from the fields in the layout.

===================================================

The next line in the file is skipped by the parsing routine, and its purpose is to make the file layouts more readable to a programmer.

 
FARM$, Farm Code (or blank), C 4

Following the file and key structure, the fields are defined. There are three parameters on each field definition line, and you make one line for each field in your file layout. The first parameter is the subscript name that you will use in your program to refer to this data element. Place a $ at the end of the subscript name for all string elements. Don’t place anything at the end of the subscript name for numeric elements. Note that each of these names will be prefixed by the second parameter of the very first line of this layout.

The second parameter is the description. This description is for the benefit of the programmer, so when the programmer is reading the file layouts, (s)he can tell which field does what. The spaces are ignored, so you may include as many spaces as you wish to make the layout look good. It does seem like good general guidelines would be to limit your layout lines to 255 characters and your descriptions to 80.

The description is also used by the built in DataCrawler, a program that reads any of your data files and displays the entire contents in raw form in a listview. The Descriptions become the headings for each column in the listview.

Those descriptions are also used for the default captions for your fields if you use ScreenIO, a library for building GUI programs that itself builds off of fileio.

The third parameter is the form statement, which is pretty straightforward. Any items with a form statement of type “X” will be ignored, except that the length will still be used to calculate the position on disk of all remaining fields in the record. The library will take X fields into consideration when building the form statement, but not at any other time.

The fourth parameter is optionally a [[#Support for Dates|Disk Date Format]]. You can specify DATE(Julian) if you're storing your dates in Julian format on disk. Or you can specify DATE(cymd) or DATE(ymd) or DATE(mdy) or any other valid date spec here, and FileIO will treat this field like a date.

Your programs will still have to unpack it for you, fileio can't do that because fileio doesn't read the file for you.

However, the data crawler, the automatic updates, and screenIO, are all compatible with these dates specified in your file layout.

If the fourth parameter is anything other then DATE(format), then its treated as a comment and ignored.

The fifth and all later columns, if any, are treated as comments and ignored.

! default cost is normally zero
Comment line text must begin with an exclamation point, but it may be indented. Comment lines may appear anywhere (vertically) and are ignored. 
Blank lines are ignored as well.

#eof#
additional comments...
After the last field definition, an ''optional'' #eof# line may be specified, in which case any lines after that will be ignored.

 
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
! default cost is normally zero
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30
#eof#
additional comments...

And that’s all there is to it.

=== Support for Dates ===
As of V2.48, file layouts support dates in any storage formats on disk. Whether you store your dates in Julian or in YMD or MDY or any other format, specify so in the 4th column of your file layouts, using the FileIO Date Keyword. ex: DATE(Julian) or DATE(YMD) or any other valid BR Date Format.

[[File:Dates0.png]]

When this is specified, it enables the FileIO data exploration tool (Data Crawler) to display the dates in human readable format. This works for both Viewing, and for Editing.

The new Date functionality also supports the File Layout Upgrade facility, allowing you to change the format of your dates on disk and FileIO will handle it automatically, upgrading the field to use the new date format for you.

It works also for Exporting your data files to CSV, and is supported automatically in the FileIO functions that do those exports. It converts the dates on export to a standard format (Default: m/d/cy) that you can specify in your FileIO.Ini File.

And it extends ScreenIO's date features to all date fields, no matter what format they're stored in. (Previously, ScreenIO's advanced date features only worked for dates stored in Julian on disk.)

This update adds two new ini file options:
CODE: SELECT ALL
DateFormatExport$='m/d/cy' ! Format of Dates when Exporting to CSV
DateFormatDisplay$='m/d/cy' ! Format of Dates when displaying in Data Crawler

You can use these to specify your preferred Date format for Viewing/Editing, and your preferred Date format for Exporting.

Remember, you can see the full list of FileIO ini file options, by looking in the source code at the top of FileIO.

There is a new optional parameter for all layout reading functions, mat NDateSpec$ and mat SDateSpec$ which correspond with the other arrays, to let you know which fields are date fields, so that you can develop routines in your programs to automatically pack and unpack the dates.

Important Note: Using FileIO, the reading of the data file is still done directly in your programs. So this does not change how your existing programs work. It does not unpack the dates for you in your programs. You still have to do all that.

For this reason, upgrading to the new Date processing will not break any of your current code.

=== Debugging Tips ===

When you're making new layouts, a missing comma can cause FileIO to parse the layout wrong and give you errors. Here are a couple tips to help ensure your layouts are error free before using them in your programs.

*Use the Data Crawler to test your layout. The data crawler is the simplest way to test your new layout without writing any code. It opens it and accesses the file in a very simple and straight forward manor to help identify any errors in the layout that you might have.

*If you have trouble with the form statement, you can't see whats in it because FileIO uses CForm$ to compile your form statement to make your programs run faster. But here's a way to tell what the original form statement was that FileIO generated when it put the strings first and numbers last in your program: Open the file in the Data Crawler. When you get an error, type "Print FormStatement$" to see the original form statement.

This works even if your file is working fine. Any time the file is opened with the data crawler, you can press CTRL-A and then type PRINT FormStatement$ and it will print out the uncompiled form statement for the file.

== Utilities ==

Now that you have your file layouts defined, you have access to several powerful utilities right out of the box using Fileio. Additionally, several more utilities are available as [[#FileIO_Add-on_Packages|Add-Ons]], including our most popular development tool [[Screenio|ScreenIO]]. You can read more about them in their section below.

But for now, lets take a look at some of the wonderful free utilities that come built into Fileio.

Some of these utilities are accessible from your code via library functions, but the primary way you access any of them is by simply loading the FileIO Library and running it directly.

=== DataCrawler ===
The data crawler is the original utility of FileIO. This utility shows you first a list of all data files allowing you to select one.

Select a data file and press enter, and FileIO will then display a listview containing all the data in the data file. This list is sized based on the size of your main BR window (window 0) automatically to take up the full size available to it, so if you want to see more, try [[Open Window|opening window 0]] larger before running FileIO.

At the top of the window is a filter box, and you can type anything you want in there and click "Refresh" and it will reread the data file, shortening the list to show only those records that match (case insensitive) what you have typed.

If you have ScreenIO installed, then FileIO's data crawler will take advantage of the included Animation Engine in ScreenIO to animate a loading window while the listview is displaying. If you don't have ScreenIO then FileIO will simply load the listview.

If you don't want to wait for the entire file to load, press ESC to stop the load process.

If the file is empty, FileIO will display a message box letting you know.

This tool is very useful for sorting out data errors. It will allow you to look inside any data file you have a layout for and directly view the data there.

At the bottom of the Data Crawler are several buttons. There's a Jump button that repositions the file by a key you specify and then loads the list with the data from that key on down to the end of the file.

There is a "Columns" button which you can use to decide which columns should show up on the listview. Fewer columns means faster loading so sometimes for large files I press ESC immediately when the file first starts loading to cancel the load. Then I click "Columns" and check only the columns I want to see. Finally I press the "Refresh" button to trigger it to read the file again and this time it loads much faster then before.

Next you'll find an Export button which starts the process for exporting a file to CSV. You can read more on that in the next section. And next to that is a Quit button.

In this example, we loaded the file "Read Only" so it put everything in a listview. But there are times when its useful to fix data errors this way too, especially during development. So if you want to directly edit your data file, on the first page select the file you want to edit and instead of pressing "Enter" or clicking "View", this time press "F5". F5 is the secret Edit button that loads a data file into a grid instead.

You can use the grid to change records, delete them or add them, and in addition to the buttons listed above, it also has an "Import" button for importing a CSV file into this data file.

Any changes you make to the data file are not saved until you click the "Save" button (which also only appears when you're in Edit mode).

In the 01/2015 release of FileIO, each records rec # is displayed in the listview, to aid in debugging bad data problems.

==== Debugging Tip ====
Any time you're viewing a file layout in the Data Crawler, you can see the Uncompiled Form Statement by pressing CTRL-A to get to an ATTN prompt, and then entering the command:

print FormStatement$

and it will print out the original form statement.

==== Another Debugging Tip ====

The FileIO Datacrawler ignores records that it cannot read. This is to allow for data files that have multiple record layouts in one data file. You make a custom layout for each record type and the data crawler shows just the records that match that type in the file.

However that becomes a problem when you're making a layout to work with an existing data file. Error 726 indicates that something minor in the file layout doesn't match the data on the disk, but these errors are ignored so you might see either an empty data file, or a data file with some records missing. If that happens, you need to see the missing records in order to figure out what is wrong with your layout. '''''It's very important that you don't try to use a file layout that isn't quite working right. Make sure your layout works and can read every record of a file that it should read before using it.'''''

To see the records that could not be read in a file, run the data crawler on the layout, then press CTRL-A to get an ATTN prompt. From there, enter the command

print mat BadRead$

and it will print all the records that were ignored because the file layout didn't match them. It prints out the raw data from the file.

==== Function Access to use Data Crawler in your programs ====
You can use the data crawler in your own programs by using one of the following functions:
* [[#fnDataCrawler|fnDataCrawler]] - Open a Listview showing the data file
* [[#fnDataEdit|fnDataEdit]] - Display the data in an editable grid
* [[#fnShowData|fnShowData]] - This function does the same thing as the above two, but with many many more options allowing you to customize exactly what appears and exactly what they're allowed to change.

Note: its not recommended to allow your customers to use the data crawler to access your data files directly. There's no way to specify validations or do anything complicated, so unless you're careful, there are lots of ways your customers could use this tool to do damage to your data files. It is a programmer tool only.

If you do decide to use it for your end users, be careful how you implement it.

=== Import/Export to CSV ===

You can use FileIO to export your data files to CSV or import from CSV into your data file. To do this, you want to run the data crawler and select the file layout you're looking for. Then, view it (or press F5 to edit if you want to import something). Click on the Export button and it will ask you to select a file. Once that is selected it will ask a couple other simple questions, and when you've specified the options to your satisfaction, click the Export! button. A new CSV file will be created.

Import is even more simple. To import, you must be in Edit mode (press F5 to select the file instead of the enter key) and then simply select the Import button. It will ask you again to choose the file, and then it will ask you if it should update all files by Record Number (if record number is recorded in the CSV file) or by Key (if the file has keys) or to just Add all information to the file. Select what you want and press Import and the CSV file is added to the BR data file.

==== Function Access to Import/Export from your programs ====

You can use the following functions to call the Import and Export functionality from your code.

*[[#fnCSVImport|fnCSVImport]]
*[[#fnCSVExport|fnCSVExport]]

These functions are intended to give you the ability to use our functionality to write your own import and export routines for your customers, because its not a good idea to let your customers run the Data Crawler.

=== Generate Layout Wizard ===

There is also a Generate Layout Wizard utility in FileIO. This utility is there to help you build your file layouts. It is designed to work with a certain style of BR programming that was common in the 80s and 90s. So if your software is written in a style that opens the file directly, and reads/writes the data to a long series of individual variables, the Generate Layout Wizard is for you.

To use it, start by running FileIO. Then, don't select a layout - instead, click on the "Generate Layout" button.

You'll see a screen with a bunch of large text boxes, a small grid, and some buttons.

The first thing you want to do is select the "Browse" button and then select a .wb or .br file that contains a program that reads or writes Most of the File.

When you select one, press the Scan All button and it fileio will search the whole program looking first for all the open strings. It will take the file that is opened the most times and then search for all read statements to that file. It will look for the longest read statement and then find the Form statement associated with that Read statement, and any DIM statements for any variables used.

If you don't like the file its chosen, click the "Open Scratch Pad" button to open the temp work file it uses into the program of your choice (I use myEdit for BRS files). Simply select all the open statements for the file you DO want to build off of, then click the Paste button to paste those open statements into the "Open String" list. After that click "Clear All" to erase what it did on the first search and then click "Scan All" again to rescan the program using this new data file.

You may have to help it a bit, but once it has a proper matching open statement, read statement, form statement and dim statements for any arrays used, press the "Generate Layout" button and it will build a layout for that file.

Finally, load the layout it built and clean up anything if you want, and consider adding better descriptions for each of the fields that you know (as it will use the variable names for both the subscripts AND descriptions in the layout).

When you're all done, click "Done".

==== Functions to Generate Layouts from your code ====

* [[#fnGenerateLayout_.26_fnWriteLayout|fnGenerateLayout]]
* [[#fnGenerateLayout_.26_fnWriteLayout|fnWriteLayout]]

=== Code Templates ===

One more tool FileIO has to help is the ability to generate code based on your file layouts.

Run FileIO and this time select a file layout and press "Generate Code". A window will pop up listing all the "Code Templates" that are available. Select one (and then select a key if it asks you - some templates require extra info). It looks like nothing happened, but the code you generated is now in your clip board. Paste it somewhere and take a look at it!

Code Templates help us to standardize our ways of doing things, which eventually leads to more and more powerful tools we can use. Code Templates also help ensure we use cleaner code by doing some of the busy-work of writing clean code for us.

==== Writing Code Templates ====
FileIO ships with several basic code templates. If you want to add your own, take a look in the filelay\templates folder (configurable in fileio.ini) and look at basic.brs. Copy it to your own program and then modify it to have your own code templates in it. Write me at gabriel.bakker@gmail.com with any questions. I want to help.

And if you write good code templates, its easy to share them with the BR community. Anyone can download your templates and place them in this folder and they'll instantly be available for use.

== FileIO Function Reference ==
''The FileIO Library contains a number of other useful functions.'' The following functions are available and you are welcome to use them:

=== Primary Functions ===

==== fnOpen ====
fnOpen is the primary function that opens a file, and it’s used like so:

''def Fnopen(Filename$*255, Mat F$, Mat F, Mat Form$; Inputonly, Keynum, DontSortSubs, Path$*255, Mat Descr$, Mat FieldWidths, SupressPrompt, IgnoreErrors, SuppressLog)''

Note that all of the parameters after MAT Form$ are optional. If you need to specify a parameter in the middle of the optional parameter group, just list zeroes and empty strings for the intervening unused parameters.

*FileName$ - The filename of the file layout for the file you’re reading.
*MAT F$ - The array that will be used to hold the string data for the file.
*MAT F – The array that will hold the numeric data for the file.
*MAT Form$ - An array of form statements.
*InputOnly – 1 means open for input only. 0 means open for OutIn and open every key file associated with the given data file (this is because all key files need to be open for the keys to be updated on an output) (defaults to 0). Files opened for input process considerably faster than files opened for output. Furthermore when files are opened for input only, alternate key files are ''not'' opened.
*KeyNum – This tells the function of which key to return the file handle (defaults to 1). Specify -1 to force the file to open Relative, without using its keys. If a file has no keys, it will always be opened Relative.
*DontSortSubs – The function by default, when compiling the Form statement, will sort the string and numeric subs in order to allow for reading the data into an array, and this parameter would turn this functionality off. However, if you are trying to read your data without reading it into an array, you are missing out on some serious efficiencies. You should normally leave this option turned off (0). This is a totally unsupported feature, and should always be set to 0, if it is specified at all.
*Path$ - The path to your data files. This optional parameter can be passed in by the calling function. It is prefixed to the beginning of the paths given in the file layout files. It is useful when your data files can be in different locations depending on the state of your program.
*mat Description$ - This optional parameter provides a way to read the description for each field from the original file layout. If the parameter is not provided, no description data will be returned.
*mat Fieldwidths – This optional parameter will return an array of the calculated display field widths. This number will always be at least large enough to contain the data for this field.
*SuppressPrompt - This optional parameter can be used to suppress the prompt normally given when fileIO creates a file. It can have three values. A value of 0, the default, uses the setting stored in your FileIO fnSettings routine to determine weather or not to prompt on Creation of a new file. A nonzero value always suppresses the prompt. A value of 1 indicates never to create a file if the file doesn't exist. A value of 2 automatically creates the file if the file doesn't exist.
*IgnoreErrors - Normally when fileio opens a data file, if there are errors trying to open the file, it prints them out to the debug console and pauses so that you can try to find out whats going wrong. If you specify 1 for "IgnoreErrors" it will cause Fileio to log those errors instead, and continue loading your program. This will result in the fnOpen file function returning Zero instead of the opened file number, so if you use IgnoreErrors, you need to test to make sure that fnOpen returned a file number before you try to access the file.
*SuppressLog - this optional parameter can be used to suppress writing to the log file for this one specific open statement. I use it for files that will be opened all the time, for example, the menu data file on one of my customers systems. Without this boolean parameter, his log file is quickly filled up with useless information any time his employees look at his menu. I specify this optional parameter to suppress logging anything about the menu file so that I can more easily find the actual programs they've used when looking in the logfile.

'''''Note: When using fnOpenFile, you really want to call your local function fnOpen, which in turn calls fnOpenFile for you.''''' FnOpenFile is for internal use only.

Example:

Let FFILE=FNOPEN(“FARM”,MAT FARM$,MAT FARM,MAT FORM$,0,2)
Let RFILE=FNOPEN(“ROUTE”,MAT ROUTE$,MAT ROUTE,MAT FORM$,1,3)
Let CFILE=FNOPEN(“CUSTOMER”,MAT CUSTOMER$,MAT CUSTOMER,MAT FORM$)

assuming:
farm.dat has 3 keys: farm.ky1, farm.ky2, farm.ky3
route.dat has 4 keys: route.ky1 … route.ky4
customer.dat has 2 keys: customer.ky1, customer.ky2

This will perform the following opens and set the following variables:

OPEN #1: “Name=Farm.Dat, kfname=farm.ky2”,internal,outin,keyed
OPEN #2: “Name=Farm.Dat, kfname=farm.ky1”,internal,outin,keyed
OPEN #3: “Name=Farm.Dat, kfname=farm.ky3”,internal,outin,keyed
OPEN #4: “Name=Route.Dat, kfname=route.ky3”,internal,input,keyed
OPEN #5: “Name=Customer.Dat,kfname=customer.ky1”,internal,outin,keyed
OPEN #6: “Name=Customer.Dat,kfname=customer.ky2”,internal,outin,keyed
LET FFILE=1
LET RFILE=4
LET CFILE=5

This will also resize the arrays, set the form statement, and create all the subscripts to make accessing the data clear and simple, as in the above example. The KEYNUM parameter is where you list the key file you would like to use for reading and writing. The extra keys are opened to ensure that all keys get updated properly when the file is changed.

Example:
DIM FORM$(1),PRICE$(1)*255,PRICE(1),
DIM DESCRIPTION$(1)*80,FIELDWIDTHS(1)

Let PRICEFILE=FNOPEN(“PRICE”,MAT PRICE$,MAT PRICE,MAT FORM$,0,2,0,"",MAT DESCRIPTION$)

Assuming the Price File layout (filelay\price) contains:

price.dat, PR_, 1
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
DUMMY, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2
DESCRIPTION$, Description of Price Rule, C 30

This will perform the following opens and set the following variables:

OPEN #1: “Name=Price.Dat, kfname=Price.ky2”,internal,outin,keyed
OPEN #2: “Name=Price.Dat, kfname=Price.ky1”,internal,outin,keyed
OPEN #3: “Name=Price.Dat, kfname=Price.ky3”,internal,outin,keyed
let PRICEFILE=1
let PR_FARM=1
let PR_ITEM=2
let PR_GRADE=3
let PR_DESCR=4
let PR_PRICE=1
let PR_COST=2
let PR_XOPRICE=3
let PR_XOCOST=4
let PR_MOPRICE=5
let PR_MOCOST=6
let PR_VOPRICE=7
let PR_VOCOST=8
MAT FORM$(1)
MAT PRICE$(4)
MAT PRICE(8)
MAT DESCRIPTION$(12)
MAT FIELDWIDTHS(12)
let FORM$(1)=CFORM$(”form C 4,C 4,C 4,POS 74,C 30,POS 50,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2,BH 3.2”)
let Description$(1)= “Farm Code (or blank)”
let Description$(2) = “Item Code”
let Description$(3) = “Quality”
let Description$(4) = “Description of Price Rule”
let Description$(5) = “Default Price”
let Description$(6) = “Default Cost”
let Description$(7) = “Default Christmas Price”
let Description$(8) = “Default Christmas Cost”
let Description$(9) = “Default Mothers D Price”
let Description$(10) = “Default Mothers D Cost”
let Description$(11) = “Default Valentine Price”
let Description$(12) = “Default Valentine Cost”
let FieldWidths(1) = 4
let FieldWidths(2) = 4
let FieldWidths(3) = 4
let FieldWidths(4) = 30
let FieldWidths(5) = 8
let FieldWidths(6) = 8
let FieldWidths(7) = 8
let FieldWidths(8) = 8
let FieldWidths(9) = 8
let FieldWidths(10) = 8
let FieldWidths(11) = 8
let FieldWidths(12) = 8

There are a few things I’d like to point out about the example above. First, you will notice that the form statement jumps around to put all the strings first, and then the numbers last. This is why it has a “POS 74, C 30,POS 50”. Then notice that the subscripts for the string variables are 1 .. 4, and the subscripts for the numbers are 1 .. 8. Finally, the order of the Description and FieldWidth fields also match the sorted positioning of the Form Statement.

The reason that we sort our form statements is so that BR will allow us to read the file into arrays by saying:

Read #pricefile, using form$(pricefile) : mat price$, mat price

Without resorting, the above statement would give a conversion error as BR attempted to put the PR_PRICE field inside mat price$(4). However, because we have reordered the form statement, we are able to read them safely into two arrays, and then we will be able to use the values without caring what position they are in the file, by simply saying PRICE$(PR_DESCRIPTION) when we want the description, and PRICE(PR_PRICE) when we want the pr_Price field.

Another thing you may notice about the above example is that it gives the calculated display length for the numeric fields as 8, when on the disk (and in the file layout) they are listed as BH 3.2. The reason for this is the program looks at the BH 3, and figures that a number that takes up 3 bytes on disk has a potential maximum size of 256**3 or 16,777,216, and therefore will need up to 8 characters of screen display space to view.

Finally, note that any field with a form statement of X is ignored by the library, except that the blank space is used when building the FORM statement.

==== fnCloseFile ====
This function will close the specified file number and all keys that were opened with the file. The purpose of this function is to facilitate the closing of the extra keys that are opened when you open a file for OutIn with the library. There is no need to use this for files opened for input because it is easier to just close the file directly. Secondary keys are not opened by FileIO for files opened for input only.

You must give the function the name of the file layout. It uses this information to determine how many keys were opened, and how many it must therefore close.

Then it basically starts at the file number you gave it, and closes the next X files that were opened with the same file name as this, where X is the number of keys associated with this file.

The syntax is:

''fnCloseFile(filenumber,filelay$;path$)''

*FileNumber – The filenumber of the file you are trying to close.
*FileLay$ - The name of the file layout for this file. This is used to determine how many keys the file would have been opened with and therefore how many we now need to close.
*Path$ - Optional Alternate Path. Use to close files that were opened using the open file's optional alternate path parameter.

==== fnGetFileNumber ====
FnGetFileNumber is a simple function to find a valid unused file handle. If you use this function in all of your programs, they will become much more portable, as you will never have to worry about your file handles fighting with each other. The function will return 0 if no free file number was found (but with 999 of them available now, I have never seen it happen).

''fnGetFileNumber(;X,Count)''

*X – This optional parameter will specify where to start looking.
*Count - This optional parameter will specify how many file numbers to find in a row. If count is 3, then fnGetFileNumber will return the first filenumber in the first gap of three unused file numbers that it finds.

=== File Reading Helper Functions ===

These functions perform various useful calculations to aid in interacting with data files when you're using fileio.

==== fnBuildKey$ ====
This function will return the key for a given record in a data file. It actually reads the file layout and builds the key to match the layout.

''FnBuildKey$(Layout$, Mat F$, Mat F; Keynum)''

*Layout$ - the name of the data file to build the key for.
*Mat F$ - the string array of the file object
*Mat F - the numeric array of the file object
*KeyNum - This optional parameter specifies which of the key files in the given layout the key should be built for.

To use this, you want some code like in the following example:

mat customer$=("") : mat Customer=(0)
let customer$(cu_name)=CustName$
let customer$(cu_phone)=CustPhone$
read #customer, using form$(Customer), key=fnBuildKey$("customer",mat Customer$,mat Customer,2) : mat Customer$, mat Customer nokey KeyNotFound
! The above code assumes that the second key of the Customer file is based on the Name and Phone fields.

By using this logic you are able to avoid directly specifying the key in your code - which means that even if the key changes in the future, as long as your code specifies enough information, it will still find the correct key. In our example, even if we dropped the phone number from the key in the future, or even if we expand the length of the Customer Name field, our code would still work and fnBuildKey$ would still build the correct key without us having to look at or change our code again.

This kind of reasoning is central to the fileio system, which, when implemented properly, ensures that you can change your data files in any way you need to in the future, without breaking your existing programs.

==== fnUniqueKey ====
This function tests to see if a given key is unique to the specified file. This function is very useful for situations where you need to ensure that the user-entered key is unique.

''fnUniqueKey(Fl,key$*255)''

*FL – The file number of the opened file.
*Key$ - This is the key to test. If this key is the key for a preexisting record in the file, the function will return false. If this key can not be found in the file, the function will return true.

==== fnMakeUniqueKey$ ====
This function generates a unique key for a given file. This is useful if you do not care what the key is, but it needs to be unique. I use this function in situations where the user never needs to know what the given key is.

This function reads the key length for the given file. Then it returns a string that is the right length, which is generated by counting in binary until a key is found that does not appear in the file. The first key found for a 4 byte key field would be chr$(0)&chr$(0)&chr$(0)&chr$(0). If that key was already in use in the file, the function would return chr$(0)&chr$(0)&chr$(0)&chr$(1). If that one was also in use, it would then try chr$(0)&chr$(0)&chr$(0)&chr$(2), and so on until it found one that wasn’t in use.

''FnMakeUniqueKey$(fl)''

*FL – This is the file number of the opened file for the desired key.

==== fnKey$ ====
This function formats the key for the given file number. All it does is ensure the key is the correct length. You should use fnBuildKey$ instead to properly build the correct key for the record you want to read.

''FnKey$(FileNumber, Key$)''

*FileNumber - the file number we are formatting the key for
*Key$ - the key we are trying to format.

==== fnNotInFile ====
This function will determine if a non-key element in a line is unique. It works almost exactly like fnUniqueKey specified above, except that it allows you to enter the subscript value of the element you are checking for uniqueness. You can use this to look for uniqueness in any field, not just in the key field. Additionally, the search engine used by this function looks for a partial match, and will only return true if the given string is not found anywhere in the specified element for the given file.

''fnNotInFile(string$*100,filename$,sub)''

*String$ - Value to check for uniqueness in this file.
*Filename$ - This is the name of the file layout of the file you want to check. This file does not have to be open in order for you to search it, because the function will open it for you.
*Sub – This is the subscript value of the element you are checking.

==== fnSortKeys ====
This function takes an array of Primary Keys indicating records in the data file, and resorts it into the order you would have expected using one of the other keys for your data file.

For example: Lets say you had a customer file, and the first key was Customer Code and the second key was Customer Last Name. This function would take an array of Customer Codes and sort it into Last Name order.

This function requires the file to already be opened (which is usually the case when you have an array of keys from that file).

''fnSortKeys(mat Keys$,Layout$,DataFile,mat F$,mat F,mat Form$;KeyNum)''

*mat Keys$ - the array of keys. These keys are based on whatever key the file was opened with in DataFile.
*Layout$ - the file layout for the file.
*DataFile - the open file number matching the key file that matches mat Keys$.
*mat F$ - array sized to hold the strings from the data file. This is the array you get back from fnOpen.
*mat F - array sized to hold the numerics from the data file. This is the array you get back from fnOpen.
*mat Form$ - array of form statements, that you get back from fnOpen.
*KeyNum - This is the key that we'll sort based on. If not given, the first key listed in the layout is assumed.

=== File Reading Functions ===

These functions actually read information from your data file and return it. These functions can be used to simplify the logic in your programs for many common tasks.

==== fnReadAllKeys ====
This function will read through a file, returning the specified element(s) from each record into (a) dynamically dimensioned array(s). For example, I could tell it to give me the Inventory Code for every inventory item in my database in one array, while placing the Inventory Description (name) for each item into the corresponding position in another array.

''fnReadAllKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$;sub2,mat out2$)''

*Fl – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array
*mat out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

For example:

FnReadAllKeys(InventFile,mat Invent$,mat Invent,mat Form$,IN_Code,mat InvtList$,IN_Name,mat InvtNames$)

==== fnReadMatchingKeys ====

This function will read through a file, returning the specified element(s) from each record where the key matches the specified key into (a) dynamically dimensioned array(s). This function is the same as the above function except this one will filter the results, returning only those records where the key matches the specified key.

''fnReadMatchingKeys(Fl,mat f$,mat f,mat fm$,key$,keysub,sub1,mat out1$;sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*mat F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*mat fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - Only records where the key field matches key$ will be returned.
*Keysub – This tells the function which element is the key element for this particular file number.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*mat out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadAllNewKeys ====

This function will read through a file, returning the specified element(s) from each record that isn’t already there into (a) dynamically dimensioned array(s). This function is the same as the above function, except this one will filter the results returning only those records that don’t already exist in the array (eliminating duplicates).

''FnReadAllNewKeys(Fl,mat f$,mat f,mat fm$,sub1,mat out1$; dont_reset,sub2,mat out2$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Dont_reset – By default the array will clear the contents of the arrays that are passed in. This Boolean flag will instruct the function to not empty the passed in arrays.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) parameter. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.

==== fnReadFilterKeys ====

This function by Mikhail Zheleznov is a modification of the above functions. Like its predecessors, it reads an entire file, populating the specified arrays with data from all or some of the records in the file. The given subscripts specify which fields to return from each record. The key given specifies search criteria for the records. The filter specifies filtering criteria that can be preformed on the data before it is returned.

''FnReadFilterKeys(Fl,Mat F$,Mat F,Mat Fm$,Key$,Keyfld,Sub1,Mat Out1$;Filter$,Filter_Sub,Readlarger,Sub2,Mat Out2$, Sub3, Mat Out3$, Sub4,Mat Out4$)''

*FL – The file handle for the already opened file in question.
*MAT F$ - Work array with a size that corresponds to the number of string elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT F – Work array with a size that corresponds to the number of numeric elements in the record (this is calculated automatically in the Open statement, if you used this library to open the file).
*MAT fm$ - Array of Forms statement. FM$(FL) must be the form statement for this file (this is calculated automatically in the Open statement, if you used this library to open the file).
*Key$ - The key to search for in the read statements
*Keyfld – the subscript of the key field in the data file. This must match the key field specified in the data file otherwise the function won’t work.
*Sub1 – Subscript of the element to return in the first array.
*MAT out1$ - Array in which to return the data. This array will be resized to match the number of records in the file.
*Filter$ – This optional parameter identifies matches to search for in the records. It works in conjunction with Filter_Sub
*Filter_Sub – This parameter specifies which field to look for in the records for matches to Filter$. Only records which have Filter$ in the specified field will be returned.
*Sub2 – Subscript of the element to return in the second array. This is optional. If it is specified, you must give MAT out2$, or BR will return an error.
*MAT out2$ - Array in which to return the second (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub2 is given (non-zero). This parameter will not be used if Sub2 is not given or is given as 0.
*Sub3 – Subscript of the element to return in the third array. This is optional. If it is specified, you must give MAT out3$, or BR will return an error.
*MAT out3$ - Array in which to return the third (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub3 is given (non-zero). This parameter will not be used if Sub3 is not given or is given as 0.
*Sub4 – Subscript of the element to return in the fourth array. This is optional. If it is specified, you must give MAT out4$, or BR will return an error.
*mat out4$ - Array in which to return the fourth (optional) field. This array will be resized to match the number of records in the file. This parameter MUST be provided when Sub4 is given (non-zero). This parameter will not be used if Sub4 is not given or is given as 0.

This function was written by Mikhail Zheleznov for the fileIO library.

==== fnReadDescription$ ====
''fnReadDescription$(Fl,Subscript,key$,mat F$,mat F,mat Form$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout) (RT_NAME, which should equal 2 after opening routefile (unless we change the file layout later)).
*key$ - Item that should match a key in this file somewhere (in this case it is the route code from the farm record).
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading they have to be dimensioned properly, which is why we use our colorcat$ and our colorcat for these parameters.
*mat Form$ - This will need to be our array of form statements, so the function can read the file properly.

Lets take a look at how this function works:

In the example program I used above, I am reading the Color File to get details about each color. The color file contains a colorcat code field, but I want to display the colorcat description. The colorcat file contains a few details about a color category, and it is indexed based on colorcat code:

route.dat, RT_
route.key, CODE
recl=512
===================================================
CODE, Routing Code, C 6
NAME, Routing Name Description, C 30
MOFT, T/A/C (truck/air/courier), C 1
SHIPPINGDAY, Day of Week for Shipping, C 7

Now, as you know, in the above example, we have already opened the ColorCat File, and we have opened and read a Color record.

04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)

30120 read #colorfile, using form$(colorfile) : mat color$, mat color eof Ignore
30180 LET ccode$=color$(CO_CODE) !:
LET Name$=color$(CO_NAME)

Now all that’s left to do is to take the Color File’s ColorCat code and use it to look up the ColorCat File’s description.

30190 LET ColorCat$ = fnReadDescription$(ColorCatFile, CC_NAME, Color$(CO_CATEGORY),
mat ColorCat$, mat ColorCat, mat form$)

==== fnReadUnopenedDescription$ ====
This function accomplishes the same thing as fnReadDescription except that it opens the data file for you. It is slower then FnReadDescription$, but it is easier to use.

''FnReadUnopenedDescription$(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the value of the key field in the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2, so sometimes it is a good idea to design your data files so that string field number two is a descriptive field, like Name or Description.

This function only works on the first key file for each data file. This function is a convenience function but it is slow because it opens the file and closes it for each call. Opening a file is one of the most time consuming program operations.

==== fnReadNumber ====

fnReadNumber does the same thing that ReadDescription does except it reads a numeric field instead of a description.

Lets take a look at how this function works:

''fnReadNumber(Fl,subscript,key$,mat F$,mat F,mat fm$)''

*Fl – File Handle for file to use (Route File).
*Subscript – Index of field in record to use (should be taken from file layout).
*Key$ - Item that should match a key in this file somewhere.
*mat F$ & mat F - Work Variables to hold a file record from the file we are reading. They have to be dimensioned properly by [[FileIO_Library#fnOpenFile|fnOpen]].
*mat Fm$ - This will need to be our array of form statements, so the function can read the file properly.

==== fnReadUnopenedNumber ====
This function accomplishes the same thing as fnReadNumber except that it opens the data file for you. It is slower then FnReadNumber, but it is easier to use.

''fnReadUnopenedNumber(Layout$,key$*255;Field)''

*Layout$ - the layout of the file we are reading
*key$ - the key of the record to be read
*Field - the element of the data file to return. If not given, this defaults to 2.

==== fnReadRelativeDescription$ ====
This function is the same as fnReadDescription$ but for Relative Files.

''fnReadRelativeDescription$(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat F,mat form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedDescription$ ====
This is the same as ReadUnopenedDescription$ but for Relative Files.

''fnReadRelUnopenedDescription(Layout$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRelativeNumber ====
This is the same as fnReadNumber but for Relative Files.

''fnReadRelativeNumber(FileNumber,SubscriptToRead,RecordNumber,mat F$,mat f,mat Form$)''

*Filenumber - The file number of the open data file
*SubscriptToRead - The subscript to read
*RecordNumber - the Record number to read
*mat F$ and mat F - the arrays to hold the data. They must match the dimensions and should be set with [[FileIO_Library#fnOpenFile|fnOpen]].
*mat form$ - the forms array is also set by [[FileIO_Library#fnOpenFile|fnOpen]].

==== fnReadRelUnopenedNumber ====
This is the same as fnReadUnopenedNumber but for Relative Files.

''fnReadRelUnopenedNumber(LayoutName$,RecordNumber;Field)''

*Layout$ - The file layout
*RecordNumber - the record to read
*Field - the field subscript to read

==== fnReadRecordWhere$ ====
This function returns the record where the given element matches the given value. It does not depend on any key files, and it can be used to locate a record based on any element. However, it loops through the entire data file to do this and it could be a bit slow for large data files. This function opens the file for you, so the file does not have to be already opened.

''FnReadRecordWhere$(Layout$,SearchSub,SearchKey$*255,ReturnSub)''

*Layout$ - the layout of the file we are searching
*SearchSub - Subscript of the element to look in
*SearchKey$ - The value we are looking for
*ReturnSub - Subscript of the element to return

=== FileIO Utility Functions ===
==== fnDataCrawler ====
This function launches the Data Crawler as a function, so you can make your own programs link to it. Special thanks to Mikhail Zheleznov for turning the DataCrawler into a library function.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnDataEdit ====
This function is the same as fnDataCrawler only it opens a Grid for editing.

''fnDataCrawler(Layout$;SRow$,SCol$,Rows$,Cols$)''

==== fnShowData ====

This function builds a list or a grid in a floating window that is tied to a data file. It uses the same function that the datacrawler uses, but its much more customizable. All other datacrawler functions are just wrappers for this one.

The first parameter is the only required parameter.

''def library fnShowData(FileLay$;Edit,sRow,sCol,Rows,Cols,KeyNumber,Caption$*127,Path$*255,KeyMatch$*255,SearchMatch$*255,CallingProgram$*255,mat Records,mat IncludeCols$,mat IncludeUI$,mat ColumnDescription$,mat ColumnWidths,mat ColumnForms$,DisplayField$*80,mat FilterFields$,mat FilterForm$,mat FilterCompare$,mat FilterCaption$,mat FilterDefaults$,mat FilterKey)''

*FileLay$ - the file layout you want to display
*Edit - 1 for Edit (Grid) and 0 for View (Listview)
*sRow, sCol - the start position. if not given, its centered. If given but out of bounds, they'll be automatically adjusted to fit the grid on the screen.
*Rows, Cols - the size. If not given, defaults to fullscreen. If given but not big enough to fit the UI elements you request, they're automatically adjusted to fit everthing.
*KeyNumber - the Key to use when reading the data, used with other parameters. If not given, the file is read Relative for faster performance. Required if KeyMatch$ is given.
*Caption$ - the Caption to display, defaults to FileIO's Datacrawler
*Path$ - Alternate path to use for data files (Prepended to the name found in the layout)
*KeyMatch$ - Show only records that match this key. You can use Partial Keys. If this parameter is given, you must also give KeyNumber (above).
*SearchMatch$ - Show only records that contain this substring in them anywhere
*CallingProgram$ - used for logging purposes, pass in the system function Program$
*mat Records - Show only these records in the Grid. Use it to control exactly what the user sees.
*mat IncludeCols$ - Show only these columns. These column names must match the subscript names from the file layout.
*mat IncludeUI$ - Which UI Options to show. Build this array with one element for each optional UI element to include. Explanations of UI elements follow:
**"ColumnsButton" - adds a Select Columns button that the user can use to modify which columns appear on the list.
**"ExportButton" - adds an Export to CSV button that exports the data to a CSV file.
**"ImportButton" - adds an Import from CSV button that imports from the CSV file.
**"AddButton" - adds a button that can be used to add records to the data file.
**"SaveButton" - adds a button allowing the user to save changes
**"DeleteButton" - adds a button allowing the user to delete a row
**"KeyButton" - adds a button allowing the user to jump to a specified position by key or by record number (depending on if the file is opened keyed or not)
**"QuitButton" - adds a Quit button to the screen (the Esc key also quits)
**"Search" - adds a case insensitive search box to the screen.
**"Border" - adds a border around the screen
**"Caption" - adds a caption. (If you specify a caption, this is automatically turned on. If you don't specify a caption but turn on caption here, then FileIO uses the default FileIO data crawler caption.
**"Recl" - adds the Recl to the caption
**"Position" - adds the positions to the field descriptions in the column headings.
*mat ColumnDescription$ - Show these captions. If blank, use the descriptions from the layout
*mat ColumnWidths - Use these widths for the data, if not given, calculate from the file layout
*mat ColumnForms$ - Display Format for the data, including DATE and FMT and PIC
*mat DisplayField$ - Counter Field to display on the Loading Window. If its a field with an associated DATE ColumnForms$ value, that column form will be used when displaying the Counter Field. It can be any of the following:
**REC - this will display the current "REC/LREC" data in the loading window.
**READCOUNT - this will display the "Record Count / LREC" in the loading window.
**FINDCOUNT - this will display the number of records that match the current search criteria by itself in the loading window.
**A Field Name - one of your field names will display that field value in the loading window
**A string literal - anything else will display as a string in the loading window, so you could put something like "Loading, please wait" here and it will display.
*mat FilterFields$ - Contains the subscript of the field to compare to
*mat FilterForm$ - Contains the format of the field to compare to
*mat FilterCompare$ - Contains the comparison type ("<>" or ">" or "=" or ">=" or "*") (* means do a substring search)
*mat FilterCaption$ - The caption for the filter box
*mat FilterDefaults$ - The default value for the filter information
*mat FilterKey - The action to use when filtering the data this way (0 means simple exclude, 1 means start here, -1 means stop here)
**The final five arrays can be used to add user filter boxes to the data grid. You need one element in each array for every custom user filter box on the screen.

==== fnBeginAudit ====

The [[AuditBR|FileIO Compare]] routine is available and can be called from within your programs. To do so, call fnBeginAudit to mark the Start of the compare, then do whatever you need, then run fnCompare to compare everything that has changed between when you ran fnBeginAudit and when you ran fnCompare.

See [[AuditBR#fnBeginAudit|the documentation]] for more details.

==== fnCompare ====

See [[AuditBR#fnCompare|the documentation]] for more details.

==== fnCSVImport ====

This function calls the FileIO Import routine, the same one that you get from the Datacrawlers Import Button.

''fnCsvImport(Layout$*64;SuppressDialog,FileName$*300,ImportModeKey)''

*Layout$ - The file layout to import into
*SupressDialog - 1 to Supress the Import Dialog
*FileName$ - the name of the CSV file (Required if Dialog is Suppressed)
*ImportModeKey - the Import Mode Key (Required if Dialog is Suppressed)
**-1 - Add all records to the file
**0 - Update by Record Number (The file must contain a RecNum column and it must be first)
**1+ - Any positive number means Update by that Key (as listed in the layout).

==== fnCSVExport ====

This function exports a data file to a CSV file.

''fnCsvExport(Layout$*64;SuppressDialog,Filename$*300,IncludeRecNums,KeyNumber,StartKey$,KeyMatch$,Startrec,mat Records,SearchMatch$)''

*Layout$ - The File Layout to Export
*SuppressDialog - (1 to Suppress the Export Dialog, 0 to show it)
*Filename$ - the output file name (Required if SuppressDialog is 1)
*IncludeRecNums - Include a column with the Record Numbers in it
*KeyNumber - Use this key when reading the data for export
*StartKey$ - Start with the record that matches StartKey$
*KeyMatch$ - Export only the record(s) that match KeyMatch$
*StartRec - Start with this Record Number
*mat Records - Export only these records
*SearchMatch$ - Export only records containing this search string anywhere in them

==== fnExportListViewCsv ====

Exports the contents of the specified Listview in CSV format.

''fnExportListViewCsv(Window,Spec$;GenFileName,Delim$,FileName$*255)''

*Window - The Window containing the listview.
*Spec$ - The Spec identifying the listview.
*GenFileName - Flag telling weather or not to generate the file name.
*Delim$ - Delimiter to use. Comma is default.
*Filename$ - Filename to use

==== fnGenerateLayout & fnWriteLayout ====

This function calls on the Generate File Layout Wizard to generate and save the layout indicated by the parameters you give it. You must give it the same valid parameters that you would have come up with if you worked through the layout wizard the normal way, by running FileIO directly and choosing "Generate Layout".

You can also bypass the automatic parsing and generate a layout by specifying all the data directly and using fnWriteLayout.

''fnGenerateLayout(mat OpenStrings$, ReadString$*999, FormString$*20000, DimString$*999; DisplayFile)''
''

*mat OpenString$ - array of all the open strings for the given file from one of your old programs.
*mat ReadString$ - solid read statement from one of your old programs reading the entire record, (or at least everything you want in the layout).
*mat FormString$ - the form statement that goes with the ReadString$ (practice using the Generate Layout Wizard the normal way for details)
*mat DimString$ - the string containing Dim statements for each array mentioned in ReadString$. We need this to know how big the arrays are.
*DisplayFile - if True (1), it will Display the new layout in notepad when its done creating it. If false (0), it will simply create the file.

fnGenerateLayout takes all the above information and parses it into a layout, then calls fnWriteLayout to actually write the layout.

If you already know the information you want to put in the layout, its more direct to call fnWriteLayout below.

''fnWriteLayout(Name$,FileName$*127,VER,PRE$,MAT KFNAME$,MAT KDESCRIPTION$,MAT SUBS$,MAT DESCR$,MAT FORM$;RECL,MAT EXTRA$,DISPLAYFILE)''

*Name$ - the name of the new layout
*FileName$*127 - the name of the data file
*Ver - the version of the data file
*Pre$ - the prefix to use for the data file
*mat KfName$ - array of all the keys for the file
*mat Kdescription$ - array of the subscripts that each key is based on
*mat Subs$ - the subscript for each field in the file
*mat Descr$ - the descriptions for each field in the file
*mat Form$ - the form specs for each field in the file
*Recl - (optional) the record length of the file
*mat Extra$ - (optional) Additonal Information for each field in the file, placed in the Comments column of the new layout. This column is ignored by standard fileio processing.
DisplayFile - if True, open the file in Notepad after it has been created.

==== fnSubstituteStringCode ====
A Large Text Field that is searched. Code is run and any resulting variables are set, if they exist inside String enclosed between Substitute Chars (default []), then they will be replaced with the values derived by the code.

''fnSubstituteStringCode(&String$,Code$*2048;SubstituteChar$)''

*String$ - the string to be searched
*Code$ - code to be run. The resulting variables can be substituted into String
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnSubstituteString ====
A Large Text Field that is searched. Any matching fields in the passed in record will be substituted into their places. For example, if the string contained [cu_name] and you ran substitutions on the Customer file, then [cu_name] would be replaced by the name in the actual Customer record.

''fnSubstituteString(&String$,Filelayout$,mat F$,mat F;SubstituteChar$)''

*String$ - the string to be searched
*FileLayout$ - the layout to be searched
*mat F$ - the record to be used for substitution
*mat F - the record to be used for substitution
*SubstituteChar$ - Defaults to [] but here you can override the Substitute Character to be used.

==== fnShowMessage ====
Displays a message to the user, in a child window. Returns the child window number, so that you can close it when you're done with the message.

''WindowNumber=fnShowMessage(Message$*54)''

*Message - the Message to display to the user

=== File System Utility Functions ===
These functions perform other tasks that aid with interacting with the file system.

==== fnGetFileDateTime$ ====
This does a directory listing to determine the Last Modified Date and Time of the given file. You pass it a file name, not a file layout, and it can be used on any file. Its not limited to BR internal files.

The syntax is:

''let FileDate$=fnGetFileDateTime$(Filename$*255)''

==== fnProgressBar ====
There's a Progress Bar that FileIO uses when copying or updating data files. You can use it in your own functions by calling fnProgressBar inside the main loop of the process that you want to display the progress bar over, and by calling fnCloseBar when you're done.

''fnProgressBar(Percent;Color$,ProgressAfter,ProgressThreshhold,UpdateThreshhold,Caption$*255,MessageRow$*255)''

*Percent - Percentage Complete expressed as a float between 0 and 1
*Color$ - HTML Color Code of BR Color Attribute to color the Progress Bar. Defaults to Green.
*ProgressAfter - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*ProgressThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*UpdateThreshhold - This value can be used to prevent the progress bar from loading when the job takes only a short time.
*Caption$ - Optional message to display above the progress bar.
*MessageRow$ - Optional message to display on the progress bar.

==== fnCloseBar ====

''fnCloseBar''

Call this function to close the progress bar window when your task is done running.

==== fnCopyFile ====

''fnCopyFile(FromFile$*255,ToFile$*255)''

*FromFile$ - The file to copy.
*ToFile$ - The destination file name including path.

This function copies any file, by opening it as an external file and reading and writing the data to the destination file. The advantage of this technique, over using the BR copy command, is this routine is more reliable when run on client server where you may be transferring large files from one side to the other over the internet.

This fnCopyFile also has a progress bar that displays as the file is transferred, so the user knows your software is busy.

This function works over Client Server. Under Client Server, specify @: at the beginning of your filename, to specify that the file is on the client. If the file is on the server, simply leave the @: off. See the chapter on [[Copy#Client_Server|using BR's copy command under Client Server]] for more details on the "@:".

This function's parameters and syntax are modeled off of the built in BR copy command, and like that one, this should work for local transfers, LAN transfers, or even internet transfers. This function will work better for internet transfers then the built in BR Copy Command, however.

==== fnCopyDataFiles ====

''fnCopyDataFiles(DestinationFolder$*255)''

*DestinationFolder$ - the folder to copy your data files to.

This function reads your file layouts and makes a copy of every data file (and key file) in your system to the destination folder, utilizing fnCopyFile above, for better performance and reliability when running over the internet, as well as a progress bar for each individual file.

It also displays a listview while its copying so you can watch the progress while its transferring your data files.

This can be used for making backups of your BR data, or for transferring the latest data onto a laptop for access to it while you're on the road away from the internet.

==== fnReIndex ====

This function reindexes a single data file

''fnReIndex(DataFile$*255;CallingProgram$*255,IndexNum,Path$*25)''

*Datafile$ - the file layout of the file to index
*CallingProgram$ - used for logging, pass Program$ in here
*IndexNum - The index to rebuild - if not given, rebuilds all indexes
*Path$ - the optional alternate path to use for rebuilding the data file.

==== fnReIndexAllFiles ====

This function reindexes all your data files. It doesn't require any parameters.

''fnReIndexAllFiles''

==== fnUpdateFile ====
This function checks and Updates a data file if it needs to be updated, by opening and then closing the data file.

''fnUpdateFile(FileLayout$)''

*FileLayout$ - The name of the file to update

==== fnRemoveDeletes ====

This function, written by Susan Smith, removes deleted records by copying the file with the -D option.

''fnRemoveDeletes(LayoutName$*255;Path$*255,CallingProgram$*255)''

*LayoutName$ - the file layout
*Path$ - Optional Alternate Path
*CallingPRogram$ - used for logging, pass Program$ in here

=== Layout Interrogation ===
Layout interrogation functions are provided for convenience and to enable future dictionary changes without disrupting any programs that interrogate it.

==== fnMakeSubProc ====
This function obtains the subscript assignments that were assigned by fnOpen according to the file layout. The fnMakeSubProc$ routine obtains the subscript assignments without actually opening the file. This is useful when a file record is passed as arrays into a library function in another program, or when you chained to another program and you need to know how to reach the data in the arrays without actually reopening the file.

''fnMakeSubProc(filelay$;mat Subscripts$)''

*FileLay$ - The name of the file layout from which to read the subscripts.
*mat Subscripts$ - If you give this optional array, fnMakeSubProc passes the subscripts back in this array rather then in the subs.$$$ file. This is much faster and helps avoid sharing conflicts.

When this routine returns, you can set the subscripts in your program by executing every element of the Subscripts$ array in a for/next loop.

If you did not pass in a subscripts array, then the a procedure file named subs.$$$ is created. If you proc that file, the proper subscripts will be set.

==== fnReadLayoutArrays ====
This function reads the fields in a file layout into arrays. You call it like the following

''fnReadLayoutArrays(filelay$,&prefix$;mat SSubs$, mat NSubs$, mat SSpec$, mat NSpec$,mat SDescription$, mat NDescription$,Mat Spos,Mat Npos)''

*filelay$ - the name of the layout to read
*prefix$ - the return value for the prefix for the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

This function call would read the fields from the layout in filelay$, and it would return the prefix to prefix$. The Subs would be returned in mat SSubs$ and mat NSubs$.

The Spec statements are returned in mat SSpec$ and mat NSpec$ and the Descriptions are returned in mat SDescription$ and mat NDescription$. The start positions on disk of each element are returned in mat SPos and mat NPos.

All the arrays are optional. If you don’t pass them the information they are supposed to record is simply not returned.

==== fnReadLayoutHeader ====
This function reads the header for a given file layout.

''fnReadLayoutHeader(Layoutname$*255;&Filename$,Mat Keys$,Mat KeyDescription$)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file

==== fnReadEntireLayout ====
This function reads the entire layout by calling fnReadLayoutHeader and fnReadLayoutArrays.

''fnReadEntireLayout(Layoutname$*255;&Filename$,&Prefix$,Mat Keys$,Mat KeyDescription$,Mat Ssubs$,Mat Nsubs$,Mat Sspec$,Mat Nspec$,Mat Sdescription$,Mat Ndescription$,Mat Spos,Mat Npos)''

*LayoutName$ - Name of the layout to read
*Filename$ - The file name read from the layout
*prefix$ - the return value for the prefix for the file
*Mat Keys$ - Array to be populated with the list of keys for the file
*Mat KeyDescription$ - Key Description String returned from the file
*mat SSubs$ - the return value for all the string subscripts in the layout
*mat NSubs$ - the return value for the numeric subscripts in the layout
*mat SSpec$ - the return value for the string fields specs
*mat NSpec$ - the return value for the numeric fields specs
*mat SDescription$ - the return value for the Descriptions of the String Specs
*mat NDescription$ - the return value for the Descriptions of the Numeric Specs
*mat SPos - the return value for the starting positions of the String Specs
*mat NPos - the return value for the starting positions of the Numeric Specs

==== fnReadSubs ====
This function reads the subscripts from a layout into Subs arrays.

''fnReadSubs(Layout$,mat SSubs$,mat NSubs$,&Prefix$)''

*Layout$ - the file layout name
*mat SSubs$ - the String Subscript Names
*mat NSubs$ - the Number Subscript Names
*Prefix$ - the files Prefix

==== fnReadKeyFiles ====
This function reads the list of key files from the layout.

''fnReadKeyFiles(Layout$,mat Keys$)''

*Layout$ - The file layout
*mat Keys$ - output array, the keys are returned here.

==== fnLayoutExtension$ ====

This function returns the layout extension being used.

==== fnReadLayouts ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''FnReadLayouts(mat Dirlist$)''

*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all the file layouts that FileIO can find.

==== fnDirVersionHistoryFiles ====
This function reads the file layout folder and returns all the applicable layouts in the passed in array.

''fnDirVersionHistoryFiles(Layout$,mat DirList$;BypassExtension$)''
*Layout$ - Which layout to look up version history of
*Mat Dirlist$ - After running the function, mat Dirlist$ will contain a list of all previous versions from history of the requested layout.

==== fnReadLayoutPath$ ====
This function doesn't actually interrogate your layouts. Instead, it interrogates your settings and returns the path specified for your layout files. This would usually be "filelay\" but you can change it in [[#fnSettings|fileio.ini.]]

It has no parameters.

''let Path$=fnReadLayoutPath$''

==== fnDoesLayoutExist ====
This function returns true if the given file layout exists. It returns false if the layout does not exist.

''FnDoesLayoutExist(layout$)''

*Layout$ - Layout to test for

==== fnReadForm$ (uncompiled) ====
Sometimes you need to know the original form statement that fileio is using to read your data file, most often when you're debugging your file layout, and you're getting some problem when reading the file. The form statement that fileio normally returns is compiled using CFORM$ to save space in the array, and to make the execution of your read statements faster. You can use this function to return the original form statement for the file.

The syntax is:

''let FormStatement$=fnReadForm$*10000(FileLayout$)''

Remember to dimension FormStatement to something huge! fnReadForm$ can return up to 10,000 characters.

==== fnReadFormAndSubs ====

This function does the same as above but it also reads the subscripts from the file into an array.

''let fnReadFormAndSubs(Layout$,mat Subs$,&ReadForm$,&StringSize,&NumberSize)''

Note that unlike most of our functions, all the above parameters are required.

The layout is the layout you're interrogating. The Array will be populated with the subscripts after the function. The ReadForm$ variable will be filled with the form statement for the file. Remember to dimension it large enough. StringSize and NumberSize will contain the number of string fields and numeric fields in the file.

Mat Subs$ will be returned, strings first, numbers last, matching the form statement that is returned. So Subs$(1) is the first string subscript and Subs$(StringSize+1) is the first Numeric subscript.

==== fnClearLayoutCache ====

fnClearLayoutCash (v2.3+) clears out the cache of layout name and data to get realtime Updates to File Layouts.

=== Other Useful Functions (non-layout related) ===

==== fnAskCombo ====

Opens a window with a combo box and returns the users selection.

''fnAskCombo$*255(mat Description$;Caption$*60,Default$*255)''

*mat Description$ - contains the combo box choices
*Caption$ - contains the optional caption for the window
*Default$ - the text of the item in mat Description$ that you want to be selected by default

==== fnSendEmail ====

This function sends an email and an optional attachment to the email address specified.

''fnSendEmail(Emailaddress$*255,Message$*10000;Subject$*255,Invoicefile$*255)''

*EmailAddress$ - the Destination Email Address
*Message$ - the Message$ to send
*Subject$ - the subject
*InvoiceFile$ - the filename of a file to attach. This is the BR filename (the function automatically converts it to an OS Filename.)

The function returns 1 when the email was sent successfully, or 0 if it wasn't sent successfully.

In order to use this function, you must have the emailcfg file layout in your layouts folder and you must have a copy of SendEmail.exe which is free and can be downloaded from the internet. Both of these files are included with the latest update of fileio.

You also have to configure fileio with the authentication information for your email server.

To configure your email server, simply run FileIO to get the data crawler, then select the emailcfg file layout and press F5 to edit it. Add a row if the file is empty.

Simply fill in the information the file is asking for in the appropriate fields and save the data, and then test sending an email to make sure it worked.

More information about sendEmail.exe is available from the author's product site here: [http://caspian.dotconf.net/menu/Software/SendEmail/ http://caspian.dotconf.net/menu/Software/SendEmail/]

==== fnClientEnv$ ====

This function returns the value of a Windows Environment Variable on the client under Client Server.

''fnClientEnv$*255(EnvKey$)''

*EnvKey$ is the name of the Windows Environment Variable to check on the client.

The function returns the value of the entered environment variable.

==== fnClientServer ====

This function returns true if you're currently running in Client Server mode, and false if you're running in the old "native" mode.

==== fnEmpty & fnEmptyS ====
These functions test if the passed in array is empty or not..

The syntax is:

''fnEmpty(mat Numeric)''

or

''fnEmptyS(mat String$)''

Example:

def fnSomeFunction(String$,mat Array$; mat OtherArray)
if fnEmpty(mat OtherArray) then
! Arrays were empty.
end if
fnend

==== fnReadScreenSize ====
This function reads the screen size of the given window (or window 0 if a window wasn't passed.) This is useful for centering a window on the screen, or for making sure window 0 is big enough for the child window you're trying to create.

The syntax is:

''fnReadScreenSize(&Rows,&Cols;Window)''

*Rows & Cols - returns the screen size in rows and columns.
*Window - the window to interrogate. If not given, assumes [[Open_Window#Comments_and_Examples|Window 0]].

==== fnBuildProcFile ====
This function builds a proc file to be executed later. This function and the next simplify the process of executing code in a proc file. It can even be used to spawn a new session of BR.

To use it, call fnBuildProcFile one or more times and specify some lines of code to execute.

''fnBuildProcFile(Command$*255)''

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnRunProcFile ====

This function spawns a new copy of BR and in it, runs the proc file that you've previously built using fnBuildProcFile (above).

'' fnRunProcFile(;NoWait) ''

The optional parameter "NoWait" causes the other session to spawn and run in a new thread. If you don't specify NoWait, the current session pauses and waits for the other session to close before proceeding.

let fnBuildProcFile("load "&Program2$)
let fnBuildProcFile("run")
let fnBuildProcFile("system")

let fnRunProcFile(1)

==== fnLog & fnErrLog ====
These next two functions are functions to aid in logging. When you call either of these two functions, you give them a string that you wish to log. They will open the FileIO Log File and add a record to the end of it containing some user information such as login_name and session$, and the string that you specified. FnErrLog does the same thing as fnLog except it also logs the Error Number and the Line.

The syntax is:

''FnLog(string$)''

*String$ - the Log Message

''FnErrLog(String$)''

*String$ - the Log Message

==== fnLogArray ====

This function logs the given arrays to the log file, logging each field in the arrays. Its useful for recording, for example, an entire data record that is about to be written to a data file.

The syntax is:
''fnLogarray(mat F$,mat f;Message$*512,CallingProgram$*255)''
The first two parameters, of course, are the array to log. The third parameter is an optional message to be recorded along with the array, and the fourth optional parameter is the CallingProgram$ to save in the log along with the message. (The CallingProgram$ parameter can usually be passed as the system function Program$)

==== fnSetLogChanges ====
This function works in conjunction with the next function, and they're for recording just what changed in a data file. When the file is read, you call fnSetLogChanges and record the "before" picture of the file record.

After changes have been made and saved back to disk, you can call fnLogChanges below to record the actual changes.

The syntax is:
''fnSetLogChanges(mat F$,mat F)''

==== fnLogChanges ====
This function is the other half of the function above. It compares the given arrays with the ones set previously in the above function and checks for changes. Then it generates a log message recording information about just the items that changed.

The syntax is:
''fnLogChanges(mat F$,mat F;Message$*1024,CallingProgram$*255,Layout$)''

You need to pass in the same two arrays as before, but this time the modified versions of them.

You can also optionally pass a 1024 byte log message to record with the log entry.

CallingProgram$ again should be passed as the system internal function Program$.

The final parameter allows the passing of a Layout$. If you pass a Layout$, that layout is read and the subscripts are used when making the log message of changes, so that its easier to read. If you pass a layout, it will identify the changed fields by name. If you don't it will identify those fields by relative position number.

==== fnViewLogFile ====
All of the above functions store the information by default into a BR internal file defined in the filelay\logfile layout.

The fnViewLog function uses fnShowData to call the Data Crawler to display the FileIO Log File in a searchable listview.

''fnViewLogFile(;ShowQuit,ShowColumns,ShowExport)''

*ShowQuit - Show a quit button on the UI (if off, ESC will quit).
*ShowColumns - Include a button to allow the user to select which columns to view.
*ShowExport - Include a button to export the log file to CSV.

==== fnReadLockedUsers ====

This function returns a list of all users using the locked data file.

''fnReadLockedUsers(mat Users$)''

*mat Users$ - the list of users is returned here

==== fnDisplayLength ====
This function calculates the display length of a field based on its form spec.

''fnDisplayLength(Spec$)''

*Spec - the Form Spec to return the display length of.

==== fnLength ====
This function calculates the length on disk of a field based on its form spec.

''fnLength(Spec$)''

*Spec$ - the Form Spec to return the length of.

==== fnStandardTime$ ====
Converts Military Time to Standard Time. Returns Standard Time$

''fnStandardTime$(MilitaryTime$;Seconds)''

*MilitaryTime$ - Time in 24 hr format.

==== fnMilitaryTime$ ====
''fnMilitaryTime$(StandardTime$;Seconds)''

*StandardTime$ - Time in AM/PM Format

==== fnCalculateHours ====
Calculates the difference between 2 specified times.

''fnCalculateHours(TimeIn$,TOut$,DaysIN,DaysOut)''

*TimeIn$ - From Time
*TimeOut$ - To Time
*DaysIn - Days Start
*DaysOut - Days End

==== fnBuildTime$ ====
Builds a time in the format used by the above functions.

''fnBuildTime$(H,M,S,P;Military,Seconds)''

*H - Hours
*M - Minutes
*S - Seconds
*P - Boolean indicating AM/PM - 0 is AM, 1 is PM
*Military - Flag indicating weather desired result is in Military Time or not
*Seconds - Flag indicating weather to count seconds or ignore them. (1 means count seconds)

==== fnParseTime ====
Takes a time and pulls out the values

''fnParseTime(T$,&H,&M,&S,&P)''

*T$ - the time to parse
*H - Return value for Hours
*M - Return value for Minutes
*S - Return value for Seconds
*P - Return Value for AM/PM

== FileIO fnSettings (Global Settings Code) ==

The FileIO library can be made to implement certain policies across the board. These are established by creating a file called fileio.ini and typing statements like the following into it. This file is "PROCed", so you don't want to put line numbers in it.

Anything you don't specify in fileio.ini will take its default value, shown below. So you only need to specify the items that you want to be different.

Note, for the boolean settings below, 1 denotes TRUE and 0 denotes FALSE.

let EnforceDupkeys=1 ! Enforce that key number 1 is unique key
let Defaultfilelayoutpath$="filelay\" ! Path To Your File Layouts
let Promptonfilecreate=1 ! Ask User Before Creating New Files
let Createlogfile=0 ! Use Logging
let StartFileNumber=1 ! Set above 300 to avoid conflicts with legacy programs.
let CheckIndex=0 ! Automatically Verify Indexes (slow)
let CompressColumns=0 ! Shrink or Expand Columns in Data Crawler by Default
let MaxColWidth=20 ! Max Default Column Width in Data Crawler
let LogLibrary$="" ! Defaut Log Library, defaults to None
let LogLayout$="" ! Log file layout, defaults to Internal File
let AnimateDatacrawler=1 ! Use ScreenIO Animation for Datacrawler
let TemplatePath$="filelay\template\" ! Default Template Path
let IgnoreLayouts$="" ! List any Ignore Layouts here.
let CloseFileSimple=0 ! Use simple comparison for fnCloseFile

==== EnforceDupkeys ====

Turn on the EnforceDupkeys option to force that the first key listed in your file layouts is a unique key. FileIO will generate the standard BR error for Dupkeys when attempting to create indexes if it is not unique.

==== DefaultFileLayoutPath$ ====

Use the DefaultFileLayoutPath option to specify the path from your programs to your file layout folder. The default is "filelay\". Use this setting if you want to place your file layouts in another folder from the default.

==== PromptOnFileCreate ====

Use the PromptOnFileCreate setting to cause FileIO to display a message box whenever it is attempting to create a new file. This happens during the automatic update procedure, as well as during any attempt to access a file that does not exist. This setting should be turned off in your live system, and only turned on for development purposes. If you use the message box to cancel creating of the new file, then the file is not created, and fileIO or your application will most likely give an error when you attempt to actually access the new file.

It can be useful during development to make sure that you don't accidentally create the wrong files, due to an incorrectly specified path or a typeo in the filename in the layout file. However, in a live system, these things have already been tested, and you generally want the default behavior, because you don't want your users to have the ability to cancel the normal operation of FileIO.

==== CreateLogFile ====

Use this option to specify weather or not to use the FileIO log file. If it is turned on, a log file called FileIO.log in the current directory is created with entries listing all attempts to open a file, automatically update one, or automatically update your indexes.

==== StartFileNumber ====

Use this option to set the starting file number that the fnGetFileNumber and the fnOpen functions use to search for available file numbers. This is so that if you have certian reserved file numbers in your code, you can make sure that FileIO will not use those reserved file numbers, causing a conflict with your already existing programs. The default is 1, which is fine if your software does not have any reserved file numbers.

The allowable BR file numbers are 1-200 and 300-999.

==== CheckIndex ====

This function is used for Partial FileIO Implementations. If all of your software uses FileIO then all of your indexes are kept automatically up to date by the FileIO library and BR's internal file processing systems. However, if some of your programs do not use FileIO, and you use the FileIO library to add a new index file that those other programs do not know about, then its possible for the additional index file to become out of date when the master file is updated by your other programs.

Use this setting to cause FileIO to check the DateTime stamp on all your index files when opening a new file, and automatically update any indexes that may have potentially gotten out of date from other programs.

This option slows down the processing of the fnOpen function, particularly when running under client server over the internet. If you know that every program in your application suite uses FileIO, and that any programs that do not use FileIO still properly update all the indexes that your data file uses, then you can safely leave this setting turned off, and optimize your performance when opening several files using the fileIO system.

==== CompressColumns ====
This instructs the datacrawler to use smaller widths for small columns. If CompressColumns is false, the data crawler will make the column the width of the field or the width of the caption, whichever is wider. If CompressColumns is true, it will use the width of the field, not the caption.

==== MaxColWidth ====
This limits the column width to a set amount. This is applied after CompressColumns above.

==== LogLibrary$ ====
If a library is specified here, then fileio looks for a BR library with the specified name, and attempts to call a library function in it called fnFileIOLog that. This function should expect six parameters, which are Logstring$, Login_Name$, Session$, Days of Date$, Time$, and CallingProgram$, if LogLayout is also nonblank.

If you specify a LogLibrary and LogLayout is blank, then it calls your function giving it only 1 parameter.

It will call your function '''''instead of''''' the normal log file. Use this to implement your own logging functions however you want.

==== LogLayout$ ====
Use this setting to specify an alternate file layout for an alternate file to do the logging in. Base the file layout for this file on the logfile we supply for you in the filelay folder. It should have at least those fields, which our log routine will automatically populate, but you can add other fields if you want (though you will need to manage them yourself).

If you don't specify LogLayout, the default filelay\logfile will be used. This will allow you to also use the fnViewLogFile function to access it.

==== AnimateDataCrawler ====
The sister library [[ScreenIO]] has a feature that allows you to use an animation of a clock in your loading screens in your own programs. If you have [[ScreenIO]] then FileIO will automatically detect it and use it to display a loading animation while the data in the data crawler loads.

Set AnimateDataCrawler to false (0) in your fileio.ini file to bypass the animations if you do have screenio but don't want to see the animations anyway.

==== TemplatePath$ ====
This setting points to the folder that contains the code templates used by the Generate Code button on the main page of the Data Crawler.

==== IgnoreLayouts$ ====
This is a comma delimited list of all layouts that you wish to suppress from appearing on the main page of the data crawler. You can still access these layouts with your code, but they won't be listed in the data crawler for you to access.

Whatever you're using for a log layout, is automatically added to this list.
==== CloseFileSimple ====
The fnCloseFile function closes all the individual handles to a data file that was opened for output using multiple keys.

For BR 4.18 and higher, we support a better algorithm for detecting which files are matches for a given opened file number.

Set CloseFileSimple to true (1) to force it to check the old way.

== FileIO Add-on Packages ==

Many FileIO Add-on packages are currently in the works.

=== ScreenIO Library ===

The [[ScreenIO Library]] is a sister library to the FileIO library. The ScreenIO library requires the FileIO library in order to run.

The ScreenIO library is a complete Rapid Application Design tool that enables you to implement custom screen functions anywhere in your exiting programs.

If you call the ScreenIO Library as a function library, you call a function called fnFM and tell it which screen you wish to use. The ScreenIO library loads your user interface, loads your data files, and preforms all the file maintenance operations you have designed into your screens.

You can find out the latest information about the ScreenIO library in the ScreenIO page.

=== Audit BR ===

The [[AuditBR|Audit BR]] developer tool makes a backup copy of your file layouts. Then you run some code you're trying to test, and finally, run Audit BR again, to get a report showing all the changes to any of your data files automatically.

AuditBR is now included directly in FileIO. To use it, select the layout from the list of layouts in the Datacrawler and press the "Compare" button.

== What’s New (also described above) ==
=== 2018 ===
*Support for dates in any storage formats on disk (v2.48)

=== 2015 ===
*Added Rec to display for fnShowData
*Added FormStatement$ for debugging of form statements inside fileio
*Added mat BadRead$ for debugging of 726 errors when making new layouts
*Fixed a bug causing crash when logging things from long program folders
*fnClientEnv$ - reads a Windows Environment variable on the client using the command shell
*fnAskCombo$ - added an optional parameter to set default selection.

=== 2010 - 2014 ===
*FileIO now caches your file layouts in memory to make it much faster then before when opening the same data file in multiple programs.
*Generate Layout Wizard
*fnShowData
*Improved Logging
*fnViewLogFile
*Import/Export
*Import/Export by Function
*Many other speed increases
*if ScreenIO is present, Datacrawler uses the animation routines
*fnBuildProcFile & fnRunProcFile
*fnGenerateLayout & fnWriteLayout
*fnReadForm$
*fnReadFormAndSubs
*fnGetFileDateTime$
*fnReadLayoutPath$
*fnSortKeys
*fnSetLogChanges
*fnLogChanges
*fnLogArray
*fnReadScreenSize
*fnEmpty
*fnEmptyS
*Many other useful functions that were added to the documentation at earlier dates.

=== Spring 2009 ===

'''''New Functions:'''''

The FileIO Library has been updated in Spring 2009 to provide several new functions:

*fnReadRecordWhere
*fnKey$
*fnBuildKey$
*fnReadUnopenedDescription$
*fnUpdateFile
*fnDisplayLength
*fnLength
*fnReadLayoutHeader
*fnReadEntireLayout

'''''Speed Increases:'''''

Thanks to the BR [[Profiler]], we have increased the speed of FileIO fnOpen function by ten times when running over a LAN and by 100 times when running over the internet using Client Server.

In order to get the new Speed Upgrades, you will need to make sure that you use the latest copy of the [[#fnOpen_Function|fnOpen]] function in each one of your programs that use FileIO.

'''''Network FileIO:'''''
This version of FileIO has been optimized to work better in network situations.

'''''FnSettings: '''''
There are more configuration options in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine.

'''''Automatic Update Speed Fix:'''''
The automatic update proceedure has been made to run more then 100 times faster then before according to our benchmarking tests.

=== Fall 2008 ===
'''''DataCrawler Grid:'''''

By popular request we added a read/write version to the data crawler. This version works exactly the same as the datacrawler did before but it displays all the contents of your data files in a grid instead of a listview.

When you run the fileIO library as a program, it launches a tool known as the [[#DataCrawler|DataCrawler]]. The DataCrawler shows a listview displaying all your layout files in it. If you select one, it builds another listview with all the data in your selected data file.

If you are looking at the first list of all your file layouts, and you press F5, a grid will be build displaying all the data in your data files. You can change any of the records you like, and when you're done, your changes will be saved to the data file. Additionally, you can Add or Delete records using the buttons at the bottom. Any changes you make are not written to the disk until you click the "Save" button. If you press ESC (Cancel) the grid is closed and all changes you made sinse the last save are lost.

This tool is for programmers only. Do not give your end users access to the DataCrawler.

Use the DataCrawler at your own risk. Gabriel Bakker and Sage AX are not responsible for any harm that comes to your data files through the use of this or any other tools we offer.

The DataCrawler is not designed to be used to maintain your data files. It can be used carefully to correct small things in your data files.

'''''Support for Nonstandard Paths:'''''

Many BR Vendors keep different versions of the same data files in different locations. For example, sometimes a BR vendor will use a different Data folder to represent data for different Warehouses, or Customers. In cases like this it is necessary for your programs to specify the path to your data files. They may do so by specifying the optional "PATH" parameter to your data files. See the section [[#fnOpenFile]] for more information.

'''''Support for Nonstandard Layout Files Path:'''''

Old versions of the fileIO library required you to place all your file layouts in a subfolder of your program directory called "filelay". We have now changed the Fileio library to allow you to place your file layouts any place you want. The only requirement is that they are all together in one folder by themselves.

If you use a nonstandard path in the fileIO library, it is necessary to make a change to the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code in your copy of fileio.br.

'''''Prompt on Create:'''''

The FileIO library automatically creates any data files that it can't find. This was done to make it easier to deploy your finished programs - if you had any empty data files you could omit them from the packages and they would be created when they were needed, on the fly.

The current version of the FileIO library contains the same ability. However, it prompts you before creating any data files. This helps to avoid bugs that happen from incorrectly specifying the path to your data files.

However, if you do intend for your data files to be autocreated, then you probably don't want your end users to modify them. Therefore, you can use the PromptOnCreate setting in the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] code to specify. If this value is set to true, then the fileIO library will prompt you whenever it attempts to Autocreate a data file. If it is set to false, then the fileIO library will create the data files without prompting you, like it always did before.

'''''fnSettings:'''''

The newest version of the FileIO library supports some features that require you to specify Global Settings values. These are done by modifying the contents of the [[#fnSettings_.28Global_Settings_Code.29|fnSettings]] routine at the beginning of the fileIO library.

=== Fall 2006 ===
Many improvements have been made in the FileIO library over the summer. This section is intended to acquaint you with the highlights of those changes. Most of these improvements were built from ideas generated during the discussion at the April conference.

'''''Intermixed String and Numeric Specs:'''''
The File Library has been expanded to allow the reading of data files that contain mixed string and numeric specs. This is to aid those of you who are planning on implementing the FileIO Library on existing data files which may not be organized with strings first and numbers second.

The central idea of the FileIO Library is based upon the reading of your data files into a String and Numeric array. This will enable you to refer to the fields in your file by using a named subscript, saying F$(FM_NAME) to refer, for example, to the farm file’s name field. The advantage to this is that when you change the file layout, all your existing programs will not have to be modified, because they will only be looking at F$(FM_NAME). If the name field changes from the third string field to the fourth, the value of FM_NAME will also change, and you won’t have to worry about updating your data files.

However, in order to support the reading of a data file with intermixed string and numeric specs, the generated form statement will actually calculate the position of any fields that are not in order, so that the file read statement will still return all string fields first (into your string array) and the numeric fields second (into your numeric array). You do not need to worry about this; the library does it for you. All you have to do is read your file and use the data values.

The only thing that is required is making sure that all your string subscript names end with a “$”. This will tell the library that they are strings. Thank you, George, for this suggestion.

'''''Versioning / Automatic Updates:'''''
The file layouts have been expanded to contain a version number. This version number will be used to determine when a file needs to be updated. The version number is the third parameter in the file layout.

Any time you wish to change your file layouts, simply increment this version number. Each time the library attempts to open a data file, the file’s version is checked and compared with the version in the file layout. If the file layout has been changed (if the version in the file layout is greater then the version in the file) then the file will be updated to the latest version. Depending on the file size this may take a couple of moments. A simple progress bar will be displayed on screen while this is happening. The progress bar will be displayed in its own window, so it should not affect anything your programs may have had on screen.

The library uses the following procedure for updating a file. First, the file is copied to a backup file (prefixed by the letter ‘o’ for old). So color.dat would become ocolor.dat, and color.key would become ocolor.key. Then the new file is created and marked with the proper version number. (color.dat, color.key). The old file is opened in read-only mode, and the new file is opened for OutIn. The update routine actually reads through the old file layout, and one record at a time creates a new record, using the new file layout, with the same data, saving it to the new data file.

When it is done upgrading, the progress bar window is closed, and the file is reopened in the fashion you described in your call to fnOpen, and flow returns to your program as though nothing unusual has happened.

If an error occurs during processing, the routine will do what it can to roll your data files back to the previous version, but please make frequent backups of your data files anyway, just to be safe.

'''''Error Checking – If there is a mistake in the file layout:'''''
The routine attempts to discover the cause of the error in the case that one is encountered due to a missing file, a file sharing violation, or an invalid or corrupt file layout. If this should happen, the program is paused, and a text message is printed out explaining the most likely source for the error, including what part of the file layout, if any, may have caused the error.

You may then examine the printed text, and the contents of the BR system variables ERR and LINE to determine the problem. If you type “GO”, the next line will be execute “system”, ending your program.

If the file was in the middle of an upgrade when the error happened, it will be automatically rolled back to the previous version, so that when you fix the problem and try to run your program again, the file will again attempt to update from the beginning, and you won’t have to worry about corrupted data.

However, please backup your data before upgrading your data files anyway, just to be safe.

'''''Implementation of Keys / Creation of New Data Files:'''''
The library has been expanded to automatically create all new data files, and to automatically update any existing files. This means that in the file layout header, two new fields that were previously ignored are no longer ignored. The RECL value that you specify in your file layout will be used, along with the description/definition of your keys file. When you open a new file (or update an existing one), the library will calculate the proper kps and kln by evaluating the key description. This key description must match up with subscript values from the data elements in your file, and more then one may be specified, but they must be separated with slashes (/). If I wanted my Farm File to be keyed based on CODE and NAME, the proper key description would be:

farm.key, CODE/NAME

The library will then look up the position and length on disk of the CODE and NAME fields and put them together to create the proper keys during an update or creation of a new file.

'''''DataCrawler:'''''
Perhaps the most exciting new addition to the library is the addition of a programming tool I like to call a DataCrawler. If you run the FileIO Library directly as a program, instead of using it as a library, it will function as a DataCrawler. The DataCrawler requires a New Gui version of BR, as it requires a ListView to be able to properly and easily display the data in your files.

If you run it in an older version of BR you will get a message, telling you to run it in a newer copy. If you run it in a New Gui version of BR with CONFIG GUI OFF, then GUI will be turned temporarily on for the use of the DataCrawler and then turned off again when you are finished. If you run it in a New Gui version of BR with GUI ON, it will just run normally.

When you run the DataCrawler, first you will see a ListView displaying every file layout it can find in the filelay folder. If you select a file, the DataCrawler will open a large ListView with as many columns as there are fields in the file. The Column Headings will come from the element descriptions in your data files, and the column widths will come from the displayed width of the fields. There will be a row for every record in your data file, and you can resize the column widths, and scroll around the data file to view the raw data of your BR data files on disk.

If you are dealing with a particularly enormous data file (50,000+ records) it can take a moment to populate the ListView with the data in your data file. You may hit ESC to stop loading if you like, and view only the already loaded records.

If you would like to look up a particular record (based only upon the primary key for the data file), you may press F4. This will give you a window which asks you to input the key or partial key. When you press enter, the file will be reloaded, starting at the key you specified and continuing on to the end of the file, or until you press ESC. The records you are looking for should appear at the top of the ListView.

To reset the ListView and look at the contents of the entire file again, simply press F4, and enter a blank (“”) key.

Finally, as with any ListView, you may resort your data by clicking on any of the column headings. Then you can use the slider bar at the right to scroll down to the record you desire.

This is a programming tool and is not designed to be used by an end user. This tool will open your file in read-only mode. It will not allow you to modify the data; I leave that as an exercise for the reader. However, it will update any datafiles you view to the latest version (if they need to be updated) when it opens them, just as any other program that uses the library will do.

== Appendix (Examples)==

=== Example.br ===
00010 ! example.br - This program is an example of for the data reading simplification
00020 ! Copyright April 2006 by Gabriel Bakker
00030 ! Distributed open source as a Christmas gift to brag members
00040 !
00100 execute "config gui off"
01020 DIM form$(1)*255
01030 DIM color$(1)*255,color(1)
01040 DIM colorcat$(1)*255,colorcat(1)
02020 library "fileio": fnopenfile, fnreaddescription$
04000 !
04010 Openfiles: ! Open your files here
04020 let colorfile=fnopen("color",mat color$,mat color,mat form$)
04030 let colorcatfile=fnopen("colorcat",mat colorcat$,mat colorcat,mat form$,1)
06000 ! gosub WriteFiles ! If you want to test this line, make sure to drop flag from 4030
07000 !
07010 MainBit: ! This'un here's tha Main Bit
07030 RESTORE #ColorFile:
07100 ReadNextcolor: ! Read next record
07120 read #ColorFile, using form$(ColorFile) : mat Color$, mat Color eof EndReadColor
07180 PRINT Color$(co_name)&" ("&Color$(co_html)&") is a member of the '";
07190 PRINT trim$(fnReadDescription$(ColorcatFile,cc_Name,Color$(co_category),mat Colorcat$,mat Colorcat,mat form$))&"' category."
07290 goto ReadNextColor
07300 EndReadcolor: ! Finished with Color File
08000 STOP
25000 !
25010 WriteFiles: ! Uncalled routine to demonstrate writing files
25105 let color$(co_code)="GD" !:
let color$(co_Name)="Gold" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFD700"
25110 write #colorfile, using form$(colorfile): mat color$, mat color
25115 let color$(co_code)="LV" !:
let color$(co_Name)="Lavender" !:
let color$(co_Category)="BL" !:
let color$(co_html)="E6E6FA"
25120 write #colorfile, using form$(colorfile): mat color$, mat color
25125 let color$(co_Code)="OR" !:
let color$(co_Name)="Orange" !:
let color$(co_Category)="YL" !:
let color$(co_html)="FFA500"
25130 write #colorfile, using form$(colorfile): mat color$, mat color
25205 let colorcat$(cc_Code)="YL" !:
let colorcat$(cc_Name)="Yellows" !:
let colorcat$(cc_html)="FFFF00"
25210 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25215 let colorcat$(cc_Code)="BL" !:
let colorcat$(cc_Name)="Blues" !:
let colorcat$(cc_html)="0000FF"
25220 write #colorcatfile, using form$(colorcatfile): mat colorcat$,mat colorcat
25300 return
40000 !
40010 Open: ! ***** Function to call library openfile and proc subs
40020 def fnOpen(FILENAME$, MAT F$, MAT F, MAT FORM$;INPUTONLY,KEYNUM,___,INDEX)
40025 dim _FileIOSubs$(1)*50
40030 let fnopen=fnopenfile(FILENAME$, MAT F$, MAT F, MAT FORM$,INPUTONLY,KEYNUM,MAT _FileIOSubs$)
40040 for Index=1 to udim(mat _FileIOSubs$) : execute (_FileIOSubs$(Index)) : next Index
40090 fnend
50000 !
60000 Ignore: Continue

Color File Layout
color.dat, CO_, 1
color.key, CODE
recl=127
===================================================
CODE$, Color Code, C 6
NAME$, English Name for Color, V 30
CATEGORY$, General Category of Color, C 6
HTML$, HTML Code for the Color, C 6

ColorCat File Layout
colorcat.dat, CC_, 0
colorcat.key, CODE
recl=127
===================================================
CODE$, Category Code, C 6
NAME$, English Name for Color, V 30
HTML$, HTML Code for the Color, C 6

Example Layout showing multiple keys (price)
price.dat, PR_, 0
price.key, FARM
price.ky2, ITEM
price.ky3, FARM/ITEM/GRADE
recl=127
===================================================
FARM$, Farm Code (or blank), C 4
ITEM$, Item Code, C 4
GRADE$, Quality, C 4
X, Empty, X 37
PRICE, Default Price, BH 3.2
COST, Default Cost, BH 3.2
XOPRICE, Default Christmas Price, BH 3.2
XOCOST, Default Christmas Cost, BH 3.2
MOPRICE, Default Mothers D Price, BH 3.2
MOCOST, Default Mothers D Cost, BH 3.2
VOPRICE, Default Valentine Price, BH 3.2
VOCOST, Default Valentine Cost, BH 3.2

[[Category:Utilities_Third_Party]]

4271

2024-09-03T02:41:40Z

Gordon.dye:

{{Error
|4271
|[[Operating System Error]] 71
|Incomplete record received/short record found.
|Incomplete record: retry the [[LINPUT]]. Short record: copy the file to a work area using the -D option to remove the partial record, then copy back the work file to the original.If the above description clearly does not apply to your situation, there is a possibility that you are receiving operating system error 71 Network request not accepted. See your Operating System manual for more information on dealing with this error.

This error can also occur quite legitimately when reading files in [[External Files|External]] mode. Typically such files consist of a data stream of unknown length. When processing blocks of data in such files, the record length is set to chunk size and each READ accesses the next chunk of data. It is up to the program to decipher the actual layout of the data. In such cases, the last record read is often a fraction of the record length (chunk size) and an error 4271 is generated by the read.

When an error 4271 occurs reading an External file, simply save the value of CNT and erform a REREAD into the same buffer as the read. The data length will be the saved CNT value and the remainder of the buffer will be set to binary zeroes.

}}
[[Category:Error Codes]]

SubProc

2024-08-27T04:32:43Z

Gordon.dye:

The '''SubProc(SU)''' command runs one [[procedure]] from within another procedure. It performs the same function for a procedure file as a [[GoSub]] [[statement]] does for a [[program]]. This command can be issued by a program via the EXECUTE or CHAIN statement. For more details see the [[CHAIN]] statement.

==Comments and Examples==

BR suspends the originating procedure when it finds the SubProc command in a procedure file. All active procedure files remain open and BR executes the entire sub-procedure before returning control to the originating procedure. Up to 9 levels of procedures may be nested.

The following example starts execution of the SAMPLE procedure file:

SubProc B:Sample

==Syntax==
SUBPROC <file name>

[[Image:SubProc.png]]

==Parameters==

SubProc requires the '''file name''' parameter, which specifies the file to be executed as a sub-procedure.

==Technical Considerations==

<noinclude>
[[Category:Commands]]
[[Category:Procedure Commands]]
</noinclude>

SubProc

2024-08-27T04:31:09Z

Gordon.dye:

The '''SubProc(SU)''' command runs one [[procedure]] from within another procedure. It performs the same function for a procedure file as a [[GoSub]] [[statement]] does for a [[program]]. This command can be issued by a program via the EXECUTE statement. For more details see the [[CHAIN]] statement.

==Comments and Examples==

BR suspends the originating procedure when it finds the SubProc command in a procedure file. All active procedure files remain open and BR executes the entire sub-procedure before returning control to the originating procedure. Up to 9 levels of procedures may be nested.

The following example starts execution of the SAMPLE procedure file:

SubProc B:Sample

==Syntax==
SUBPROC <file name>

[[Image:SubProc.png]]

==Parameters==

SubProc requires the '''file name''' parameter, which specifies the file to be executed as a sub-procedure.

==Technical Considerations==

<noinclude>
[[Category:Commands]]
[[Category:Procedure Commands]]
</noinclude>

Chain

2024-08-27T04:24:00Z

Gordon.dye: /* Parameters */

The '''Chain''' (CH) [[statement]] ends the current program and starts execution of another program, procedure, or sub-procedure.

===Comments and Examples===
CHAIN is most often used to chain from one program to another. To do this you just type CHAIN and indicate the name of the desired program.

The statement in the following example causes the system to end the current program and load the program MENU.BR (or MENU.BRO) from a subdirectory called MAIN:

00350 CHAIN "MAIN\MENU"

The next example loads and runs the program GLEDIT.BR (or GLEDIT.BRO) from the subdirectory GLPROG (a subdirectory of the root directory). All files stay open at their current positions. The variable D$ retains its current value at the start of the new program; all other variables return to zeros or null strings.

00900 CHAIN "C:\GLPROG\GLEDIT" ,FILES,D$

To chain from a program to a procedure or sub-procedure (rather than another program), you must have either "PROC=" or "SUBPROC=" immediately before the name of the desired file, as in the following two examples:

00900 CHAIN "PROC=GLPOST"

00080 NAME$="EDITLIST.PRC"
00090 X$="SUBPROC=GLPROG\"&NAME$
00100 CHAIN X$

When a program chains to a procedure (PROC or SUBPROC), the procedure acts much like the operator stopped the program and started entering commands. A procedure is a set of commands. (However a procedure can skip forward or backward within itself.) While it is emulating a series of commands, the program that initiated the procedure is retained in memory even though the CHAIN statement terminated it. Therefore its variable contents are accessible to the procedure.

The following example specifies that the string array A$ and the numeric variables B and C are to retain their values in the chained-to program:

60000 CHAIN PROG$,MAT A$,B,C

===Syntax===
CHAIN {"<program name>"|”PROC=<name>”|”SUPROC=<name>”|”<path>\<name>”} [,FILES] [,MAT<array name>][,...] [,<variable name>][,...]

[[file:Chain.png|700px]]

===Defaults===
# Load and run a program.
# Close all open files (except procedure files).
# Set all variables in the chained-to program to blanks or zeros.

===Parameters===
The only required parameter of the CHAIN statement is the "file-ref", which specifies the program, procedure, or sub-procedure to be executed. This name and subdirectory information may be specified as a quoted literal string or as a string variable.

If the file-ref is preceded with the string "PROC=", the CHAIN initiates a procedure. If the file-ref is preceded with the string "SUBPROC=", the CHAIN initiates a sub-procedure. If neither of these keywords is present, the CHAIN statement attempts to load and run a program.

The differtence between PROC and SUBPROC is that PROC will close the current (lowest level) PROC file (if one is running) before starting the specifified procedure, whereas SUBPROC will not affect a currently running PROC file.

The parameters following the file-ref apply only to programs and not procedures.

Following the file-ref information, CHAIN can take three optional parameters, but these parameters should be included only when chaining to a program.

"FILES" indicates that all files are to remain open and at their current positions. If you do not specify "FILES", the CHAIN statement closes all files except procedure files.

The "MAT array-name" and "variables" parameters allow the specified arrays or variables to retain their current values in the chained-to program. If several are used they are seperated by commas.

===Technical Considerations===
# Array variables and string variables passed between programs by a CHAIN statement, are not required to be dimensioned the same way in both programs. If dimensions do not match, the dimensions in the first program will override those in the DIM statements of the second program. However, it is recommended for improved readability that dimensions should match in both programs. Arrays may be re-dimensioned in the second program.
# Options selected in an OPTION statement are not required to be the same in both programs. However, it is strongly recommended that these options be the same. For example, if the first program uses BASE 1 and the second program uses BASE 0, confusing results could "run rampant" because the last element of a 10-element array would have a subscript of 10 in the first program and 9 in the second program.
# RUN command options, which are active in the initial program, will remain active in the chained program. These options include RUN PROC and output redirected to a file (see the RUN command for more information).
# In Business Rules, there is no need for a USE statement in the program being chained. USE is treated as a comment and is maintained only for compatibility with IBM Business BASIC.
# Although Business Rules checks most statements for proper syntax as they are entered, the file-ref parameter of the CHAIN statement is not checked until execution (this is also true in the OPEN statement). In this case, variables and quoted strings cannot be checked until execution. # IBM Business BASIC restricted the use of CHAIN statements within IF statements; if the THEN clause was a CHAIN statement, the ELSE clause was not permitted. This restriction does not apply to Business Rules. The following statement is allowed: 90 IF X=0 THEN CHAIN "MENU" ELSE CHAIN "PR2"
# The rules for the default extension of a program name, which is specified in a CHAIN statement, are the same as the rules for the LOAD command. In short, the system first looks for an extension of .BR; if that is not present, the system then looks for .BRO. You can change these defaults with the CHAINDFLT specification in the BRConfig.sys file. You can also override the defaults from within the CHAIN statement by specifying your own extension, as in the following example:900 CHAIN "C:\MAIN\MENU.OLD"
# The ability to pass specified variables from a program to a procedure is not explicitly supported in Business Rules because the values of all variables are available at the end of a program. These variables retain their values until a SORT, INDEX, CLEAR, or LOAD command is encountered from the keyboard or from a procedure file. This means that any variable from the calling program could be tested by a SKIP command (or therwise used) in a procedure file. (Notice that this also means those values of all variables are available to an opertor after program termination for interrogation [displaying contents] and debugging.)
# Like most Business Rules statements, CHAIN may be used in immediate mode like a command (except with the EXECUTE statement, where commands may not terminate a program.) Within a procedure, the following two commands are equivalent: PROC EOM - CHAIN "PROC=EOM". The next two commands would also be equivalent within a procedure: SUBPROC EOM - CHAIN "SUBPROC=EOM". Although using CHAIN, as a command may not seem very useful because the simpler PROC and SUBPROC alternatives exist, CHAIN allows a procedure to pass variables from it's parent or itself to a program. For example, a procedure file might start a program to print designated messages for certain completion codes as follows: LOAD PROG1 - RUN - X=CODE - SKIP 1 IF X=0 - CHAIN "MESSAGE", X. This passes the variable X (created by PROG1 or the procedure) to be passed to the program named MESSAGE. The same is true if a program CHAINS to a procedure and the procedure simply forwards variables from the chaining program to anotherr program.
# CHAIN "PROC=XYZ" is similar to EXECUTE "PROC XYZ", except EXECUTE does not end the program. That being said, the procedure has the authority to end the program that called it via EXECUTE.
# If the FILES keyword is used to keep files open, file pointers are not moved. Thus, pointers, which were at the end of the file in the first program, will also be at the end of the file in the second program; you may use a RESTORE statement to reposition a file pointer.

<noinclude>
[[Category:Ending Programs Statements]]
[[Category:Statements]]
</noinclude>

Chain

2024-08-27T04:23:02Z

Gordon.dye: /* Parameters */

The '''Chain''' (CH) [[statement]] ends the current program and starts execution of another program, procedure, or sub-procedure.

===Comments and Examples===
CHAIN is most often used to chain from one program to another. To do this you just type CHAIN and indicate the name of the desired program.

The statement in the following example causes the system to end the current program and load the program MENU.BR (or MENU.BRO) from a subdirectory called MAIN:

00350 CHAIN "MAIN\MENU"

The next example loads and runs the program GLEDIT.BR (or GLEDIT.BRO) from the subdirectory GLPROG (a subdirectory of the root directory). All files stay open at their current positions. The variable D$ retains its current value at the start of the new program; all other variables return to zeros or null strings.

00900 CHAIN "C:\GLPROG\GLEDIT" ,FILES,D$

To chain from a program to a procedure or sub-procedure (rather than another program), you must have either "PROC=" or "SUBPROC=" immediately before the name of the desired file, as in the following two examples:

00900 CHAIN "PROC=GLPOST"

00080 NAME$="EDITLIST.PRC"
00090 X$="SUBPROC=GLPROG\"&NAME$
00100 CHAIN X$

When a program chains to a procedure (PROC or SUBPROC), the procedure acts much like the operator stopped the program and started entering commands. A procedure is a set of commands. (However a procedure can skip forward or backward within itself.) While it is emulating a series of commands, the program that initiated the procedure is retained in memory even though the CHAIN statement terminated it. Therefore its variable contents are accessible to the procedure.

The following example specifies that the string array A$ and the numeric variables B and C are to retain their values in the chained-to program:

60000 CHAIN PROG$,MAT A$,B,C

===Syntax===
CHAIN {"<program name>"|”PROC=<name>”|”SUPROC=<name>”|”<path>\<name>”} [,FILES] [,MAT<array name>][,...] [,<variable name>][,...]

[[file:Chain.png|700px]]

===Defaults===
# Load and run a program.
# Close all open files (except procedure files).
# Set all variables in the chained-to program to blanks or zeros.

===Parameters===
The only required parameter of the CHAIN statement is the "file-ref", which specifies the program, procedure, or sub-procedure to be executed. This name and subdirectory information may be specified as a quoted literal string or as a string variable.

If the file-ref is preceded with the string "PROC=", the CHAIN initiates a procedure. If the file-ref is preceded with the string "SUBPROC=", the CHAIN initiates a sub-procedure. If neither of these keywords is present, the CHAIN statement attempts to load and run a program.

The differtence between PROC and SUBPROC is that PROC will close the current (lowest level) PROC file (if one is running) before starting the specifified procedure, whereas SUBPROC will not affect a currently running PROC file.

The parameters following file-ref apply only to programs and not procedures.

Following the file-ref information, CHAIN can take three optional parameters, but these parameters should be included only when chaining to a program.

"FILES" indicates that all files are to remain open and at their current positions. If you do not specify "FILES", the CHAIN statement closes all files except procedure files.

The "MAT array-name" and "variables" parameters allow the specified arrays or variables to retain their current values in the chained-to program. If several are used they are seperated by commas.

===Technical Considerations===
# Array variables and string variables passed between programs by a CHAIN statement, are not required to be dimensioned the same way in both programs. If dimensions do not match, the dimensions in the first program will override those in the DIM statements of the second program. However, it is recommended for improved readability that dimensions should match in both programs. Arrays may be re-dimensioned in the second program.
# Options selected in an OPTION statement are not required to be the same in both programs. However, it is strongly recommended that these options be the same. For example, if the first program uses BASE 1 and the second program uses BASE 0, confusing results could "run rampant" because the last element of a 10-element array would have a subscript of 10 in the first program and 9 in the second program.
# RUN command options, which are active in the initial program, will remain active in the chained program. These options include RUN PROC and output redirected to a file (see the RUN command for more information).
# In Business Rules, there is no need for a USE statement in the program being chained. USE is treated as a comment and is maintained only for compatibility with IBM Business BASIC.
# Although Business Rules checks most statements for proper syntax as they are entered, the file-ref parameter of the CHAIN statement is not checked until execution (this is also true in the OPEN statement). In this case, variables and quoted strings cannot be checked until execution. # IBM Business BASIC restricted the use of CHAIN statements within IF statements; if the THEN clause was a CHAIN statement, the ELSE clause was not permitted. This restriction does not apply to Business Rules. The following statement is allowed: 90 IF X=0 THEN CHAIN "MENU" ELSE CHAIN "PR2"
# The rules for the default extension of a program name, which is specified in a CHAIN statement, are the same as the rules for the LOAD command. In short, the system first looks for an extension of .BR; if that is not present, the system then looks for .BRO. You can change these defaults with the CHAINDFLT specification in the BRConfig.sys file. You can also override the defaults from within the CHAIN statement by specifying your own extension, as in the following example:900 CHAIN "C:\MAIN\MENU.OLD"
# The ability to pass specified variables from a program to a procedure is not explicitly supported in Business Rules because the values of all variables are available at the end of a program. These variables retain their values until a SORT, INDEX, CLEAR, or LOAD command is encountered from the keyboard or from a procedure file. This means that any variable from the calling program could be tested by a SKIP command (or therwise used) in a procedure file. (Notice that this also means those values of all variables are available to an opertor after program termination for interrogation [displaying contents] and debugging.)
# Like most Business Rules statements, CHAIN may be used in immediate mode like a command (except with the EXECUTE statement, where commands may not terminate a program.) Within a procedure, the following two commands are equivalent: PROC EOM - CHAIN "PROC=EOM". The next two commands would also be equivalent within a procedure: SUBPROC EOM - CHAIN "SUBPROC=EOM". Although using CHAIN, as a command may not seem very useful because the simpler PROC and SUBPROC alternatives exist, CHAIN allows a procedure to pass variables from it's parent or itself to a program. For example, a procedure file might start a program to print designated messages for certain completion codes as follows: LOAD PROG1 - RUN - X=CODE - SKIP 1 IF X=0 - CHAIN "MESSAGE", X. This passes the variable X (created by PROG1 or the procedure) to be passed to the program named MESSAGE. The same is true if a program CHAINS to a procedure and the procedure simply forwards variables from the chaining program to anotherr program.
# CHAIN "PROC=XYZ" is similar to EXECUTE "PROC XYZ", except EXECUTE does not end the program. That being said, the procedure has the authority to end the program that called it via EXECUTE.
# If the FILES keyword is used to keep files open, file pointers are not moved. Thus, pointers, which were at the end of the file in the first program, will also be at the end of the file in the second program; you may use a RESTORE statement to reposition a file pointer.

<noinclude>
[[Category:Ending Programs Statements]]
[[Category:Statements]]
</noinclude>

Chain

2024-08-27T04:18:18Z

Gordon.dye: /* Technical Considerations */

The '''Chain''' (CH) [[statement]] ends the current program and starts execution of another program, procedure, or sub-procedure.

===Comments and Examples===
CHAIN is most often used to chain from one program to another. To do this you just type CHAIN and indicate the name of the desired program.

The statement in the following example causes the system to end the current program and load the program MENU.BR (or MENU.BRO) from a subdirectory called MAIN:

00350 CHAIN "MAIN\MENU"

The next example loads and runs the program GLEDIT.BR (or GLEDIT.BRO) from the subdirectory GLPROG (a subdirectory of the root directory). All files stay open at their current positions. The variable D$ retains its current value at the start of the new program; all other variables return to zeros or null strings.

00900 CHAIN "C:\GLPROG\GLEDIT" ,FILES,D$

To chain from a program to a procedure or sub-procedure (rather than another program), you must have either "PROC=" or "SUBPROC=" immediately before the name of the desired file, as in the following two examples:

00900 CHAIN "PROC=GLPOST"

00080 NAME$="EDITLIST.PRC"
00090 X$="SUBPROC=GLPROG\"&NAME$
00100 CHAIN X$

When a program chains to a procedure (PROC or SUBPROC), the procedure acts much like the operator stopped the program and started entering commands. A procedure is a set of commands. (However a procedure can skip forward or backward within itself.) While it is emulating a series of commands, the program that initiated the procedure is retained in memory even though the CHAIN statement terminated it. Therefore its variable contents are accessible to the procedure.

The following example specifies that the string array A$ and the numeric variables B and C are to retain their values in the chained-to program:

60000 CHAIN PROG$,MAT A$,B,C

===Syntax===
CHAIN {"<program name>"|”PROC=<name>”|”SUPROC=<name>”|”<path>\<name>”} [,FILES] [,MAT<array name>][,...] [,<variable name>][,...]

[[file:Chain.png|700px]]

===Defaults===
# Load and run a program.
# Close all open files (except procedure files).
# Set all variables in the chained-to program to blanks or zeros.

===Parameters===
The only required parameter of the CHAIN statement is the "file-ref", which specifies the program, procedure, or sub-procedure to be executed. This name and subdirectory information may be specified as a quoted literal string or as a string variable.

If the file-ref is preceded with the string "PROC=", the CHAIN initiates a procedure. If the file-ref is preceded with the string "SUBPROC=", the CHAIN initiates a sub-procedure. If neither of these keywords is present, the CHAIN statement attempts to load and run a program.

The differtence between PROC and SUBPROC is that PROC will close the current (lowest level) PROC file (if one is running) before starting the specifified procedure, whereas SUBPROC will not affect a currently running PROC file.

Following the file-ref information, CHAIN can take three optional parameters, but these parameters should be included only when chaining to a program.

"FILES" indicates that all files are to remain open and at their current positions. If you do not specify "FILES", the CHAIN statement closes all files except procedure files.

The "MAT array-name" and "variables" parameters allow the specified arrays or variables to retain their current values in the chained-to program. If several are used they are seperated by commas.

===Technical Considerations===
# Array variables and string variables passed between programs by a CHAIN statement, are not required to be dimensioned the same way in both programs. If dimensions do not match, the dimensions in the first program will override those in the DIM statements of the second program. However, it is recommended for improved readability that dimensions should match in both programs. Arrays may be re-dimensioned in the second program.
# Options selected in an OPTION statement are not required to be the same in both programs. However, it is strongly recommended that these options be the same. For example, if the first program uses BASE 1 and the second program uses BASE 0, confusing results could "run rampant" because the last element of a 10-element array would have a subscript of 10 in the first program and 9 in the second program.
# RUN command options, which are active in the initial program, will remain active in the chained program. These options include RUN PROC and output redirected to a file (see the RUN command for more information).
# In Business Rules, there is no need for a USE statement in the program being chained. USE is treated as a comment and is maintained only for compatibility with IBM Business BASIC.
# Although Business Rules checks most statements for proper syntax as they are entered, the file-ref parameter of the CHAIN statement is not checked until execution (this is also true in the OPEN statement). In this case, variables and quoted strings cannot be checked until execution. # IBM Business BASIC restricted the use of CHAIN statements within IF statements; if the THEN clause was a CHAIN statement, the ELSE clause was not permitted. This restriction does not apply to Business Rules. The following statement is allowed: 90 IF X=0 THEN CHAIN "MENU" ELSE CHAIN "PR2"
# The rules for the default extension of a program name, which is specified in a CHAIN statement, are the same as the rules for the LOAD command. In short, the system first looks for an extension of .BR; if that is not present, the system then looks for .BRO. You can change these defaults with the CHAINDFLT specification in the BRConfig.sys file. You can also override the defaults from within the CHAIN statement by specifying your own extension, as in the following example:900 CHAIN "C:\MAIN\MENU.OLD"
# The ability to pass specified variables from a program to a procedure is not explicitly supported in Business Rules because the values of all variables are available at the end of a program. These variables retain their values until a SORT, INDEX, CLEAR, or LOAD command is encountered from the keyboard or from a procedure file. This means that any variable from the calling program could be tested by a SKIP command (or therwise used) in a procedure file. (Notice that this also means those values of all variables are available to an opertor after program termination for interrogation [displaying contents] and debugging.)
# Like most Business Rules statements, CHAIN may be used in immediate mode like a command (except with the EXECUTE statement, where commands may not terminate a program.) Within a procedure, the following two commands are equivalent: PROC EOM - CHAIN "PROC=EOM". The next two commands would also be equivalent within a procedure: SUBPROC EOM - CHAIN "SUBPROC=EOM". Although using CHAIN, as a command may not seem very useful because the simpler PROC and SUBPROC alternatives exist, CHAIN allows a procedure to pass variables from it's parent or itself to a program. For example, a procedure file might start a program to print designated messages for certain completion codes as follows: LOAD PROG1 - RUN - X=CODE - SKIP 1 IF X=0 - CHAIN "MESSAGE", X. This passes the variable X (created by PROG1 or the procedure) to be passed to the program named MESSAGE. The same is true if a program CHAINS to a procedure and the procedure simply forwards variables from the chaining program to anotherr program.
# CHAIN "PROC=XYZ" is similar to EXECUTE "PROC XYZ", except EXECUTE does not end the program. That being said, the procedure has the authority to end the program that called it via EXECUTE.
# If the FILES keyword is used to keep files open, file pointers are not moved. Thus, pointers, which were at the end of the file in the first program, will also be at the end of the file in the second program; you may use a RESTORE statement to reposition a file pointer.

<noinclude>
[[Category:Ending Programs Statements]]
[[Category:Statements]]
</noinclude>

Chain

2024-08-27T03:52:04Z

Gordon.dye: /* Comments and Examples */

The '''Chain''' (CH) [[statement]] ends the current program and starts execution of another program, procedure, or sub-procedure.

===Comments and Examples===
CHAIN is most often used to chain from one program to another. To do this you just type CHAIN and indicate the name of the desired program.

The statement in the following example causes the system to end the current program and load the program MENU.BR (or MENU.BRO) from a subdirectory called MAIN:

00350 CHAIN "MAIN\MENU"

The next example loads and runs the program GLEDIT.BR (or GLEDIT.BRO) from the subdirectory GLPROG (a subdirectory of the root directory). All files stay open at their current positions. The variable D$ retains its current value at the start of the new program; all other variables return to zeros or null strings.

00900 CHAIN "C:\GLPROG\GLEDIT" ,FILES,D$

To chain from a program to a procedure or sub-procedure (rather than another program), you must have either "PROC=" or "SUBPROC=" immediately before the name of the desired file, as in the following two examples:

00900 CHAIN "PROC=GLPOST"

00080 NAME$="EDITLIST.PRC"
00090 X$="SUBPROC=GLPROG\"&NAME$
00100 CHAIN X$

When a program chains to a procedure (PROC or SUBPROC), the procedure acts much like the operator stopped the program and started entering commands. A procedure is a set of commands. (However a procedure can skip forward or backward within itself.) While it is emulating a series of commands, the program that initiated the procedure is retained in memory even though the CHAIN statement terminated it. Therefore its variable contents are accessible to the procedure.

The following example specifies that the string array A$ and the numeric variables B and C are to retain their values in the chained-to program:

60000 CHAIN PROG$,MAT A$,B,C

===Syntax===
CHAIN {"<program name>"|”PROC=<name>”|”SUPROC=<name>”|”<path>\<name>”} [,FILES] [,MAT<array name>][,...] [,<variable name>][,...]

[[file:Chain.png|700px]]

===Defaults===
# Load and run a program.
# Close all open files (except procedure files).
# Set all variables in the chained-to program to blanks or zeros.

===Parameters===
The only required parameter of the CHAIN statement is the "file-ref", which specifies the program, procedure, or sub-procedure to be executed. This name and subdirectory information may be specified as a quoted literal string or as a string variable.

If the file-ref is preceded with the string "PROC=", the CHAIN initiates a procedure. If the file-ref is preceded with the string "SUBPROC=", the CHAIN initiates a sub-procedure. If neither of these keywords is present, the CHAIN statement attempts to load and run a program.

The differtence between PROC and SUBPROC is that PROC will close the current (lowest level) PROC file (if one is running) before starting the specifified procedure, whereas SUBPROC will not affect a currently running PROC file.

Following the file-ref information, CHAIN can take three optional parameters, but these parameters should be included only when chaining to a program.

"FILES" indicates that all files are to remain open and at their current positions. If you do not specify "FILES", the CHAIN statement closes all files except procedure files.

The "MAT array-name" and "variables" parameters allow the specified arrays or variables to retain their current values in the chained-to program. If several are used they are seperated by commas.

===Technical Considerations===
# Array variables and string variables passed between programs by a CHAIN statement, are not required to be dimensioned the same way in both programs. If dimensions do not match, the dimensions in the first program will override those in the DIM statements of the second program. However, it is recommended for improved readability that dimensions should match in both programs. Arrays may be re-dimensioned in the second program.
# Options selected in an OPTION statement are not required to be the same in both programs. However, it is strongly recommended that these options be the same. For example, if the first program uses BASE 1 and the second program uses BASE 0, confusing results could "run rampant" because the last element of a 10-element array would have a subscript of 10 in the first program and 9 in the second program.
# RUN command options, which are active in the initial program, will remain active in the chained program. These options include RUN PROC and output redirected to a file (see the RUN command for more information).
# In Business Rules, there is no need for a USE statement in the program being chained. USE is treated as a comment and is maintained only for compatibility with IBM Business BASIC.
# Although Business Rules checks most statements for proper syntax as they are entered, the file-ref parameter of the CHAIN statement is not checked until execution (this is also true in the OPEN statement). In this case, variables and quoted strings cannot be checked until execution. Execution errors may arise from text entered as literally inside quotes. The same errors result when a string variable is used as the file-ref if that string does not validly specify an existing file.
# IBM Business BASIC restricted the use of CHAIN statements within IF statements; if the THEN clause was a CHAIN statement, the ELSE clause was not permitted. This restriction does not apply to Business Rules. The following statement is allowed: 90 IF X=0 THEN CHAIN "MENU" ELSE CHAIN "PR2"
# The rules for the default extension of a program name, which is specified in a CHAIN statement, are the same as the rules for the LOAD command. In short, the system first looks for an extension of .BR; if that is not present, the system then looks for .BRO. You can change these defaults with the CHAINDFLT specification in the BRConfig.sys file. You can also override the defaults from within the CHAIN statement by specifying your own extension, as in the following example:900 CHAIN "C:\MAIN\MENU.OLD"
# The ability to pass specified variables from a program to a procedure is not explicitly supported in Business Rules because all values of all variables are available at the end of a program. These variables retain their values until a SORT, INDEX, CLEAR, or LOAD command is encountered from the keyboard or from a procedure file. This means that any variable from the previous program could be tested by a SKIP command in a procedure file. (Notice that this also means those values of all variables are still available after program termination for printing and debugging.)
# Like most Business Rules statements, CHAIN may be used in immediate mode like a command (except with the EXECUTE statement, where commands may not terminate a program.) Within a procedure, the following two commands are equivalent: PROC EOM - CHAIN "PROC=EOM"The next two commands would also be equivalent within a procedure: SUBPROC EOM - CHAIN "SUBPROC=EOM" Although using CHAIN, as a command may not seem very useful because the simpler PROC and SUBPROC alternatives exist, it does allow for variables to be passed from a procedure to a program. For example, a procedure file might start a program to print designated messages for certain completion codes as follows: LOAD PROG1 - RUN - X=CODE - SKIP 1 IF X=0 - CHAIN "MESSAGE", X
# If the FILES keyword is used to keep files open, file pointers are not moved. Thus, pointers, which were at the end of the file in the first program, will also be at the end of the file in the second program; you may use a RESTORE statement to reposition a file pointer.

<noinclude>
[[Category:Ending Programs Statements]]
[[Category:Statements]]
</noinclude>

Chain

2024-08-27T03:29:14Z

Gordon.dye: /* Parameters */

The '''Chain''' (CH) [[statement]] ends the current program and starts execution of another program, procedure, or sub-procedure.

===Comments and Examples===
CHAIN is most often used to chain from one program to another. To do this you just type CHAIN and indicate the name of the desired program.

The statement in the following example causes the system to end the current program and load the program MENU.BR (or MENU.BRO) from a subdirectory called MAIN:

00350 CHAIN "MAIN\MENU"

The next example loads and runs the program GLEDIT.BR (or GLEDIT.BRO) from the subdirectory GLPROG (a subdirectory of the root directory). All files stay open at their current positions. The variable D$ retains its current value at the start of the new program; all other variables return to zeros or null strings.

00900 CHAIN "C:\GLPROG\GLEDIT" ,FILES,D$

To chain from a program to a procedure or sub-procedure (rather than another program), you must have either "PROC=" or "SUBPROC=" immediately before the name of the desired file, as in the following two examples:

00900 CHAIN "PROC=GLPOST"

00080 NAME$="EDITLIST"
00090 X$="SUBPROC=GLPROG\"&NAME$
00100 CHAIN X$

The following example specifies that the string array A$ and the numeric variables B and C are to retain their values in the chained-to program:

60000 CHAIN PROG$,MAT A$,B,C

===Syntax===
CHAIN {"<program name>"|”PROC=<name>”|”SUPROC=<name>”|”<path>\<name>”} [,FILES] [,MAT<array name>][,...] [,<variable name>][,...]

[[file:Chain.png|700px]]

===Defaults===
# Load and run a program.
# Close all open files (except procedure files).
# Set all variables in the chained-to program to blanks or zeros.

===Parameters===
The only required parameter of the CHAIN statement is the "file-ref", which specifies the program, procedure, or sub-procedure to be executed. This name and subdirectory information may be specified as a quoted literal string or as a string variable.

If the file-ref is preceded with the string "PROC=", the CHAIN initiates a procedure. If the file-ref is preceded with the string "SUBPROC=", the CHAIN initiates a sub-procedure. If neither of these keywords is present, the CHAIN statement attempts to load and run a program.

The differtence between PROC and SUBPROC is that PROC will close the current (lowest level) PROC file (if one is running) before starting the specifified procedure, whereas SUBPROC will not affect a currently running PROC file.

Following the file-ref information, CHAIN can take three optional parameters, but these parameters should be included only when chaining to a program.

"FILES" indicates that all files are to remain open and at their current positions. If you do not specify "FILES", the CHAIN statement closes all files except procedure files.

The "MAT array-name" and "variables" parameters allow the specified arrays or variables to retain their current values in the chained-to program. If several are used they are seperated by commas.

===Technical Considerations===
# Array variables and string variables passed between programs by a CHAIN statement, are not required to be dimensioned the same way in both programs. If dimensions do not match, the dimensions in the first program will override those in the DIM statements of the second program. However, it is recommended for improved readability that dimensions should match in both programs. Arrays may be re-dimensioned in the second program.
# Options selected in an OPTION statement are not required to be the same in both programs. However, it is strongly recommended that these options be the same. For example, if the first program uses BASE 1 and the second program uses BASE 0, confusing results could "run rampant" because the last element of a 10-element array would have a subscript of 10 in the first program and 9 in the second program.
# RUN command options, which are active in the initial program, will remain active in the chained program. These options include RUN PROC and output redirected to a file (see the RUN command for more information).
# In Business Rules, there is no need for a USE statement in the program being chained. USE is treated as a comment and is maintained only for compatibility with IBM Business BASIC.
# Although Business Rules checks most statements for proper syntax as they are entered, the file-ref parameter of the CHAIN statement is not checked until execution (this is also true in the OPEN statement). In this case, variables and quoted strings cannot be checked until execution. Execution errors may arise from text entered as literally inside quotes. The same errors result when a string variable is used as the file-ref if that string does not validly specify an existing file.
# IBM Business BASIC restricted the use of CHAIN statements within IF statements; if the THEN clause was a CHAIN statement, the ELSE clause was not permitted. This restriction does not apply to Business Rules. The following statement is allowed: 90 IF X=0 THEN CHAIN "MENU" ELSE CHAIN "PR2"
# The rules for the default extension of a program name, which is specified in a CHAIN statement, are the same as the rules for the LOAD command. In short, the system first looks for an extension of .BR; if that is not present, the system then looks for .BRO. You can change these defaults with the CHAINDFLT specification in the BRConfig.sys file. You can also override the defaults from within the CHAIN statement by specifying your own extension, as in the following example:900 CHAIN "C:\MAIN\MENU.OLD"
# The ability to pass specified variables from a program to a procedure is not explicitly supported in Business Rules because all values of all variables are available at the end of a program. These variables retain their values until a SORT, INDEX, CLEAR, or LOAD command is encountered from the keyboard or from a procedure file. This means that any variable from the previous program could be tested by a SKIP command in a procedure file. (Notice that this also means those values of all variables are still available after program termination for printing and debugging.)
# Like most Business Rules statements, CHAIN may be used in immediate mode like a command (except with the EXECUTE statement, where commands may not terminate a program.) Within a procedure, the following two commands are equivalent: PROC EOM - CHAIN "PROC=EOM"The next two commands would also be equivalent within a procedure: SUBPROC EOM - CHAIN "SUBPROC=EOM" Although using CHAIN, as a command may not seem very useful because the simpler PROC and SUBPROC alternatives exist, it does allow for variables to be passed from a procedure to a program. For example, a procedure file might start a program to print designated messages for certain completion codes as follows: LOAD PROG1 - RUN - X=CODE - SKIP 1 IF X=0 - CHAIN "MESSAGE", X
# If the FILES keyword is used to keep files open, file pointers are not moved. Thus, pointers, which were at the end of the file in the first program, will also be at the end of the file in the second program; you may use a RESTORE statement to reposition a file pointer.

<noinclude>
[[Category:Ending Programs Statements]]
[[Category:Statements]]
</noinclude>

Chain

2024-08-27T03:10:49Z

Gordon.dye: /* Syntax */

The '''Chain''' (CH) [[statement]] ends the current program and starts execution of another program, procedure, or sub-procedure.

===Comments and Examples===
CHAIN is most often used to chain from one program to another. To do this you just type CHAIN and indicate the name of the desired program.

The statement in the following example causes the system to end the current program and load the program MENU.BR (or MENU.BRO) from a subdirectory called MAIN:

00350 CHAIN "MAIN\MENU"

The next example loads and runs the program GLEDIT.BR (or GLEDIT.BRO) from the subdirectory GLPROG (a subdirectory of the root directory). All files stay open at their current positions. The variable D$ retains its current value at the start of the new program; all other variables return to zeros or null strings.

00900 CHAIN "C:\GLPROG\GLEDIT" ,FILES,D$

To chain from a program to a procedure or sub-procedure (rather than another program), you must have either "PROC=" or "SUBPROC=" immediately before the name of the desired file, as in the following two examples:

00900 CHAIN "PROC=GLPOST"

00080 NAME$="EDITLIST"
00090 X$="SUBPROC=GLPROG\"&NAME$
00100 CHAIN X$

The following example specifies that the string array A$ and the numeric variables B and C are to retain their values in the chained-to program:

60000 CHAIN PROG$,MAT A$,B,C

===Syntax===
CHAIN {"<program name>"|”PROC=<name>”|”SUPROC=<name>”|”<path>\<name>”} [,FILES] [,MAT<array name>][,...] [,<variable name>][,...]

[[file:Chain.png|700px]]

===Defaults===
# Load and run a program.
# Close all open files (except procedure files).
# Set all variables in the chained-to program to blanks or zeros.

===Parameters===
The only required parameter of the CHAIN statement is the "file-ref", which specifies the program, procedure, or sub-procedure to be executed. This name and subdirectory information may be specified as a quoted literal string or as a string variable. If the file-ref is preceded with the string "PROC=", the CHAIN initiates a procedure. If the file-ref is preceded with the string "SUBPROC=", the CHAIN initiates a sub-procedure. If neither of these is present, the CHAIN statement attempts to load and run a program.

Following the file-ref information, CHAIN can take three optional parameters, but these parameters should be included only when chaining to a program.

"FILES" indicates that all files are to remain open and at their current positions. If you do not specify "FILES", the CHAIN statement closes all files except procedure files.

The "MAT array-name" and "variables" parameters allow the specified arrays or variables to retain their current values in the chained program. If several are used they are seperated by commas.

===Technical Considerations===
# Array variables and string variables passed between programs by a CHAIN statement, are not required to be dimensioned the same way in both programs. If dimensions do not match, the dimensions in the first program will override those in the DIM statements of the second program. However, it is recommended for improved readability that dimensions should match in both programs. Arrays may be re-dimensioned in the second program.
# Options selected in an OPTION statement are not required to be the same in both programs. However, it is strongly recommended that these options be the same. For example, if the first program uses BASE 1 and the second program uses BASE 0, confusing results could "run rampant" because the last element of a 10-element array would have a subscript of 10 in the first program and 9 in the second program.
# RUN command options, which are active in the initial program, will remain active in the chained program. These options include RUN PROC and output redirected to a file (see the RUN command for more information).
# In Business Rules, there is no need for a USE statement in the program being chained. USE is treated as a comment and is maintained only for compatibility with IBM Business BASIC.
# Although Business Rules checks most statements for proper syntax as they are entered, the file-ref parameter of the CHAIN statement is not checked until execution (this is also true in the OPEN statement). In this case, variables and quoted strings cannot be checked until execution. Execution errors may arise from text entered as literally inside quotes. The same errors result when a string variable is used as the file-ref if that string does not validly specify an existing file.
# IBM Business BASIC restricted the use of CHAIN statements within IF statements; if the THEN clause was a CHAIN statement, the ELSE clause was not permitted. This restriction does not apply to Business Rules. The following statement is allowed: 90 IF X=0 THEN CHAIN "MENU" ELSE CHAIN "PR2"
# The rules for the default extension of a program name, which is specified in a CHAIN statement, are the same as the rules for the LOAD command. In short, the system first looks for an extension of .BR; if that is not present, the system then looks for .BRO. You can change these defaults with the CHAINDFLT specification in the BRConfig.sys file. You can also override the defaults from within the CHAIN statement by specifying your own extension, as in the following example:900 CHAIN "C:\MAIN\MENU.OLD"
# The ability to pass specified variables from a program to a procedure is not explicitly supported in Business Rules because all values of all variables are available at the end of a program. These variables retain their values until a SORT, INDEX, CLEAR, or LOAD command is encountered from the keyboard or from a procedure file. This means that any variable from the previous program could be tested by a SKIP command in a procedure file. (Notice that this also means those values of all variables are still available after program termination for printing and debugging.)
# Like most Business Rules statements, CHAIN may be used in immediate mode like a command (except with the EXECUTE statement, where commands may not terminate a program.) Within a procedure, the following two commands are equivalent: PROC EOM - CHAIN "PROC=EOM"The next two commands would also be equivalent within a procedure: SUBPROC EOM - CHAIN "SUBPROC=EOM" Although using CHAIN, as a command may not seem very useful because the simpler PROC and SUBPROC alternatives exist, it does allow for variables to be passed from a procedure to a program. For example, a procedure file might start a program to print designated messages for certain completion codes as follows: LOAD PROG1 - RUN - X=CODE - SKIP 1 IF X=0 - CHAIN "MESSAGE", X
# If the FILES keyword is used to keep files open, file pointers are not moved. Thus, pointers, which were at the end of the file in the first program, will also be at the end of the file in the second program; you may use a RESTORE statement to reposition a file pointer.

<noinclude>
[[Category:Ending Programs Statements]]
[[Category:Statements]]
</noinclude>

SpoolCmd

2024-08-08T03:52:25Z

Gordon.dye: /* Syntax */

SPOOLCMD is mainly useful for producing print files for Linux and MAC systems. In Windows systems the DIRECT://printer-name is preferred. Also see the [[PRINTING]] section.

Basically, SpoolCmd provides a description of how to print data sent to the printer.

Business Rules supports independent spoolers on all systems. The [[BRConfig.sys]] SPOOLCMD specification will make a [[shell call]] to issue the necessary spool command whenever printing is done. When this is invoked the spooler is responsible for removing the spool file created by Business Rules.

====Syntax====
SPOOLCMD spool-program [SPOOLFILE] [NAME=<name>] [QUEUE] [PRINTER] [COPIES] [WSID] [PROGRAM]

The spool command and its parameters can be specified in a [[CONFIG]] command or in the [[BRConfig.sys]] file as follows:

[[file:Spoolcmd.png|750px]]

Business Rules can also make substitutions as follows in parameters specified with SPOOLCMD (they're all optional):

'''[SPOOLFILE]''' substitutes the name of the spool file, as determined by Business Rules.

'''[NAME=]''' substitutes the name of the printer file as specified in the OPEN display statement's NAME= string. For example, PRN:/10.

'''[QUEUE]''' substitutes the queue name as specified in the OPEN display statement. In the following example, "queue" would be substituted for [QUEUE]: PRN:queue/10.

'''[PRINTER]''' substitutes the "printerclass" string as specified in the [[OPEN display]] statement. For example, PRN:/printerclass.

'''[COPIES]''' substitutes the value of the COPIES= parameter as specified in the OPEN display statement.

'''[WSID]''' substitutes the user's workstation ID.

'''[PROGRAM]''' substitutes the name of the program that is loaded at the time that the printer is closed.

The '''[QUEUE]''' and '''[PRINTER]''' parameters can be used almost interchangeably. They are simply a versatile way to pass specifications from the Open (or SUBSTITUTE) statement to the spooler.

NOTE: The spoolfile created by Business Rules will not automatically be deleted.

SPOOLCMD supports the -w flag which avoids the use of a DOS shell command when calling Windows applications directly. The Windows Client SPOOLCMD syntax is:

SPOOLCMD [@] [-w] command parm-1 parm-2 ...

SPOOLCMD honors BR drive substitution on the command itself, for example:
DRIVE J:,M:\myapp,j,\
SPOOLCMD J:\mylib\spooler [SPOOLFILE] [COPIES]

This finds 'spooler' in M:\myapp\mylib.

See also:
*[[SpoolFile]]
*[[SpoolPath]]

====Config Spoolcmd====
As of 4.3, the [[CONFIG]] command supports the SPOOLCMD spec, which enables any system spooler to work with BR. See the "SPOOLCMD" specification in the BRConfig.sys Specification section for additional information. On DOS and NetWork versions, OPENs to PRN: will return error [[6298]] when the following two conditions are true:

:1) SPOOLCMD is not specified
:2) The printer is not ready.

<noinclude>
[[Category:Config]]
</noinclude>

Chain

2024-03-03T06:23:29Z

Gordon.dye: /* Syntax */

The '''Chain''' (CH) [[statement]] ends the current program and starts execution of another program, procedure, or sub-procedure.

===Comments and Examples===
CHAIN is most often used to chain from one program to another. To do this you just type CHAIN and indicate the name of the desired program.

The statement in the following example causes the system to end the current program and load the program MENU.BR (or MENU.BRO) from a subdirectory called MAIN:

00350 CHAIN "MAIN\MENU"

The next example loads and runs the program GLEDIT.BR (or GLEDIT.BRO) from the subdirectory GLPROG (a subdirectory of the root directory). All files stay open at their current positions. The variable D$ retains its current value at the start of the new program; all other variables return to zeros or null strings.

00900 CHAIN "C:\GLPROG\GLEDIT" ,FILES,D$

To chain from a program to a procedure or sub-procedure (rather than another program), you must have either "PROC=" or "SUBPROC=" immediately before the name of the desired file, as in the following two examples:

00900 CHAIN "PROC=GLPOST"

00080 NAME$="EDITLIST"
00090 X$="SUBPROC=GLPROG\"&NAME$
00100 CHAIN X$

The following example specifies that the string array A$ and the numeric variables B and C are to retain their values in the chained-to program:

60000 CHAIN PROG$,MAT A$,B,C

===Syntax===
CHAIN {"<program name>"|”PROC=<name>”|”SUPROC=<name>”|”<path>\<name>”} [,FILES] [,MAT<array name>][,...] [,<variables>][,...]

[[file:Chain.png|700px]]

===Defaults===
# Load and run a program.
# Close all open files (except procedure files).
# Set all variables in the chained-to program to blanks or zeros.

===Parameters===
The only required parameter of the CHAIN statement is the "file-ref", which specifies the program, procedure, or sub-procedure to be executed. This name and subdirectory information may be specified as a quoted literal string or as a string variable. If the file-ref is preceded with the string "PROC=", the CHAIN initiates a procedure. If the file-ref is preceded with the string "SUBPROC=", the CHAIN initiates a sub-procedure. If neither of these is present, the CHAIN statement attempts to load and run a program.

Following the file-ref information, CHAIN can take three optional parameters, but these parameters should be included only when chaining to a program.

"FILES" indicates that all files are to remain open and at their current positions. If you do not specify "FILES", the CHAIN statement closes all files except procedure files.

The "MAT array-name" and "variables" parameters allow the specified arrays or variables to retain their current values in the chained program. If several are used they are seperated by commas.

===Technical Considerations===
# Array variables and string variables passed between programs by a CHAIN statement, are not required to be dimensioned the same way in both programs. If dimensions do not match, the dimensions in the first program will override those in the DIM statements of the second program. However, it is recommended for improved readability that dimensions should match in both programs. Arrays may be re-dimensioned in the second program.
# Options selected in an OPTION statement are not required to be the same in both programs. However, it is strongly recommended that these options be the same. For example, if the first program uses BASE 1 and the second program uses BASE 0, confusing results could "run rampant" because the last element of a 10-element array would have a subscript of 10 in the first program and 9 in the second program.
# RUN command options, which are active in the initial program, will remain active in the chained program. These options include RUN PROC and output redirected to a file (see the RUN command for more information).
# In Business Rules, there is no need for a USE statement in the program being chained. USE is treated as a comment and is maintained only for compatibility with IBM Business BASIC.
# Although Business Rules checks most statements for proper syntax as they are entered, the file-ref parameter of the CHAIN statement is not checked until execution (this is also true in the OPEN statement). In this case, variables and quoted strings cannot be checked until execution. Execution errors may arise from text entered as literally inside quotes. The same errors result when a string variable is used as the file-ref if that string does not validly specify an existing file.
# IBM Business BASIC restricted the use of CHAIN statements within IF statements; if the THEN clause was a CHAIN statement, the ELSE clause was not permitted. This restriction does not apply to Business Rules. The following statement is allowed: 90 IF X=0 THEN CHAIN "MENU" ELSE CHAIN "PR2"
# The rules for the default extension of a program name, which is specified in a CHAIN statement, are the same as the rules for the LOAD command. In short, the system first looks for an extension of .BR; if that is not present, the system then looks for .BRO. You can change these defaults with the CHAINDFLT specification in the BRConfig.sys file. You can also override the defaults from within the CHAIN statement by specifying your own extension, as in the following example:900 CHAIN "C:\MAIN\MENU.OLD"
# The ability to pass specified variables from a program to a procedure is not explicitly supported in Business Rules because all values of all variables are available at the end of a program. These variables retain their values until a SORT, INDEX, CLEAR, or LOAD command is encountered from the keyboard or from a procedure file. This means that any variable from the previous program could be tested by a SKIP command in a procedure file. (Notice that this also means those values of all variables are still available after program termination for printing and debugging.)
# Like most Business Rules statements, CHAIN may be used in immediate mode like a command (except with the EXECUTE statement, where commands may not terminate a program.) Within a procedure, the following two commands are equivalent: PROC EOM - CHAIN "PROC=EOM"The next two commands would also be equivalent within a procedure: SUBPROC EOM - CHAIN "SUBPROC=EOM" Although using CHAIN, as a command may not seem very useful because the simpler PROC and SUBPROC alternatives exist, it does allow for variables to be passed from a procedure to a program. For example, a procedure file might start a program to print designated messages for certain completion codes as follows: LOAD PROG1 - RUN - X=CODE - SKIP 1 IF X=0 - CHAIN "MESSAGE", X
# If the FILES keyword is used to keep files open, file pointers are not moved. Thus, pointers, which were at the end of the file in the first program, will also be at the end of the file in the second program; you may use a RESTORE statement to reposition a file pointer.

<noinclude>
[[Category:Ending Programs Statements]]
[[Category:Statements]]
</noinclude>

Run

2024-02-28T19:34:45Z

Gordon.dye: /* Parameters */

The '''Run (RU)''' [[command]] begins execution of a program. When RUN is used to redirect printer output to a file or screen (RUN> filename) the redirection is now stopped only when the system returns to READY mode (when no programs or procedures remain active). This allows redirection to work with a procedure file that contains multiple RUN commands. Previously, the redirection remained active only until the next RUN command was issued.

==Comments and Examples==

RUN sets all variables to zero (or zero length) and begins executing at the lowest line number of the program. Open files stay open. Execution halts and an error message is displayed on the status line when an error occurs during program execution.

A running program stops when it reaches a STOP, END, or CHAIN statement within the program; all open files close (except when the optional FILES parameter is used in a CHAIN statement). A running program pauses when it reaches a PAUSE statement or when you press the Ctrl-A key combination. To resume execution, enter a GO command (see the options for the GO command in the GO section of this chapter).

The following command begins execution of the program in memory at line 350:

RUN 350

The next command executes the program in memory and sends all printer output to the file REPORT. The use of the double redirection arrow (>>) causes the output to be appended to the end of REPORT (rather than to overwrite it):

RUN >>REPORT

The command below begins execution of the program in memory and directs printer output to the screen:

RUN >CON:

The following command loads and begins execution of the program SCORE. All TRACE output is sent to the printer.

RUN B:SCORE TRACE PRINT

==Syntax==
RUN <file name> [ [[TRACE]] [PRINT]][...] [{[[STEP]]|[[PROC]]|<[[line number]]>|>[>]<file name>}[...]

[[Image:Run.png]]

==Defaults==

# RUN the program currently in memory.
# Send TRACE output to the screen.

==Parameters==

{|
|-valign="top"
|width="10%"|'''"File-name"'''|| is the name and path of the file you wish to run. BR to see that the named file exists, then performs a CLEAR operation and loads and begins executing the specified file. File names which are the same as any of RUN's parameters (TRACE, PRINT, STEP or PROC) cannot be specified with the RUN command. Also, file names that are also numbers cannot be specified with RUN (the number will be interpreted as a "line-num" parameter -see below) unless the extension is also specified (i.e., RUN 123.BR). It is important to note that the system will always clear current memory and load the specified file, even if that file is currently in memory -thus the potential exists for losing unstored program lines.
|-valign="top"
|}

{|
|-valign="top"
|width="10%"|'''"TRACE" '''||displays the line number of each line as it is being executed. Unlike STEP, it does not cause the program to pause before executing each statement. This parameter is very useful for debugging purposes. To turn TRACE off, you must interrupt BR (Ctrl-A) and use GO RUN to continue execution.
|-valign="top"
|}

{|
|-valign="top"
|width="10%"|'''"PRINT" '''||sends TRACE output to an attached printer.
|-valign="top"
|}

{|
|-valign="top"
|width="10%"|'''"STEP" '''||pauses the program before each statement is executed. The line number field in the status line tells you the next line number to be executed. That line is executed and the next line number appears when <CR> is pressed. STEP is useful for debugging of programs, as it allows you to closely follow the program's flow.
|-valign="top"
|}

{|
|-valign="top"
|width="10%"|'''"PROC" '''||accept input from the procedure file that contains this command, for all INPUT, LINPUT, and RINPUT statements. Normally the input for these statements would come from the keyboard. The RUN PROC option has no effect on INPUT FIELDS or RINPUT FIELDS statements. (see Technical Considerations below)
|-valign="top"
|}

If you wish to start running the program from a point other than the beginning, you can use "line-num" to specify the first line of execution.

"File_ref saves to a file all program output that normally goes to the printer. Use of one redirection arrow (>) causes output to overwrite the contents of the specified file. Two redirection arrows (>>) cause the output to be appended to the end of the specified file.

The >file-ref can also redirect printer output to other communications devices. To send output to the screen, for example, use:

RUN >CON:

To send it to whatever device is connected to the first communications port, use:

RUN >AUX:

These strings must be translated with the SUBSTITUTE specification for BR or Linux versions. BR sends all program results to the specified file-ref location until you enter another RUN command.

==Technical Considerations==

# BR closes a procedure before executing the last line. Thus when RUN file-ref is included as the last line, there is a clean trade-off in the number of open files on the system. But RUN PROC cannot be used as the last line because the procedure will be closed before the program starts to look for data in the procedure (an easy solution is to add a comment line ( ! - exclamation point ) after the RUN PROC command).
# RUN >file-ref remains in effect until another RUN command is issued. Output redirected to a file is not accessible until the file is closed by another RUN command.

<noinclude>
[[Category:Commands]]
[[Category:Program Management Commands]]
</noinclude>

Run

2024-02-28T19:33:23Z

Gordon.dye: /* Technical Considerations */

The '''Run (RU)''' [[command]] begins execution of a program. When RUN is used to redirect printer output to a file or screen (RUN> filename) the redirection is now stopped only when the system returns to READY mode (when no programs or procedures remain active). This allows redirection to work with a procedure file that contains multiple RUN commands. Previously, the redirection remained active only until the next RUN command was issued.

==Comments and Examples==

RUN sets all variables to zero (or zero length) and begins executing at the lowest line number of the program. Open files stay open. Execution halts and an error message is displayed on the status line when an error occurs during program execution.

A running program stops when it reaches a STOP, END, or CHAIN statement within the program; all open files close (except when the optional FILES parameter is used in a CHAIN statement). A running program pauses when it reaches a PAUSE statement or when you press the Ctrl-A key combination. To resume execution, enter a GO command (see the options for the GO command in the GO section of this chapter).

The following command begins execution of the program in memory at line 350:

RUN 350

The next command executes the program in memory and sends all printer output to the file REPORT. The use of the double redirection arrow (>>) causes the output to be appended to the end of REPORT (rather than to overwrite it):

RUN >>REPORT

The command below begins execution of the program in memory and directs printer output to the screen:

RUN >CON:

The following command loads and begins execution of the program SCORE. All TRACE output is sent to the printer.

RUN B:SCORE TRACE PRINT

==Syntax==
RUN <file name> [ [[TRACE]] [PRINT]][...] [{[[STEP]]|[[PROC]]|<[[line number]]>|>[>]<file name>}[...]

[[Image:Run.png]]

==Defaults==

# RUN the program currently in memory.
# Send TRACE output to the screen.

==Parameters==

{|
|-valign="top"
|width="10%"|'''"File-name"'''|| is the name and path of the file you wish to run. BR to see that the named file exists, then performs a CLEAR operation and loads and begins executing the specified file. File names which are the same as any of RUN's parameters (TRACE, PRINT, STEP or PROC) cannot be specified with the RUN command. Also, file names that are also numbers cannot be specified with RUN (the number will be interpreted as a "line-num" parameter -see below) unless the extension is also specified (i.e., RUN 123.BR). It is important to note that the system will always clear current memory and load the specified file, even if that file is currently in memory -thus the potential exists for losing unstored program lines.
|-valign="top"
|}

{|
|-valign="top"
|width="10%"|'''"TRACE" '''||displays the line number of each line as it is being executed. Unlike STEP, it does not cause the program to pause before executing each statement. This parameter is very useful for debugging purposes. To turn TRACE off, you must interrupt BR (Ctrl-A) and use GO RUN to continue execution.
|-valign="top"
|}

{|
|-valign="top"
|width="10%"|'''"PRINT" '''||sends TRACE output to an attached printer.
|-valign="top"
|}

{|
|-valign="top"
|width="10%"|'''"STEP" '''||pauses the program before each statement is executed. The line number field in the status line tells you the next line number to be executed. That line is executed and the next line number appears when <CR> is pressed. STEP is useful for debugging of programs, as it allows you to closely follow the program's flow.
|-valign="top"
|}

{|
|-valign="top"
|width="10%"|'''"PROC" '''||accept input from the procedure file that contains this command, for all INPUT, LINPUT, and RINPUT statements. Normally the input for these statements would come from the keyboard. The RUN PROC option has no effect on INPUT FIELDS or RINPUT FIELDS statements.
|-valign="top"
|}

If you wish to start running the program from a point other than the beginning, you can use "line-num" to specify the first line of execution.

"File_ref saves to a file all program output that normally goes to the printer. Use of one redirection arrow (>) causes output to overwrite the contents of the specified file. Two redirection arrows (>>) cause the output to be appended to the end of the specified file.

The >file-ref can also redirect printer output to other communications devices. To send output to the screen, for example, use:

RUN >CON:

To send it to whatever device is connected to the first communications port, use:

RUN >AUX:

These strings must be translated with the SUBSTITUTE specification for BR or Linux versions. BR sends all program results to the specified file-ref location until you enter another RUN command.

==Technical Considerations==

# BR closes a procedure before executing the last line. Thus when RUN file-ref is included as the last line, there is a clean trade-off in the number of open files on the system. But RUN PROC cannot be used as the last line because the procedure will be closed before the program starts to look for data in the procedure (an easy solution is to add a comment line ( ! - exclamation point ) after the RUN PROC command).
# RUN >file-ref remains in effect until another RUN command is issued. Output redirected to a file is not accessible until the file is closed by another RUN command.

<noinclude>
[[Category:Commands]]
[[Category:Program Management Commands]]
</noinclude>

Run

2024-02-28T19:30:26Z

Gordon.dye: /* Parameters */

The '''Run (RU)''' [[command]] begins execution of a program. When RUN is used to redirect printer output to a file or screen (RUN> filename) the redirection is now stopped only when the system returns to READY mode (when no programs or procedures remain active). This allows redirection to work with a procedure file that contains multiple RUN commands. Previously, the redirection remained active only until the next RUN command was issued.

==Comments and Examples==

RUN sets all variables to zero (or zero length) and begins executing at the lowest line number of the program. Open files stay open. Execution halts and an error message is displayed on the status line when an error occurs during program execution.

A running program stops when it reaches a STOP, END, or CHAIN statement within the program; all open files close (except when the optional FILES parameter is used in a CHAIN statement). A running program pauses when it reaches a PAUSE statement or when you press the Ctrl-A key combination. To resume execution, enter a GO command (see the options for the GO command in the GO section of this chapter).

The following command begins execution of the program in memory at line 350:

RUN 350

The next command executes the program in memory and sends all printer output to the file REPORT. The use of the double redirection arrow (>>) causes the output to be appended to the end of REPORT (rather than to overwrite it):

RUN >>REPORT

The command below begins execution of the program in memory and directs printer output to the screen:

RUN >CON:

The following command loads and begins execution of the program SCORE. All TRACE output is sent to the printer.

RUN B:SCORE TRACE PRINT

==Syntax==
RUN <file name> [ [[TRACE]] [PRINT]][...] [{[[STEP]]|[[PROC]]|<[[line number]]>|>[>]<file name>}[...]

[[Image:Run.png]]

==Defaults==

# RUN the program currently in memory.
# Send TRACE output to the screen.

==Parameters==

{|
|-valign="top"
|width="10%"|'''"File-name"'''|| is the name and path of the file you wish to run. BR to see that the named file exists, then performs a CLEAR operation and loads and begins executing the specified file. File names which are the same as any of RUN's parameters (TRACE, PRINT, STEP or PROC) cannot be specified with the RUN command. Also, file names that are also numbers cannot be specified with RUN (the number will be interpreted as a "line-num" parameter -see below) unless the extension is also specified (i.e., RUN 123.BR). It is important to note that the system will always clear current memory and load the specified file, even if that file is currently in memory -thus the potential exists for losing unstored program lines.
|-valign="top"
|}

{|
|-valign="top"
|width="10%"|'''"TRACE" '''||displays the line number of each line as it is being executed. Unlike STEP, it does not cause the program to pause before executing each statement. This parameter is very useful for debugging purposes. To turn TRACE off, you must interrupt BR (Ctrl-A) and use GO RUN to continue execution.
|-valign="top"
|}

{|
|-valign="top"
|width="10%"|'''"PRINT" '''||sends TRACE output to an attached printer.
|-valign="top"
|}

{|
|-valign="top"
|width="10%"|'''"STEP" '''||pauses the program before each statement is executed. The line number field in the status line tells you the next line number to be executed. That line is executed and the next line number appears when <CR> is pressed. STEP is useful for debugging of programs, as it allows you to closely follow the program's flow.
|-valign="top"
|}

{|
|-valign="top"
|width="10%"|'''"PROC" '''||accept input from the procedure file that contains this command, for all INPUT, LINPUT, and RINPUT statements. Normally the input for these statements would come from the keyboard. The RUN PROC option has no effect on INPUT FIELDS or RINPUT FIELDS statements.
|-valign="top"
|}

If you wish to start running the program from a point other than the beginning, you can use "line-num" to specify the first line of execution.

"File_ref saves to a file all program output that normally goes to the printer. Use of one redirection arrow (>) causes output to overwrite the contents of the specified file. Two redirection arrows (>>) cause the output to be appended to the end of the specified file.

The >file-ref can also redirect printer output to other communications devices. To send output to the screen, for example, use:

RUN >CON:

To send it to whatever device is connected to the first communications port, use:

RUN >AUX:

These strings must be translated with the SUBSTITUTE specification for BR or Linux versions. BR sends all program results to the specified file-ref location until you enter another RUN command.

==Technical Considerations==

# BR closes a procedure before executing the last line. Thus when RUN file-ref is included as the last line, there is a clean trade-off in the number of open files on the system. But RUN PROC cannot be used as the last line because the procedure will be closed before the program starts to look for data in the procedure (an easy solution is to add a blank line or comment line after the RUN PROC command).
# The use of RUN PROC does not alter the forward slash's (/) capability of terminating INPUT, LINPUT and RINPUT statements. See the INPUT statement for additional information.
# RUN >file-ref remains in effect until another RUN command is issued. Output redirected to a file is not accessible until the file is closed by another RUN command.

<noinclude>
[[Category:Commands]]
[[Category:Program Management Commands]]
</noinclude>

Proc

2024-02-28T16:28:17Z

Gordon.dye: /* See Also */

The '''Proc''' [[command]] opens and begins execution of a [[Procedure|procedure]] file.

==Comments and Examples==

BR automatically closes the most recently executed, active procedure file before opening and executing the procedure file specified with the PROC command. If a procedure is executed from a sub-procedure, the calling sub-procedure is canceled, but its parent remains active.

The following command causes the procedure file PROCNAME, located on drive B, to be opened and executed:

PROC B:PROCNAME

The next command starts execution of the procedure file START. The asterisk prevents F2 logging of the commands within START.

PROC *START

==Syntax==
PROC {[[ECHO]]|[[NOECHO]]|<[[Procedure files|proc name]]>|*<[[Procedure files|proc name]]>}

[[Image:Proc.png]]

==Defaults==

# Log procedure commands for recall by the F2 key

==Parameters==
The '''ECHO''' parameter reverses the affects of the PROC NOECHO command.

The '''NOECHO''' parameter prevents procedure lines from being displayed on the screen as they are executed. This command will apply to all procedures until PROC ECHO is entered or until Business Rules is exited. 

The '''procedure file name''' parameter identifies the procedure file to be opened and executed. When '''procedure file name''' is preceded by an asterisk '''*''', command logging will be turned off. Thus pressing of the F2 key will recall the PROC command, but not the commands in the procedure.

==Technical Considerations==

# If an error occurs while PROC NOECHO is active, F2 and F3 can be used to recall and display the error-causing command.
# ALERT commands which are executed while PROC NOECHO is active will not be displayed on the screen. The operator must press F2 or F3 to view the message. Use of PROC ECHO before and PROC NOECHO after the ALERT command is recommended to avoid this situation.
# Each open procedure file counts as one open file against the operating system limit on open files.
# Business Rules closes a procedure before executing the last line in the procedure. This eliminates procedure stacking (and an added open file) in situations such as when one procedure ends with a SUBPROC command to call another procedure, or when RUN is the last command in a procedure, or when a procedure has only one command.
# As the procedure file is closed before the last command is executed, the last command cannot be a SKIP to branch back to an earlier part of the procedure. If you want to end with an option to branch backward, you must add another line (such as a blank line or a remark) to keep the procedure file open.
# {{:$$$}}

===See Also===
[[CLEAR]] PROC command.

[[ProcIn|PROCIN]] system function.

<noinclude>
[[Category:Commands]]
[[Category:Procedure Commands]]
</noinclude>

CurRow

2024-02-05T05:32:12Z

Gordon.dye:

CURROW

The '''CURROW''' internal function returns the cursor's row from last [[Input Fields]] or [[RInput Fields]] statement.

CURROW and [[CURCOL]] return the row or column (within a window) of the first character position of the control being exited. However, if the control is a LIST or GRID then CURROW and CURCOL identify the cell that was exited relative to the control itself (see [[Grid and List]]). (OPTION 59 provides the exact position of the mouse click.)

===Comments and Examples===

00100 DIM ALL$*1920
00110 INPUT FIELDS "1,1,c 1920,u": ALL$
00120 PRINT "Cursor ended on ROW"; CURROW
00130 PRINT "Cursor ended on COLUMN"; CURCOL
00140 PRINT "Cursor ended on FIELD"; CURFLD

In the sample program above, the entire screen is treated as one 1920-character input field. The operator can move the cursor to any of the 24 rows or any of the 80 columns. After the operator hits the <ENTER> key, line 120 will print the row number containing the cursor when input was ended. Also, line 130 will print the column number. Line 140 will print field 1 because there is only one large field in this example.

===Related Functions===

*[[CurCol]]
*[[CurFld]]
*[[CurWindow]]
*[[NxtRow]]
*[[NxtCol]]
*[[Next (Internal Function)]]

<noinclude>
[[Category:Internal Functions]]
</noinclude>

Grid and List

2024-02-05T05:25:45Z

Gordon.dye: /* FKey Processing */

This discussion assumes the reader has a clear understanding of [[INPUT FIELDS]] and [[PRINT FIELDS]] processing with simple fields.

'''Grid''' and '''List''' (a.k.a. '''ListView''') are [[Two dimensional controls]], which means that they contain rows and columns. GRIDs are normally used for data entry, while LISTs are used only for selection. In Business Rules, outputting to these controls is done with [[Print Fields]] and inputting from them is done with [[Input Fields]]. Each field specification pertains to one [[Control]]. However, a single FIELD specification can pertain to a parenthesized group of arrays. When using Grids and Lists, first the header must be populated, and then the data within the rows.

The [[INPUT FIELDS]] specification states Grid or List as the field type. The display area is specified in terms of rows and columns separated by a slash. The following parameter, instead of being leading field attributes, is a secondary keyword indicating the type (CNT/SUB/CELL/ROWCNT/ROWSUB/ROW) of output or input operation to be performed. The next parameter further qualifies the IO operation (CHG/SEL/ALL/CUR/NEXT). Normally this trailing attribute is an [[FKEY]] value which is shifted right one parameter in this context.

It is useful to work with [[2D Controls]] in terms of rows versus cells, particularly when the columns are dissimilar. A complete set of row oriented parameters are provided for that purpose. Output operations support the mass populating of 2D controls row by row. And input operations can be row oriented as well. The keywords associated with row processing are R, ROWCNT, ROWSUB, and ROW.

RINPUT does not work with 2D controls because the output statements are somewhat different from the input statements. The output consists of setting up the columns, including providing the column headings, and populating the control with data. The input consists of identifying what has changed in a manner that enables selective data retrieval and corresponding file updating.

If the user clicks on a column heading the GRID or LIST will be sorted on that column. Sorting is done in terms of rows. Such sorting of these controls has no affect on the BR program. The information returned to BR will be as though no sorting were performed. If a control's population is increased by populating with the plus (+) flag, the control will be resequenced back to its original order before the data is added. One way a program can restore the original displayed order of a GRID or LIST is to populate it incrementally (+) with no data. As of version 4.1 and higher, if a GRID input is attempted on a protected field, BR issues a Bell.

Shift+PgUp and Shift+PgDn selects within a List/Grid.

Grids and lists are compatible with the [[FILTER]] field, which works like a search bar.

In GRIDs and LISTs only, string arrays may be used to process numeric values. BR automatically performs [[VAL]] and [[STR]] conversions as needed. If string data is passed to a numeric field type such as N or DATE then it is automatically converted to numeric form for internal processing (4.2).

As of Business Rules! versions [[4.3]]+, arrays are automatically resized when receiving data from 2D INPUT operations. This also applies to grouped arrays. Automatic resizing only applies to one dimensional arrays and does not occur when INPUTing into two dimensional arrays. For example, where all arrays are one dimensional and may have the incorrect number of elements:

INPUT FIELDS "row,col,LIST rows/cols, ROW, ALL" : ( MAT Array1$, MAT Array2$, MAT Array3, MAT Array4, MAT Array5$ )

====FKey Processing====

An [[FKey]] value can be associated with a LIST or GRID control by specifying the FKey number during either output or input operations. Once an Fkey value is specified, the control retains the setting until it is reset. An FKey value can be cleared by specifying an Fkey value of minus one (-1).

When a LIST or GRID has an FKey value set processing is dependent on whether or not the 2D control is being processed by an INPUT FIELDS statement:

*Displayed but inactive- Single clicking any cell produces the FKey interrupt.
*Active (participating in Input Fields)- Double clicking any cell produces an FKey completion.

With regard to simple field specifications in PRINT FIELDS or INPUT FIELDS statements, [[CURROW]] and [[CURCOL]] identify the character position where the cursor was when FIELDS processing is completed. However, when the most recent field processed is a [[2D control]] then [[CURROW]] and [[CURCOL]] results have different meanings:

When FIELDS processing ends and control is returned to the program while the 'current' control is of type LIST or GRID, CURROW and CURCOL are set to the current cell row and column within the 2D control instead of the character position relative to the window.

====GRID CURSOR MOVEMENT====
When field + or - is keyed BR always returns fkey values of 114 or 115 in both navigation and edit mode and for any type of data.
(This assumes the X attribute or some other attribute returns control to the program.)

Default cursor positioning for Field +/- keys is to perform a down arrow operation, and the Enter key defaults to NONE (no movement).

In edit mode, Field +/- forces the signing of a numeric field, whether or not the field type is PIC.

In edit mode, Field +/- also right truncates any character or numeric data before exiting the field.

A Config statement can be used to override (control) grid cursor movement. When this is used, both Field +/- and Enter produce the same cursor movement:

GRID_CURSOR_MOVE DOWN | RIGHT | NONE | DEFAULT

This determines the field cursor position after keying Enter or Field +/-. Both navigation and edit mode produce the same resulting cursor position.

====Restoring a User Sorted 2D Control====

In versions 4.3 and higher the syntax for sorting a listview is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }

This has been extended to allow a numeric array instead of a scalar. If an array is given, it is assumed to be in the same format that SORT_ORDER returns. The new format is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column-number | numeric-array }

Where the numeric-array has one element for each column left to right. BR will resort the columns in the requested order.

The numeric array values indicating the order of column sorting to be performed do not need to exactly match the standard format. e.g Fractions are allowed, the values can fall within any range, and there does not need to be trailing zero elements for unsorted columns.

==== A multi column LISTview ====

01000 PRINT FIELDS "10,20,LIST 10/80,HEADERS,[HDRS][,fkey]": (MAT HEADINGS$,MAT WIDTHS, MAT FORMS$)

'''Note:''' Widths are expressed in character positions.

The [HDRS] notation refers to an optional CONFIG ATTRIBUTE HDRS specification for setting the appearance of the header row. In this case the brackets [] are required and the term HDRS may be any bracketed attribute name.

If a function key value (e.g. 1520) is given then when the control is not active, it may be clicked to trigger the specified interrupt similar to any other hot control. A function key interrupt is also triggered by double clicking during an Input operation.

{|
|- valign="top"
| width="10%" | '''MAT HEADINGS$'''
| Specifies the titles that will appear at the top of each column in the List or Grid. The format of this row may be specified by an optional parameter following HEADERS in the above example.
|}

{|
|- valign="top"
| width="10%" | '''MAT WIDTHS'''
| Specifies the number of characters in each column. For example if four columns are specified and the widths are given as 10, 15, 10 and 5, then the 2D control occupies 40 character positions (plus a little for the column separators) irrespective of the number of columns specified for the display area. If needed, scroll bars are used to display wider controls within the displayed area.
|}

{|
|- valign="top"
| width="10%" | '''MAT FORMS$'''
| Specifies the display characteristics of each column such as "C 12" or "PIC(z,zzz,zz#.##-)". A "P" following the display parameter will cause the field to be protected and no data entry will be allowed in GRID mode.
|}

 The field form array elements may also include a trailing comma followed by field attributes (e.g. color) that pertain to the column.

PRINT FIELDS "10,20,LIST 10/80, = [,fkey]": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

In this example, the fourth element of the HEADERS FIELD_FORM$ array (above) could specify rounding of WEIGHT to two decimal places. If an fkey value is specified, then double-clicking (or single clicking if S is specified) a cell will generate the specified fkey interrupt.

==== Reading a Listview or Grid ====
When using INPUT FIELDS to read from a 2D control, the leading attributes specification states the type of read operation and the trailing attributes specification is the type of cell or row selection to be performed. The third parameter can optionally specify NOWAIT or an FKEY value. If it is an FKEY value, it signifies that an FKEY event should be triggered when, in navigation mode, a selection is made by double clicking or pressing the Enter key.

===== Syntax =====

[[Image:Grid.png|950px]]

=====Parameters=====
Quotation marks must surround the specifications, and individual parts must be separated by commas.

'''Row''' and '''Column''' specify the space where the grid or list begins.

'''List''' or '''Grid''', followed by rows and columns separated by a slash determine how big the list or grid is going to be. The main difference between a list and grid is that lists are for selection only while information can be added to grids directly.

The following '''Read Types''' are valid for both grids and lists:

{|
|- valign="top"
| width="10%" | '''RowCnt'''
| The number of rows specified.
|- valign="top"
| width="10%" | '''RowSub'''
| The subscripts of the specified rows.
|- valign="top"
| width="10%" | '''Row'''
| Read all cells in each specified row.
|- valign="top"
| width="10%" | '''Colcnt'''
|The number of columns established by the header arrays. e.g. INPUT FIELDS "row,col,LIST rows/cols, COLCNT, ALL" : numeric-variable
|- valign="top"
| width="10%" | '''Sort_Order'''
|(4.3+) Provides a value of zero for each unsorted column and gives the ascending sequence of column sorts that have occurred. If a column has been reversed (double sorted) it's value will be negative. The selection typed used must be ALL. For example: INPUT FIELDS "row,col,GRID rows/cols, SORT_ORDER, ALL" : Mat NumArray, with the following history of sorting a four column GRID:
column 1 (descending most recent)
column 2 (ascending first sorted)
column 3 (not sorted)
column 4 (sorted ascending)

SORT_ORDER would return-
array(1) -> -1
array(2) -> 3
array(3) -> 0
array(4) -> 2
|- valign="top"
| width="10%" | '''HEADERS'''
|(As of 4.30) The read operation returns the original PRINT FIELDS HEADER values. For example: INPUT FIELDS "row,col,LIST rows/cols, HEADERS,ALL,NOWAIT" : (MAT HEADINGS$,MAT WIDTHS, MAT FORMS$) The selection type used must be ALL.
|- valign="top"
| width="10%" | '''MASK'''
|(As of 4.30) MASK can be used with Grids and Lists. As a READ type, this reads the display mask setting, including listviews that have been displayed according to a [[filter]] or filterbox. For example: INPUT FIELDS "row,col,LIST rows/cols,MASK [,NOWAIT]" : mask_array. The mask array affects only the user presentation and not the data. Use RANGE processing or the CHG selection type to selectively read from a 2D control.
|}

These Read Types are valid for Grids only:

{|
|- valign="top"
| width="10%" | '''Cnt'''
| Specify the number of cells specified (see selection types below).
|- valign="top"
| width="10%" | '''Sub'''
| Read the Cell Subscript Values (see example below).
|- valign="top"
| width="10%" | '''Cell'''
| Read each cell specified.
|}

For the "Sel-type" parameter, the following selection types are valid for both grids and lists:

{|
|- valign="top"
| width="10%" | '''Sel'''
| Read one or more selected items.
|- valign="top"
| width="10%" | '''SelOne'''
| Select only one item.
|- valign="top"
| width="10%" | '''All'''
| Read all items in the control (except headings).
|- valign="top"
| width="10%" | '''Cur'''
| Current cell or row number.
|- valign="top"
| width="10%" | '''Next (4.2+)'''
| The cell the cursor is going to next if the user moved it using an arrow or a mouse click.
|- valign="top"
| width="10%" | '''Range'''
|Specifies which portion of a 2D control is to be input. (As of 4.3) [[#Range Input|See Below]].
|- valign="top"
| width="10%" | '''Cell_Range'''
|A special type of output range. (As of 4.3) [[#Range Input|See Below]].
|}

This Selection Type is valid for Grids only:

{|
|- valign="top"
| width="10%" | '''Chg'''
| All items changed since the last '=' populate or the last CHG retrieval of cell/row contents.
|}

The '''Read Qualifier''' is an optional parameter to help the read. As of 4.3 it can be [[DISPLAYED_ORDER]]. #[[PIC]] or #[[FMT]] could be used. #PIC and #FMT allow numeric data from a string to be used. For example: '''DISPLAYED_ORDER''' Indicates that the read operation is to not restore the data into it's original order before returning the results to the program (as of version 4.30). This reads the original row subscripts for all rows - in their present order - and only works with the ALL selection type.

GRIDLINES makes LIST controls look like GRIDs with respect to the display of data (column and row separators).
PRINT FIELDS "10,20,LIST 10/80,GRIDLINES": 1 | 0 (on or off)

The leading attribute values "^select" or "^deselect" may be specified to allow the pre-selection of GRID / LIST Elements:
PRINT FIELDS "nn,nn,GRID 10/40,^select ATTR": (mat start, mat end, mat attr$)

The '''Fkey''' and '''Nowait''' parameters are optional. FKEY means that an FKEY event should be triggered when a selection is made by double clicking or pressing the Enter key, in navigation mode. Nowait simply means that it does not wait for user input.

Following the ending quotation mark, a colon precedes the name of the I/O List.

====DISPLAYED ORDER '''Read Qualifier'''====

As of 4.30, [[DISPLAYED ORDER]] - indicates that the read operation is to not restore the data into it's original order before returning the results to the program, for example:

INPUT FIELDS "row,col,LIST rows/cols, ROWSUB, ALL, DISPLAYED_ORDER, NOWAIT": numeric-array

This reads the original row subscripts for all rows in their present order. This qualifier works only with the ALL selection type. It may be used in conjunction with other qualifiers such as FKEY.

==== Examples ====

===== LIST =====

00210 INPUT FIELDS "10,20,LIST 10/80,ROWCNT,SEL,FKEY": avail_rows ! selected row cnt
00220 ! next INPUT operation does not wait for operator
00230 MAT subscr(avail_rows)  ! redimension with number of selected rows
00240 INPUT FIELDS "10,20,LIST 10/80,ROWSUB,SEL,NOWAIT": MAT subscr ! read subscripts

===== Uniform GRID =====
Contains one data array and multiple columns

00210 INPUT FIELDS "10,20,GRID 10/80,CNT,CHG": cells  ! # of changed cells
00220 MAT subscr(cells)  ! redimension
00230 INPUT FIELDS "10,20,GRID 10/80,SUB,CHG,NOWAIT": MAT subscr ! read subscripts
00240 MAT data$(cells)  ! redimension
00250 INPUT FIELDS "10,20,GRID 10/80,CELL,CHG,NOWAIT": MAT data$ ! read changes

===== Row Oriented GRID =====
00210 INPUT FIELDS "10,20,GRID 10/80,ROWCNT,CHG": rows  ! # of changed rows
00220 MAT subscr(rows)  ! redimension
00230 INPUT FIELDS "10,20,GRID 10/80,ROWSUB,CHG,NOWAIT": MAT subscr ! read subscripts
00240 MAT NAME$(rows) : MAT CITY$(rows) : MAT AGE(rows) : MAT WEIGHT(rows) ! redimension
00250 INPUT FIELDS "10,20,GRID 10/80,ROW,CHG,NOWAIT": (MAT NAME$, MAT CITY$,MAT AGE, MAT WEIGHT)  ! read changed rows

This brings us to the question of what is to be done with the information after it has been read. If it is to be stored in a file, then we should have included a hidden column with master file record numbers of the data in each row. This would support looping through the input array and rewriting the changed data.

While LIST subscripts are expressed in terms of rows, GRID subscripts may be either. In a four column five row GRID, the cell at row three column two has a subscript of ten.

==== Cell Subscript Values of a 5 x 4 GRID ====

1 2 3 4
5 6 7 8
9 10 11 12
13 14 15 16
17 18 19 20

==== Sample Program====
The following example shows use of LIST and GRID controls. There are seven parts in this program.

The first part creates a LIST with 2 columns and 3 rows. On lines 300 - 500, column headings, widths, and form specifications are assigned to the corresponding matrices. Lines 600 and 700 place data into the matrices to be printed in the LIST. The HEADERS operation on line 800 sets the column headings, widths and form specs. Line 900 populates the LIST by row, which is the default.

00100 dim HEADINGS$(2), WIDTHS(2), FORMS$(2), NAMES$(3)*28, CITIES$(3)*18, DATA$(1)*80, SUBSCR(1)
00200 print NEWPAGE
00300 let HEADINGS$(1)="Name": let HEADINGS$(2)="City"
00400 let WIDTHS(1)=30 : let WIDTHS(2)=20
00500 let FORMS$(1)="CC 28" : let FORMS$(2)="CC 18"
00600 let NAMES$(1)="Stalin" : let NAMES$(2)="Napoleon" : let NAMES$(3)="Roosevelt"
00700 let CITIES$(1)="Moscow" : let CITIES$(2)="Paris" : let CITIES$(3)="Washington"
00800 print fields "1,1,list 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$)
00900 print fields "1,1,list 8/60,=R": (MAT NAMES$,MAT CITIES$)
01000 print fields "9,1,C 50" : "Press enter to insert at the end of list"
01100 let KSTAT$(1)

===== Output =====

[[Image:Output1.jpg]]

The second part of the program demonstrates the use of the primary flag +, which adds to the end of any previously populated data. Line 01200 redimensions matrices NAMES$ and CITIES$ to allow room for one extra item in each of them. Line 01300 places new data into the matrices to be printed in the LIST. Line 01400 adds the new data to the LIST.

01200 mat NAMES$(UDIM(NAMES$)+1) : mat CITIES$(UDIM(CITIES$)+1)
01300 let NAMES$(4)="Churchill" : let CITIES$(4)="London"
01400 print fields "1,1,list 8/60,+": (MAT NAMES$(4:4),MAT CITIES$(4:4))
01500 print fields "9,1,C 50" : "Select rows to be read into a matrix"

===== Output =====

[[Image:Output2.jpg]]

The third part of the program demonstrates use of read types ROWSUB and ROWCNT and selection type SEL. Line 1600 inputs the number of selected rows into AVAIL_ROWS. The user may select rows using the mouse or the keyboard and SHIFT and CTRL keys. Line 1700 redimensions matrix SUBSCR to the number of selected rows. Line 1800 inputs the subscripts of the selected rows into matrix SUBSCR. Line 1900 performs a HEADERS operation for a new LIST using the same matrices as were used in the previous LIST. Line 2000 populates the first row of the new LIST with the data from the first selected row from the previous LIST using the primary flag =. If user selects more than one row, then lines 2100 - 2500 add the data from the selected rows using the primary flag +.

01600 input fields "1,1,list 8/60,ROWCNT,SEL": AVAIL_ROWS
01700 mat SUBSCR(AVAIL_ROWS)
01800 input fields "1,1,list 8/60,rowsub,sel,nowait": MAT SUBSCR
01900 print fields "12,1,list 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$)
02000 print fields "12,1,list 8/60,=": (MAT NAMES$(SUBSCR(1):SUBSCR(1)),MAT CITIES$(SUBSCR(1):SUBSCR(1)))
02100 if UDIM(SUBSCR) > 1 then
02200 for I = 2 to UDIM(SUBSCR)
02300 print fields "12,1,list 8/60,+": ( MAT NAMES$(SUBSCR(I):SUBSCR(I)),MAT CITIES$(SUBSCR(I):SUBSCR(I)))
02400 next I
02500 end if
02600 print fields "9,1,C 50" : "Press enter to insert at beginning of list"

===== Output =====

[[Image:Output3.jpg]]

The fourth part of the program demonstrates the use of the primary flag -, which inserts in the beginning of any previously populated data. Line 2800 redimensions matrices NAMES$ and CITIES$ to allow room for one extra item in each of them. Line 2900 places new data into the matrices to be printed in the LIST. Line 3000 adds the new data to the beginning of the LIST ahead of previously populated data.

02700 let KSTAT$(1)
02800 mat NAMES$(UDIM(NAMES$)+1): mat CITIES$(UDIM(CITIES$)+1)
02900 let NAMES$(5)="Castro" :! let CITIES$(5)="Havana"
03000 print fields "1,1,list 8/60,-": (MAT NAMES$(5:5),MAT CITIES$(5:5))
03100 print fields "9,1,C 60" : "Press enter to populate list by column"

===== Output =====

[[Image:Output4.jpg]]

The fifth part of the program, more specifically, Line 3300, demonstrates the use of the secondary flag C to populate the LIST by column. The primary flag = is also used in order to replace any previously populated data.

03200 let KSTAT$(1)
03300 print fields "1,1,list 8/60,=C": (MAT NAMES$,MAT CITIES$)

===== Output =====

[[Image:Output5.jpg]]

The sixth part of the program creates a GRID. The HEADERS operation on line 3600 uses the same HEADINGS$, WIDTHS, and FORMS$ as the previously constructed LISTs. Line 3700 sets CURFLD to be on the sixth cell of the GRID (this is discussed in the next section). Line 3800 populates the GRID. The user may change the contents of the cells.

03400 print fields "23,1,C 50" : "Press enter to continue": let KSTAT$(1)
03500 print NEWPAGE
03600 print fields "1,1,grid 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$)
03700 let CURFLD (1,6)
03800 print fields "1,1,grid 8/60,=": (MAT NAMES$,MAT CITIES$)

===== Output =====

[[Image:Output6.jpg]]

The seventh part of the program demonstrates the use of read types CNT, CELL, and SUB and selection type CHG. Line 3900 counts the number of changed cells and inputs that number into variable CELLS. Line 4000 redimensions the matrix SUBSCR to the number of changed cells. Line 4100 inputs the changed cells into SUBSCR. Line 4200 redimensions the matrix DATA$. Line 4300 inputs the subscripts of the changed cells into matrix DATA$. Line 4400 prints DATA$.

03900 input fields "1,1,grid 8/60,cnt,chg": CELLS
04000 mat SUBSCR(CELLS)
04100 input fields "1,1,grid 8/60,sub,chg,nowait": MAT SUBSCR
04200 mat DATA$(CELLS)
04300 input fields "1,1,grid 8/60,cell,chg,nowait": MAT DATA$
04400 print MAT DATA$

===== Output =====

[[Image:Output6b.jpg]]

===== Output of line 04400 =====

[[Image:Output7.jpg]]

=== Displaying a List or Grid (Output Operations) ===
[[file:Grid2.png|900px]]

To display a listview or a grid, you must set the headers first, using a special PRINT FIELDS operation.

====HEADERS====
The HEADERS operation sets the column headings and widths. The corresponding input/output list value must be a parenthesized group of three arrays, for example:

00250 PRINT FIELDS "10,20,LIST 10/80,HEADERS": (MAT HEADINGS$, MAT WIDTHS, MAT FIELD_FORMS$)
- or -
00250 PRINT FIELDS "10,20,GRID 10/80,HEADERS,[hdrs],1520": (MAT HEADINGS$, MAT WIDTHS,MAT FIELD_FORMS$)

The [hdrs] notation refers to an optional CONFIG ATTRIBUTE [HDRS] specification for setting the appearance of the header row. In this case the [] brackets are required.

If a function key value (e.g. 1520) is given then when the control is not active, it may be clicked to trigger the specified interrupt similar to any other hot control. A function key interrupt is also triggered by double clicking during an Input operation.

MAT HEADINGS$ Contains the column titles that will be displayed at the top of each column. The font, color and shading of these titles can be set through the [HDRS] or similar substitution attribute.

MAT WIDTHS specifies DISPLAYED Column Widths and is expressed as the number of character positions occupied by each column. Scrollbars are provided as needed to honor overall control size specified in the FIELDS specification.

For example, if four columns are specified and the widths are given as 10, 15, 10 and 5, then the 2D control occupies 40 character positions (plus a little for the column separators) irrespective of the number of columns specified for the display area. If needed, scroll bars are used to display wider controls within the displayed area.

Displayed widths of zero characters are allowed. This enables the use of hidden columns for storing things like record numbers and record keys.

MAT FIELD_FORMS$ provides the BR FORM for each column. e.g. C 15 stipulates a maximum field capacity of 15. The actual displayed length is a function of the grid size and the column relative width.

The field form array elements may also include a comma followed by leading field attributes (e.g. color) pertaining to the column.

The number of columns must be set with HEADERS prior to Populating a control (loading data into it).

====MASKing====

As of 4.3, LIST and GRID support the MASK operation, both in READs and Populating, as seen in this section. For example:

PRINT FIELDS "row,col,LIST rows/cols,MASK" : mask_array

This restricts the rows (for both LIST and GRID) previously displayed to those corresponding to a “true” value in mask_array. A true value is represented in a numeric array as a value greater than zero. Negative values are not allowed in mask arrays. A string mask array may also be used with “T” and “F” values. The MASK stays in effect until 1) a new MASK is specified or 2) the contents of the control are changed with PRINT ( <nowiki>=, +, -,</nowiki> see primary flags below). Also, the mask array affects only the user presentation, not the result set.

====Populating====

The populate operation loads data into the control. In the following example four columns are loaded:

03010 PRINT FIELDS "10,20,LIST 10/80, =": (MAT NAME$, MAT CITY$,MAT AGE, MAT WEIGHT)
- or -
03020 PRINT FIELDS "10,20,GRID 10/80, =": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

In this example, the fourth element of the HEADERS FIELD_FORM$ array (above) could specify rounding of WEIGHT to two decimal places. If an fkey value is specified, then double-clicking (or single clicking if S is specified) a cell will generate the specified fkey interrupt.

Permissible leading attribute values are:

===== Primary Flags =====

{|
|- valign="top"
| width="10%" | '''='''
| Replace any previous data
|- valign="top"
| width="10%" | '''+'''
| Add to any previously populated data (this allows loading in chunks)
|}

{|
|- valign="top"
| width="10%" | '''-'''
| Insert data ahead of previously populated data (4.16+)
|}

==== Secondary Flags ====

{|
|- valign="top"
| width="10%" | '''R'''
| Load one row at a time (the default - use grouped IO parens)
|- valign="top"
| width="10%" | '''C'''
| Load one column at a time - This is for loading multiple columns of the same data type
|- valign="top"
| width="10%" | '''L'''
| Provide the FKEY (see INPUT below) or Enter interrupt if the user presses up arrow or page up in the first field, or down arrow or page down in the last field. Note that this is not specified in the individual field leading attributes.
|- valign="top"
| width="10%" | '''S'''
| Single click to activate an Enter or FKEY event (otherwise a double click is required) (4.17+)
|}

 Note that the following example will NOT work-

00100 PRINT FIELDS "10,20,LIST 10/80,=C": MAT NAME$,MAT CITY$,MAT AGE,MAT WEIGHT

The reason is that only MAT NAME$ will reach the list. MAT CITY$, MAT AGE and MAT WEIGHT will be associated with subsequent fields. Multiple arrays provided to a single control must be grouped with parentheses.

Populating a two-dimensional object by row with grouped IO means NAME$(1) will go into (1,1), AGE(1) will go into (1,2) and WGT(1) will go into (1,3) and so on. If a single array (MAT DATA$) is specified instead of a group, MAT DATA$ is applied horizontally instead of vertically. So DATA$(1) - DATA$(3) will be the first row and DATA$(4) - DATA$(6) will be the next row and so on.

Populating a two dimensional grid by column with an array named DATA$ means that DATA$(1) goes in (1,1) and DATA$(2) goes in (2,1) and DATA$(3) goes in (3,1). Therefore the first however many values of DATA refer to the first column and the second however many values of DATA refer to the second column. So if there are 3 columns and UDIM(DATA$) = 90 then DATA$(1)-DATA$(30) is the first column, and DATA$(31) - DATA$(60) is the second column and DATA$(61) - DATA$(90) is the last column.

For example, using the following information, each example demonstrates how the grid will be filled:

MAT NAME$ = George, Peter, Tom

MAT CITY$ = Dallas, Detroit, Denver

MAT AGE$ = 42, 23, 35

MAT WEIGHT$ = 180, 212, 193

00200 PRINT FIELDS "10,20,GRID 10/80, =": (MAT NAME$, MAT CITY$,MAT AGE$, MAT WEIGHT$)

Peter, Detroit, 23, 212

Tom, Denver, 35, 193

00200 PRINT FIELDS "10,20,GRID 10/80, =C": (MAT NAME$, MAT CITY$,MAT AGE$, MAT WEIGHT$)

Dallas, Detroit, Denver

42, 23, 35

180, 212, 193

As you can see using C with grouped arrays is counter-intuitive and doesn't fit well. C is most useful with a single array that should be loaded vertically down several columns.

===== Grid Validation =====

GRIDs are now validated as each cell is exited instead of when control is passed to the BR program after all data is entered.

===== Color and Font changes in Cells =====

The attributes that determine font, color and style in each cell can be set for an entire column by including these parameters in the heading FORM array. Individual cells can then be changed using a PRINT statement.

The format of the print statement is

00100 PRINT #WINNO, fields "2,2,LIST 10/60,ATTR":(mat start, mat end, mat attribute$)

With the following parameter descriptions:

{|
|- valign="top"
| width="10%" | '''mat start'''
| contains the cell number(s) where the attribute chain begins,
|- valign="top"
| width="10%" | '''mat end'''
| contains the last cell number where the attribute applies
|- valign="top"
| width="10%" | '''mat attribute$'''
| contains the attribute specification that should be applied to the cell range(s) specified.
|}

If the 2d control is a GRID, then mat Start and mat End refer to starting and ending Cell Numbers. If the 2d control is a listview, then mat Start and mat End refer to starting and ending Row Numbers.

The attributes specified for any COLUMN can be overridden on a cell basis by specifying the starting cell number, ending cell number, and the overriding attributes in three arrays that are printed to the grid window with the same grid specificatoins and the key word "ATTR".

02420 PRINT #BLISTWIN,FIELDS BLISTSPEC$&",ATTR": (MAT BROWS,MAT BROWE,MAT BATT$)

In the above example, BLISTWIN is the window number, BLISTSPEC$ is the grid specification ("GRID 10/40" for example), BROWS is an array holding the starting cell number, BROWE is an array holding the ending cell number, and BATT$ is an array holding the overriding attributes. In a list the attributes of the first cell in the row controls the appearance of the entire row.

01500 PRINT FIELDS "nn,nn,GRID 10/40,ATTR": (mat start, mat end, mat attr$)

The above example overrides the attributes of a range of cells/rows for a GRID/LIST display. This allows you to shade or otherwise alter the display of a range of cells / rows in a 2D control.

====Aggregate Sorting====
BR supports aggregated sorting for LISTs and GRIDs. This means when clicking
on various column headings or programmatically sorting columns, fields of
equal values retain their previous order within their new groupings (4.2).

==== Numeric Column Sorting ====

2D controls now facilitate numeric column sorting. This works well in conjunction with the new [[Date (Format Specification)|DATE]] field format (see release notes [[4.16]]) where the data is stored as day of century, but is displayed as a formatted date. It also works with all numeric columns.

If a listview columns form spec if given as DATE(mm/dd/ccyy), for example, then any time that column is sorted, either as a result of the user clicking on the column heading, or the program giving the sort command (shown below), the dates are properly sorted even though they're displayed as mm/dd/ccyy. For this to work, the data has to be given in the julian days format, see the [[DAYS]] function for more information.

In versions 4.2 and higher the syntax for sorting a listview is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }

To sort in reverse order, sort the column twice:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }
PRINT FIELDS "nn,nn,GRID 10/40,SORT": { same column number }

This has been extended in version 4.3 to allow a numeric array instead of a scalar. If an array is given, it is assumed to be in the same format that SORT_ORDER returns. The new format is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column-number | numeric-array }

Where the numeric-array has one element for each column left to right. BR will resort the columns in the requested order.

The numeric array values indicating the order of column sorting to be performed do not need to exactly match the standard format. e.g Fractions are allowed, the values can fall within any range, and there does not need to be trailing zero elements for unsorted columns.

==== NOSORT for Columns ====
As of 4.2, the '''NoSort''' parameter is used to prevent users from sorting columns of a Grid or List.

For the statement:

PRINT FIELDS "10,20,GRID 10/80,HEADERS,[hdrs],1520": (MAT HEADINGS$, MAT WIDTHS, MAT FIELD_FORMS$)

The field attribute "^nosort" appearing in the MAT FIELD_FORM$ prevents the sorting of a grid or listview in response to the user clicking on the corresponding column header. This does not prevent programs from sorting on those columns.

==== Range Input ====

The following examples are used in versions 4.3 and higher. In these examples BR will redimension the receiving arrays as needed:

INPUT FIELDS "row,col,LIST rows/cols, CELL, RANGE" :
start, end, MAT Data$

This reads the specified range of cells. BR redimensions MAT Data$ as needed. Note that CELL may now be used with LIST. Previously, LISTs were only addressable by row.

INPUT FIELDS "row,col,LIST rows/cols, ROW, RANGE" :
(start:=7), (end:=11), ( MAT Array1$, MAT Array2, MAT Array3$ )

This reads the cells in rows 7 through 11. The receiving arrays are re-dimensioned as appropriate.

INPUT FIELDS "row,col,GRID rows/cols, ROW, RANGE":
MAT start, MAT end, ( MAT Data1$, MAT Data2$, MAT Data3 )

This reads one or more ranges of rows.

A more detailed example of this is:

100 ! create and populate a LIST control
200 MAT START(3) : MAT END(3)
210 READ MAT START, MAT END
220 DATA 7,21,33
230 DATA 11,21,38
240 INPUT FIELDS "row,col,LIST rows/cols, ROW, RANGE" : MAT START,
MAT END, ( MAT Array1$, MAT Array2, MAT Array3$ )

This reads 12 rows of data ( row 7-11, row 21 and rows 33-38 ).

==== Range Output ====

The following examples are valid for versions [[4.3]] and higher. By default, RANGE output refers to rows. The special keyword CELL_RANGE is used to denote the specification of cell ranges. Additionally, the use of scalars versus arrays for start and end values determines important characteristics of the output process.

 Using Scalars For Range Specification

PRINT FIELDS "7,8,GRID 10/75, RANGE": start, end, MAT Data$

This replaces the values in rows numbered 'start' through 'end' with the data in MAT Data$. The size of MAT Data$ must be a multiple of the number of columns in the GRID or an error is generated.

PRINT FIELDS "7,8,LIST 10/75, RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

This replaces the values in ROWs numbered 'start' through 'end' with the data from MATs NAME$, CITY$, AGE and WEIGHT. The data arrays must all be dimensioned the same.

==== Insertion and Deletion with RANGE ====

The number of rows being output do not need to match the number of rows being replaced. To delete a range of rows, output one or more grouped arrays with zero elements.

The following examples are valid for versions 4.3 and higher. Using the following statement, various scenarios are described.

PRINT FIELDS "7,8,LIST 10/75, RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

start=7, end=11, and the arrays have been DIMed to nine elements
Result- Nine rows replace five, and the total content of the control is expanded by 4 rows.

start=7, end=11, and the arrays are DIMed to zero elements
Result- Five rows are deleted, and the total size of the control is reduced by 5 rows.

start=7, end=0 (anything less than 7), and the arrays are DIMed to support three rows
Result- Three rows are inserted ahead of row seven and the total content of the control is expanded by three rows

start=5000, end={any value}, the control only has 482 rows, and the source arrays are DIMed to support eleven rows
Result- Eleven rows are appended to the end of the control and become rows 483 through 493.

==== Outputting Ranges of Cells ====

The following examples are valid for versions 4.3 and higher.

Ranges of cells may be output in conjunction with the CELL_RANGE keyword.

PRINT FIELDS "7,8,LIST 10/75, CELL_RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)
- or -

PRINT FIELDS "7,8,GRID 10/75, CELL_RANGE": start, end, MAT Data$

In this case, start and end specify cells instead of rows. If insertion or deletion is indicated by dimensioning the data arrays to greater or fewer elements than are being replaced, then the data must be a multiple of the number of columns. Insertion and deletion is only valid in terms of rows, even when cell subscripts are used to specify ranges. In such cases, if the cell subscripts are not on row boundaries, an error is generated.

PRINT FIELDS "7,8,GRID 10/75, CELL_RANGE": start, start, Data$

In this example, the value in one cell is replaced with the content of a scalar.

==== Using Arrays For Range Specification ====

If the start and end specifications are array denoting multiple ranges, there must be a one to one correspondence between the number of rows specified and those in the data. This method implies replacement only and insertion or deletion is not allowed.

The data flow that this feature was designed to support is one where the user is presented with a LIST or GRID where multiple rows have been either selected or changed before returning control to the program and the program is responding by updating something on those rows.

The program begins by presenting a 2D control to the user and reading the the control with type ROWSUB or SUB. Type SUB only works for GRIDs where all colmns have the same data type. Of course the subscripts are read into a numeric array which BR redimensions as appropriate. Then the program reads the changed or selected data with NOWAIT. (This resets the CHG flags in the control.) The program then changes either row (ROWSUB) or cell (SUB) data and outputs the results using the subscript array as both the start and end specification. Other scenarios are possible but this is the primary intended use.

The following examples are valid for versions 4.3 and higher:

100 ! create and populate a GRID --
200 INPUT FIELDS "row,col,GRID rows/cols,ROWSUB,CHG": MAT Rowsubs
(Reading subscripts does not reset the CHG flags in the control.)
210 INPUT FIELDS "row,col,GRID rows/cols,ROW,CHG,NOWAIT": ( MAT Data1$,
MAT Data2, MAT Data3$ )
BR redimensions the receiving arrays as needed.
(Reading the data also resets the CHG flags in the control.)

220 ! process the changed rows now present in the data arrays --
300 PRINT FIELDS "row,col,GRID rows/cols,RANGE": MAT Rowsubs,
MAT Rowsubs, ( MAT Data1$, MAT Data2, MAT Data3$ )

This outputs the updated rows.

 

==== Grid and List BR_VB Similarities ====
Before introducing grids and lists in BR, similar effects could be achieved using BR_VB to work with Visual Basic. If you were familiar with BR_VB, the following notes may be of interest:

Grid and list controls work like the BR_VB interface except headers now specify the form of each column and a new input type has been added:

A multi column LISTview-

00100 PRINT FIELDS "10,20,LIST 10/80,HEADERS[,hdrs][,fkey]": (MAT HEADINGS$, MAT WIDTHS, MAT FORMS$)

'''Note-''' Widths are expressed in character positions, not percentages like they are in BR_VB.

The populate operation-

00200 PRINT FIELDS "10,20,LIST 10/80,=": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

Read-Ctl type: CNT (in place of CELLROWSUB) returns a single numeric value which is the number of subscripts available to read. In the case of grids, this is the number of cells. In the case of LISTviews, this is the number of rows.

00110 INPUT FIELDS "10,20,LIST 10/80,ROWCNT,SEL": avail_rows ! # of selected rows
00120 MAT DATA$(3 * avail_rows)  ! redimension.. 3 cols x selected rows
00130 INPUT FIELDS "10,20,LIST 10/80,ROW,SEL,NOWAIT": MAT DATA$ ! read rows

====See Also: ====
* [[Grids Tutorial]]
* [[0886]]

<noinclude>
[[Category:Widget]]
</noinclude>

Grid and List

2024-02-05T05:15:42Z

Gordon.dye: /* FKey Processing */

This discussion assumes the reader has a clear understanding of [[INPUT FIELDS]] and [[PRINT FIELDS]] processing with simple fields.

'''Grid''' and '''List''' (a.k.a. '''ListView''') are [[Two dimensional controls]], which means that they contain rows and columns. GRIDs are normally used for data entry, while LISTs are used only for selection. In Business Rules, outputting to these controls is done with [[Print Fields]] and inputting from them is done with [[Input Fields]]. Each field specification pertains to one [[Control]]. However, a single FIELD specification can pertain to a parenthesized group of arrays. When using Grids and Lists, first the header must be populated, and then the data within the rows.

The [[INPUT FIELDS]] specification states Grid or List as the field type. The display area is specified in terms of rows and columns separated by a slash. The following parameter, instead of being leading field attributes, is a secondary keyword indicating the type (CNT/SUB/CELL/ROWCNT/ROWSUB/ROW) of output or input operation to be performed. The next parameter further qualifies the IO operation (CHG/SEL/ALL/CUR/NEXT). Normally this trailing attribute is an [[FKEY]] value which is shifted right one parameter in this context.

It is useful to work with [[2D Controls]] in terms of rows versus cells, particularly when the columns are dissimilar. A complete set of row oriented parameters are provided for that purpose. Output operations support the mass populating of 2D controls row by row. And input operations can be row oriented as well. The keywords associated with row processing are R, ROWCNT, ROWSUB, and ROW.

RINPUT does not work with 2D controls because the output statements are somewhat different from the input statements. The output consists of setting up the columns, including providing the column headings, and populating the control with data. The input consists of identifying what has changed in a manner that enables selective data retrieval and corresponding file updating.

If the user clicks on a column heading the GRID or LIST will be sorted on that column. Sorting is done in terms of rows. Such sorting of these controls has no affect on the BR program. The information returned to BR will be as though no sorting were performed. If a control's population is increased by populating with the plus (+) flag, the control will be resequenced back to its original order before the data is added. One way a program can restore the original displayed order of a GRID or LIST is to populate it incrementally (+) with no data. As of version 4.1 and higher, if a GRID input is attempted on a protected field, BR issues a Bell.

Shift+PgUp and Shift+PgDn selects within a List/Grid.

Grids and lists are compatible with the [[FILTER]] field, which works like a search bar.

In GRIDs and LISTs only, string arrays may be used to process numeric values. BR automatically performs [[VAL]] and [[STR]] conversions as needed. If string data is passed to a numeric field type such as N or DATE then it is automatically converted to numeric form for internal processing (4.2).

As of Business Rules! versions [[4.3]]+, arrays are automatically resized when receiving data from 2D INPUT operations. This also applies to grouped arrays. Automatic resizing only applies to one dimensional arrays and does not occur when INPUTing into two dimensional arrays. For example, where all arrays are one dimensional and may have the incorrect number of elements:

INPUT FIELDS "row,col,LIST rows/cols, ROW, ALL" : ( MAT Array1$, MAT Array2$, MAT Array3, MAT Array4, MAT Array5$ )

====FKey Processing====

An [[FKey]] value can be associated with a LIST or GRID control by specifying the FKey number during either output or input operations. Once an Fkey value is specified, the control retains the setting until it is reset. An FKey value can be cleared by specifying an Fkey value of minus one (-1).

When a LIST or GRID has an FKey value set processing is dependent on whether or not the 2D control is being processed by an INPUT FIELDS statement:

*Displayed but inactive- Single clicking any cell produces the FKey interrupt.
*Active (participating in Input Fields)- Double clicking any cell produces an FKey completion.

Formerly, [[CURROW]] and [[CURCOL]] represented the character position where the cursor was when FIELDS processing is completed. This is still true except when the most recent field processed is a [[2D control]].

When FIELDS processing ends and control is returned to the program while the 'current' control is of type LIST or GRID, CURROW and CURCOL are set to the current cell row and column within the 2D control instead of the character position relative to the window.

====GRID CURSOR MOVEMENT====
When field + or - is keyed BR always returns fkey values of 114 or 115 in both navigation and edit mode and for any type of data.
(This assumes the X attribute or some other attribute returns control to the program.)

Default cursor positioning for Field +/- keys is to perform a down arrow operation, and the Enter key defaults to NONE (no movement).

In edit mode, Field +/- forces the signing of a numeric field, whether or not the field type is PIC.

In edit mode, Field +/- also right truncates any character or numeric data before exiting the field.

A Config statement can be used to override (control) grid cursor movement. When this is used, both Field +/- and Enter produce the same cursor movement:

GRID_CURSOR_MOVE DOWN | RIGHT | NONE | DEFAULT

This determines the field cursor position after keying Enter or Field +/-. Both navigation and edit mode produce the same resulting cursor position.

====Restoring a User Sorted 2D Control====

In versions 4.3 and higher the syntax for sorting a listview is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }

This has been extended to allow a numeric array instead of a scalar. If an array is given, it is assumed to be in the same format that SORT_ORDER returns. The new format is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column-number | numeric-array }

Where the numeric-array has one element for each column left to right. BR will resort the columns in the requested order.

The numeric array values indicating the order of column sorting to be performed do not need to exactly match the standard format. e.g Fractions are allowed, the values can fall within any range, and there does not need to be trailing zero elements for unsorted columns.

==== A multi column LISTview ====

01000 PRINT FIELDS "10,20,LIST 10/80,HEADERS,[HDRS][,fkey]": (MAT HEADINGS$,MAT WIDTHS, MAT FORMS$)

'''Note:''' Widths are expressed in character positions.

The [HDRS] notation refers to an optional CONFIG ATTRIBUTE HDRS specification for setting the appearance of the header row. In this case the brackets [] are required and the term HDRS may be any bracketed attribute name.

If a function key value (e.g. 1520) is given then when the control is not active, it may be clicked to trigger the specified interrupt similar to any other hot control. A function key interrupt is also triggered by double clicking during an Input operation.

{|
|- valign="top"
| width="10%" | '''MAT HEADINGS$'''
| Specifies the titles that will appear at the top of each column in the List or Grid. The format of this row may be specified by an optional parameter following HEADERS in the above example.
|}

{|
|- valign="top"
| width="10%" | '''MAT WIDTHS'''
| Specifies the number of characters in each column. For example if four columns are specified and the widths are given as 10, 15, 10 and 5, then the 2D control occupies 40 character positions (plus a little for the column separators) irrespective of the number of columns specified for the display area. If needed, scroll bars are used to display wider controls within the displayed area.
|}

{|
|- valign="top"
| width="10%" | '''MAT FORMS$'''
| Specifies the display characteristics of each column such as "C 12" or "PIC(z,zzz,zz#.##-)". A "P" following the display parameter will cause the field to be protected and no data entry will be allowed in GRID mode.
|}

 The field form array elements may also include a trailing comma followed by field attributes (e.g. color) that pertain to the column.

PRINT FIELDS "10,20,LIST 10/80, = [,fkey]": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

In this example, the fourth element of the HEADERS FIELD_FORM$ array (above) could specify rounding of WEIGHT to two decimal places. If an fkey value is specified, then double-clicking (or single clicking if S is specified) a cell will generate the specified fkey interrupt.

==== Reading a Listview or Grid ====
When using INPUT FIELDS to read from a 2D control, the leading attributes specification states the type of read operation and the trailing attributes specification is the type of cell or row selection to be performed. The third parameter can optionally specify NOWAIT or an FKEY value. If it is an FKEY value, it signifies that an FKEY event should be triggered when, in navigation mode, a selection is made by double clicking or pressing the Enter key.

===== Syntax =====

[[Image:Grid.png|950px]]

=====Parameters=====
Quotation marks must surround the specifications, and individual parts must be separated by commas.

'''Row''' and '''Column''' specify the space where the grid or list begins.

'''List''' or '''Grid''', followed by rows and columns separated by a slash determine how big the list or grid is going to be. The main difference between a list and grid is that lists are for selection only while information can be added to grids directly.

The following '''Read Types''' are valid for both grids and lists:

{|
|- valign="top"
| width="10%" | '''RowCnt'''
| The number of rows specified.
|- valign="top"
| width="10%" | '''RowSub'''
| The subscripts of the specified rows.
|- valign="top"
| width="10%" | '''Row'''
| Read all cells in each specified row.
|- valign="top"
| width="10%" | '''Colcnt'''
|The number of columns established by the header arrays. e.g. INPUT FIELDS "row,col,LIST rows/cols, COLCNT, ALL" : numeric-variable
|- valign="top"
| width="10%" | '''Sort_Order'''
|(4.3+) Provides a value of zero for each unsorted column and gives the ascending sequence of column sorts that have occurred. If a column has been reversed (double sorted) it's value will be negative. The selection typed used must be ALL. For example: INPUT FIELDS "row,col,GRID rows/cols, SORT_ORDER, ALL" : Mat NumArray, with the following history of sorting a four column GRID:
column 1 (descending most recent)
column 2 (ascending first sorted)
column 3 (not sorted)
column 4 (sorted ascending)

SORT_ORDER would return-
array(1) -> -1
array(2) -> 3
array(3) -> 0
array(4) -> 2
|- valign="top"
| width="10%" | '''HEADERS'''
|(As of 4.30) The read operation returns the original PRINT FIELDS HEADER values. For example: INPUT FIELDS "row,col,LIST rows/cols, HEADERS,ALL,NOWAIT" : (MAT HEADINGS$,MAT WIDTHS, MAT FORMS$) The selection type used must be ALL.
|- valign="top"
| width="10%" | '''MASK'''
|(As of 4.30) MASK can be used with Grids and Lists. As a READ type, this reads the display mask setting, including listviews that have been displayed according to a [[filter]] or filterbox. For example: INPUT FIELDS "row,col,LIST rows/cols,MASK [,NOWAIT]" : mask_array. The mask array affects only the user presentation and not the data. Use RANGE processing or the CHG selection type to selectively read from a 2D control.
|}

These Read Types are valid for Grids only:

{|
|- valign="top"
| width="10%" | '''Cnt'''
| Specify the number of cells specified (see selection types below).
|- valign="top"
| width="10%" | '''Sub'''
| Read the Cell Subscript Values (see example below).
|- valign="top"
| width="10%" | '''Cell'''
| Read each cell specified.
|}

For the "Sel-type" parameter, the following selection types are valid for both grids and lists:

{|
|- valign="top"
| width="10%" | '''Sel'''
| Read one or more selected items.
|- valign="top"
| width="10%" | '''SelOne'''
| Select only one item.
|- valign="top"
| width="10%" | '''All'''
| Read all items in the control (except headings).
|- valign="top"
| width="10%" | '''Cur'''
| Current cell or row number.
|- valign="top"
| width="10%" | '''Next (4.2+)'''
| The cell the cursor is going to next if the user moved it using an arrow or a mouse click.
|- valign="top"
| width="10%" | '''Range'''
|Specifies which portion of a 2D control is to be input. (As of 4.3) [[#Range Input|See Below]].
|- valign="top"
| width="10%" | '''Cell_Range'''
|A special type of output range. (As of 4.3) [[#Range Input|See Below]].
|}

This Selection Type is valid for Grids only:

{|
|- valign="top"
| width="10%" | '''Chg'''
| All items changed since the last '=' populate or the last CHG retrieval of cell/row contents.
|}

The '''Read Qualifier''' is an optional parameter to help the read. As of 4.3 it can be [[DISPLAYED_ORDER]]. #[[PIC]] or #[[FMT]] could be used. #PIC and #FMT allow numeric data from a string to be used. For example: '''DISPLAYED_ORDER''' Indicates that the read operation is to not restore the data into it's original order before returning the results to the program (as of version 4.30). This reads the original row subscripts for all rows - in their present order - and only works with the ALL selection type.

GRIDLINES makes LIST controls look like GRIDs with respect to the display of data (column and row separators).
PRINT FIELDS "10,20,LIST 10/80,GRIDLINES": 1 | 0 (on or off)

The leading attribute values "^select" or "^deselect" may be specified to allow the pre-selection of GRID / LIST Elements:
PRINT FIELDS "nn,nn,GRID 10/40,^select ATTR": (mat start, mat end, mat attr$)

The '''Fkey''' and '''Nowait''' parameters are optional. FKEY means that an FKEY event should be triggered when a selection is made by double clicking or pressing the Enter key, in navigation mode. Nowait simply means that it does not wait for user input.

Following the ending quotation mark, a colon precedes the name of the I/O List.

====DISPLAYED ORDER '''Read Qualifier'''====

As of 4.30, [[DISPLAYED ORDER]] - indicates that the read operation is to not restore the data into it's original order before returning the results to the program, for example:

INPUT FIELDS "row,col,LIST rows/cols, ROWSUB, ALL, DISPLAYED_ORDER, NOWAIT": numeric-array

This reads the original row subscripts for all rows in their present order. This qualifier works only with the ALL selection type. It may be used in conjunction with other qualifiers such as FKEY.

==== Examples ====

===== LIST =====

00210 INPUT FIELDS "10,20,LIST 10/80,ROWCNT,SEL,FKEY": avail_rows ! selected row cnt
00220 ! next INPUT operation does not wait for operator
00230 MAT subscr(avail_rows)  ! redimension with number of selected rows
00240 INPUT FIELDS "10,20,LIST 10/80,ROWSUB,SEL,NOWAIT": MAT subscr ! read subscripts

===== Uniform GRID =====
Contains one data array and multiple columns

00210 INPUT FIELDS "10,20,GRID 10/80,CNT,CHG": cells  ! # of changed cells
00220 MAT subscr(cells)  ! redimension
00230 INPUT FIELDS "10,20,GRID 10/80,SUB,CHG,NOWAIT": MAT subscr ! read subscripts
00240 MAT data$(cells)  ! redimension
00250 INPUT FIELDS "10,20,GRID 10/80,CELL,CHG,NOWAIT": MAT data$ ! read changes

===== Row Oriented GRID =====
00210 INPUT FIELDS "10,20,GRID 10/80,ROWCNT,CHG": rows  ! # of changed rows
00220 MAT subscr(rows)  ! redimension
00230 INPUT FIELDS "10,20,GRID 10/80,ROWSUB,CHG,NOWAIT": MAT subscr ! read subscripts
00240 MAT NAME$(rows) : MAT CITY$(rows) : MAT AGE(rows) : MAT WEIGHT(rows) ! redimension
00250 INPUT FIELDS "10,20,GRID 10/80,ROW,CHG,NOWAIT": (MAT NAME$, MAT CITY$,MAT AGE, MAT WEIGHT)  ! read changed rows

This brings us to the question of what is to be done with the information after it has been read. If it is to be stored in a file, then we should have included a hidden column with master file record numbers of the data in each row. This would support looping through the input array and rewriting the changed data.

While LIST subscripts are expressed in terms of rows, GRID subscripts may be either. In a four column five row GRID, the cell at row three column two has a subscript of ten.

==== Cell Subscript Values of a 5 x 4 GRID ====

1 2 3 4
5 6 7 8
9 10 11 12
13 14 15 16
17 18 19 20

==== Sample Program====
The following example shows use of LIST and GRID controls. There are seven parts in this program.

The first part creates a LIST with 2 columns and 3 rows. On lines 300 - 500, column headings, widths, and form specifications are assigned to the corresponding matrices. Lines 600 and 700 place data into the matrices to be printed in the LIST. The HEADERS operation on line 800 sets the column headings, widths and form specs. Line 900 populates the LIST by row, which is the default.

00100 dim HEADINGS$(2), WIDTHS(2), FORMS$(2), NAMES$(3)*28, CITIES$(3)*18, DATA$(1)*80, SUBSCR(1)
00200 print NEWPAGE
00300 let HEADINGS$(1)="Name": let HEADINGS$(2)="City"
00400 let WIDTHS(1)=30 : let WIDTHS(2)=20
00500 let FORMS$(1)="CC 28" : let FORMS$(2)="CC 18"
00600 let NAMES$(1)="Stalin" : let NAMES$(2)="Napoleon" : let NAMES$(3)="Roosevelt"
00700 let CITIES$(1)="Moscow" : let CITIES$(2)="Paris" : let CITIES$(3)="Washington"
00800 print fields "1,1,list 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$)
00900 print fields "1,1,list 8/60,=R": (MAT NAMES$,MAT CITIES$)
01000 print fields "9,1,C 50" : "Press enter to insert at the end of list"
01100 let KSTAT$(1)

===== Output =====

[[Image:Output1.jpg]]

The second part of the program demonstrates the use of the primary flag +, which adds to the end of any previously populated data. Line 01200 redimensions matrices NAMES$ and CITIES$ to allow room for one extra item in each of them. Line 01300 places new data into the matrices to be printed in the LIST. Line 01400 adds the new data to the LIST.

01200 mat NAMES$(UDIM(NAMES$)+1) : mat CITIES$(UDIM(CITIES$)+1)
01300 let NAMES$(4)="Churchill" : let CITIES$(4)="London"
01400 print fields "1,1,list 8/60,+": (MAT NAMES$(4:4),MAT CITIES$(4:4))
01500 print fields "9,1,C 50" : "Select rows to be read into a matrix"

===== Output =====

[[Image:Output2.jpg]]

The third part of the program demonstrates use of read types ROWSUB and ROWCNT and selection type SEL. Line 1600 inputs the number of selected rows into AVAIL_ROWS. The user may select rows using the mouse or the keyboard and SHIFT and CTRL keys. Line 1700 redimensions matrix SUBSCR to the number of selected rows. Line 1800 inputs the subscripts of the selected rows into matrix SUBSCR. Line 1900 performs a HEADERS operation for a new LIST using the same matrices as were used in the previous LIST. Line 2000 populates the first row of the new LIST with the data from the first selected row from the previous LIST using the primary flag =. If user selects more than one row, then lines 2100 - 2500 add the data from the selected rows using the primary flag +.

01600 input fields "1,1,list 8/60,ROWCNT,SEL": AVAIL_ROWS
01700 mat SUBSCR(AVAIL_ROWS)
01800 input fields "1,1,list 8/60,rowsub,sel,nowait": MAT SUBSCR
01900 print fields "12,1,list 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$)
02000 print fields "12,1,list 8/60,=": (MAT NAMES$(SUBSCR(1):SUBSCR(1)),MAT CITIES$(SUBSCR(1):SUBSCR(1)))
02100 if UDIM(SUBSCR) > 1 then
02200 for I = 2 to UDIM(SUBSCR)
02300 print fields "12,1,list 8/60,+": ( MAT NAMES$(SUBSCR(I):SUBSCR(I)),MAT CITIES$(SUBSCR(I):SUBSCR(I)))
02400 next I
02500 end if
02600 print fields "9,1,C 50" : "Press enter to insert at beginning of list"

===== Output =====

[[Image:Output3.jpg]]

The fourth part of the program demonstrates the use of the primary flag -, which inserts in the beginning of any previously populated data. Line 2800 redimensions matrices NAMES$ and CITIES$ to allow room for one extra item in each of them. Line 2900 places new data into the matrices to be printed in the LIST. Line 3000 adds the new data to the beginning of the LIST ahead of previously populated data.

02700 let KSTAT$(1)
02800 mat NAMES$(UDIM(NAMES$)+1): mat CITIES$(UDIM(CITIES$)+1)
02900 let NAMES$(5)="Castro" :! let CITIES$(5)="Havana"
03000 print fields "1,1,list 8/60,-": (MAT NAMES$(5:5),MAT CITIES$(5:5))
03100 print fields "9,1,C 60" : "Press enter to populate list by column"

===== Output =====

[[Image:Output4.jpg]]

The fifth part of the program, more specifically, Line 3300, demonstrates the use of the secondary flag C to populate the LIST by column. The primary flag = is also used in order to replace any previously populated data.

03200 let KSTAT$(1)
03300 print fields "1,1,list 8/60,=C": (MAT NAMES$,MAT CITIES$)

===== Output =====

[[Image:Output5.jpg]]

The sixth part of the program creates a GRID. The HEADERS operation on line 3600 uses the same HEADINGS$, WIDTHS, and FORMS$ as the previously constructed LISTs. Line 3700 sets CURFLD to be on the sixth cell of the GRID (this is discussed in the next section). Line 3800 populates the GRID. The user may change the contents of the cells.

03400 print fields "23,1,C 50" : "Press enter to continue": let KSTAT$(1)
03500 print NEWPAGE
03600 print fields "1,1,grid 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$)
03700 let CURFLD (1,6)
03800 print fields "1,1,grid 8/60,=": (MAT NAMES$,MAT CITIES$)

===== Output =====

[[Image:Output6.jpg]]

The seventh part of the program demonstrates the use of read types CNT, CELL, and SUB and selection type CHG. Line 3900 counts the number of changed cells and inputs that number into variable CELLS. Line 4000 redimensions the matrix SUBSCR to the number of changed cells. Line 4100 inputs the changed cells into SUBSCR. Line 4200 redimensions the matrix DATA$. Line 4300 inputs the subscripts of the changed cells into matrix DATA$. Line 4400 prints DATA$.

03900 input fields "1,1,grid 8/60,cnt,chg": CELLS
04000 mat SUBSCR(CELLS)
04100 input fields "1,1,grid 8/60,sub,chg,nowait": MAT SUBSCR
04200 mat DATA$(CELLS)
04300 input fields "1,1,grid 8/60,cell,chg,nowait": MAT DATA$
04400 print MAT DATA$

===== Output =====

[[Image:Output6b.jpg]]

===== Output of line 04400 =====

[[Image:Output7.jpg]]

=== Displaying a List or Grid (Output Operations) ===
[[file:Grid2.png|900px]]

To display a listview or a grid, you must set the headers first, using a special PRINT FIELDS operation.

====HEADERS====
The HEADERS operation sets the column headings and widths. The corresponding input/output list value must be a parenthesized group of three arrays, for example:

00250 PRINT FIELDS "10,20,LIST 10/80,HEADERS": (MAT HEADINGS$, MAT WIDTHS, MAT FIELD_FORMS$)
- or -
00250 PRINT FIELDS "10,20,GRID 10/80,HEADERS,[hdrs],1520": (MAT HEADINGS$, MAT WIDTHS,MAT FIELD_FORMS$)

The [hdrs] notation refers to an optional CONFIG ATTRIBUTE [HDRS] specification for setting the appearance of the header row. In this case the [] brackets are required.

If a function key value (e.g. 1520) is given then when the control is not active, it may be clicked to trigger the specified interrupt similar to any other hot control. A function key interrupt is also triggered by double clicking during an Input operation.

MAT HEADINGS$ Contains the column titles that will be displayed at the top of each column. The font, color and shading of these titles can be set through the [HDRS] or similar substitution attribute.

MAT WIDTHS specifies DISPLAYED Column Widths and is expressed as the number of character positions occupied by each column. Scrollbars are provided as needed to honor overall control size specified in the FIELDS specification.

For example, if four columns are specified and the widths are given as 10, 15, 10 and 5, then the 2D control occupies 40 character positions (plus a little for the column separators) irrespective of the number of columns specified for the display area. If needed, scroll bars are used to display wider controls within the displayed area.

Displayed widths of zero characters are allowed. This enables the use of hidden columns for storing things like record numbers and record keys.

MAT FIELD_FORMS$ provides the BR FORM for each column. e.g. C 15 stipulates a maximum field capacity of 15. The actual displayed length is a function of the grid size and the column relative width.

The field form array elements may also include a comma followed by leading field attributes (e.g. color) pertaining to the column.

The number of columns must be set with HEADERS prior to Populating a control (loading data into it).

====MASKing====

As of 4.3, LIST and GRID support the MASK operation, both in READs and Populating, as seen in this section. For example:

PRINT FIELDS "row,col,LIST rows/cols,MASK" : mask_array

This restricts the rows (for both LIST and GRID) previously displayed to those corresponding to a “true” value in mask_array. A true value is represented in a numeric array as a value greater than zero. Negative values are not allowed in mask arrays. A string mask array may also be used with “T” and “F” values. The MASK stays in effect until 1) a new MASK is specified or 2) the contents of the control are changed with PRINT ( <nowiki>=, +, -,</nowiki> see primary flags below). Also, the mask array affects only the user presentation, not the result set.

====Populating====

The populate operation loads data into the control. In the following example four columns are loaded:

03010 PRINT FIELDS "10,20,LIST 10/80, =": (MAT NAME$, MAT CITY$,MAT AGE, MAT WEIGHT)
- or -
03020 PRINT FIELDS "10,20,GRID 10/80, =": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

In this example, the fourth element of the HEADERS FIELD_FORM$ array (above) could specify rounding of WEIGHT to two decimal places. If an fkey value is specified, then double-clicking (or single clicking if S is specified) a cell will generate the specified fkey interrupt.

Permissible leading attribute values are:

===== Primary Flags =====

{|
|- valign="top"
| width="10%" | '''='''
| Replace any previous data
|- valign="top"
| width="10%" | '''+'''
| Add to any previously populated data (this allows loading in chunks)
|}

{|
|- valign="top"
| width="10%" | '''-'''
| Insert data ahead of previously populated data (4.16+)
|}

==== Secondary Flags ====

{|
|- valign="top"
| width="10%" | '''R'''
| Load one row at a time (the default - use grouped IO parens)
|- valign="top"
| width="10%" | '''C'''
| Load one column at a time - This is for loading multiple columns of the same data type
|- valign="top"
| width="10%" | '''L'''
| Provide the FKEY (see INPUT below) or Enter interrupt if the user presses up arrow or page up in the first field, or down arrow or page down in the last field. Note that this is not specified in the individual field leading attributes.
|- valign="top"
| width="10%" | '''S'''
| Single click to activate an Enter or FKEY event (otherwise a double click is required) (4.17+)
|}

 Note that the following example will NOT work-

00100 PRINT FIELDS "10,20,LIST 10/80,=C": MAT NAME$,MAT CITY$,MAT AGE,MAT WEIGHT

The reason is that only MAT NAME$ will reach the list. MAT CITY$, MAT AGE and MAT WEIGHT will be associated with subsequent fields. Multiple arrays provided to a single control must be grouped with parentheses.

Populating a two-dimensional object by row with grouped IO means NAME$(1) will go into (1,1), AGE(1) will go into (1,2) and WGT(1) will go into (1,3) and so on. If a single array (MAT DATA$) is specified instead of a group, MAT DATA$ is applied horizontally instead of vertically. So DATA$(1) - DATA$(3) will be the first row and DATA$(4) - DATA$(6) will be the next row and so on.

Populating a two dimensional grid by column with an array named DATA$ means that DATA$(1) goes in (1,1) and DATA$(2) goes in (2,1) and DATA$(3) goes in (3,1). Therefore the first however many values of DATA refer to the first column and the second however many values of DATA refer to the second column. So if there are 3 columns and UDIM(DATA$) = 90 then DATA$(1)-DATA$(30) is the first column, and DATA$(31) - DATA$(60) is the second column and DATA$(61) - DATA$(90) is the last column.

For example, using the following information, each example demonstrates how the grid will be filled:

MAT NAME$ = George, Peter, Tom

MAT CITY$ = Dallas, Detroit, Denver

MAT AGE$ = 42, 23, 35

MAT WEIGHT$ = 180, 212, 193

00200 PRINT FIELDS "10,20,GRID 10/80, =": (MAT NAME$, MAT CITY$,MAT AGE$, MAT WEIGHT$)

Peter, Detroit, 23, 212

Tom, Denver, 35, 193

00200 PRINT FIELDS "10,20,GRID 10/80, =C": (MAT NAME$, MAT CITY$,MAT AGE$, MAT WEIGHT$)

Dallas, Detroit, Denver

42, 23, 35

180, 212, 193

As you can see using C with grouped arrays is counter-intuitive and doesn't fit well. C is most useful with a single array that should be loaded vertically down several columns.

===== Grid Validation =====

GRIDs are now validated as each cell is exited instead of when control is passed to the BR program after all data is entered.

===== Color and Font changes in Cells =====

The attributes that determine font, color and style in each cell can be set for an entire column by including these parameters in the heading FORM array. Individual cells can then be changed using a PRINT statement.

The format of the print statement is

00100 PRINT #WINNO, fields "2,2,LIST 10/60,ATTR":(mat start, mat end, mat attribute$)

With the following parameter descriptions:

{|
|- valign="top"
| width="10%" | '''mat start'''
| contains the cell number(s) where the attribute chain begins,
|- valign="top"
| width="10%" | '''mat end'''
| contains the last cell number where the attribute applies
|- valign="top"
| width="10%" | '''mat attribute$'''
| contains the attribute specification that should be applied to the cell range(s) specified.
|}

If the 2d control is a GRID, then mat Start and mat End refer to starting and ending Cell Numbers. If the 2d control is a listview, then mat Start and mat End refer to starting and ending Row Numbers.

The attributes specified for any COLUMN can be overridden on a cell basis by specifying the starting cell number, ending cell number, and the overriding attributes in three arrays that are printed to the grid window with the same grid specificatoins and the key word "ATTR".

02420 PRINT #BLISTWIN,FIELDS BLISTSPEC$&",ATTR": (MAT BROWS,MAT BROWE,MAT BATT$)

In the above example, BLISTWIN is the window number, BLISTSPEC$ is the grid specification ("GRID 10/40" for example), BROWS is an array holding the starting cell number, BROWE is an array holding the ending cell number, and BATT$ is an array holding the overriding attributes. In a list the attributes of the first cell in the row controls the appearance of the entire row.

01500 PRINT FIELDS "nn,nn,GRID 10/40,ATTR": (mat start, mat end, mat attr$)

The above example overrides the attributes of a range of cells/rows for a GRID/LIST display. This allows you to shade or otherwise alter the display of a range of cells / rows in a 2D control.

====Aggregate Sorting====
BR supports aggregated sorting for LISTs and GRIDs. This means when clicking
on various column headings or programmatically sorting columns, fields of
equal values retain their previous order within their new groupings (4.2).

==== Numeric Column Sorting ====

2D controls now facilitate numeric column sorting. This works well in conjunction with the new [[Date (Format Specification)|DATE]] field format (see release notes [[4.16]]) where the data is stored as day of century, but is displayed as a formatted date. It also works with all numeric columns.

If a listview columns form spec if given as DATE(mm/dd/ccyy), for example, then any time that column is sorted, either as a result of the user clicking on the column heading, or the program giving the sort command (shown below), the dates are properly sorted even though they're displayed as mm/dd/ccyy. For this to work, the data has to be given in the julian days format, see the [[DAYS]] function for more information.

In versions 4.2 and higher the syntax for sorting a listview is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }

To sort in reverse order, sort the column twice:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }
PRINT FIELDS "nn,nn,GRID 10/40,SORT": { same column number }

This has been extended in version 4.3 to allow a numeric array instead of a scalar. If an array is given, it is assumed to be in the same format that SORT_ORDER returns. The new format is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column-number | numeric-array }

Where the numeric-array has one element for each column left to right. BR will resort the columns in the requested order.

The numeric array values indicating the order of column sorting to be performed do not need to exactly match the standard format. e.g Fractions are allowed, the values can fall within any range, and there does not need to be trailing zero elements for unsorted columns.

==== NOSORT for Columns ====
As of 4.2, the '''NoSort''' parameter is used to prevent users from sorting columns of a Grid or List.

For the statement:

PRINT FIELDS "10,20,GRID 10/80,HEADERS,[hdrs],1520": (MAT HEADINGS$, MAT WIDTHS, MAT FIELD_FORMS$)

The field attribute "^nosort" appearing in the MAT FIELD_FORM$ prevents the sorting of a grid or listview in response to the user clicking on the corresponding column header. This does not prevent programs from sorting on those columns.

==== Range Input ====

The following examples are used in versions 4.3 and higher. In these examples BR will redimension the receiving arrays as needed:

INPUT FIELDS "row,col,LIST rows/cols, CELL, RANGE" :
start, end, MAT Data$

This reads the specified range of cells. BR redimensions MAT Data$ as needed. Note that CELL may now be used with LIST. Previously, LISTs were only addressable by row.

INPUT FIELDS "row,col,LIST rows/cols, ROW, RANGE" :
(start:=7), (end:=11), ( MAT Array1$, MAT Array2, MAT Array3$ )

This reads the cells in rows 7 through 11. The receiving arrays are re-dimensioned as appropriate.

INPUT FIELDS "row,col,GRID rows/cols, ROW, RANGE":
MAT start, MAT end, ( MAT Data1$, MAT Data2$, MAT Data3 )

This reads one or more ranges of rows.

A more detailed example of this is:

100 ! create and populate a LIST control
200 MAT START(3) : MAT END(3)
210 READ MAT START, MAT END
220 DATA 7,21,33
230 DATA 11,21,38
240 INPUT FIELDS "row,col,LIST rows/cols, ROW, RANGE" : MAT START,
MAT END, ( MAT Array1$, MAT Array2, MAT Array3$ )

This reads 12 rows of data ( row 7-11, row 21 and rows 33-38 ).

==== Range Output ====

The following examples are valid for versions [[4.3]] and higher. By default, RANGE output refers to rows. The special keyword CELL_RANGE is used to denote the specification of cell ranges. Additionally, the use of scalars versus arrays for start and end values determines important characteristics of the output process.

 Using Scalars For Range Specification

PRINT FIELDS "7,8,GRID 10/75, RANGE": start, end, MAT Data$

This replaces the values in rows numbered 'start' through 'end' with the data in MAT Data$. The size of MAT Data$ must be a multiple of the number of columns in the GRID or an error is generated.

PRINT FIELDS "7,8,LIST 10/75, RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

This replaces the values in ROWs numbered 'start' through 'end' with the data from MATs NAME$, CITY$, AGE and WEIGHT. The data arrays must all be dimensioned the same.

==== Insertion and Deletion with RANGE ====

The number of rows being output do not need to match the number of rows being replaced. To delete a range of rows, output one or more grouped arrays with zero elements.

The following examples are valid for versions 4.3 and higher. Using the following statement, various scenarios are described.

PRINT FIELDS "7,8,LIST 10/75, RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

start=7, end=11, and the arrays have been DIMed to nine elements
Result- Nine rows replace five, and the total content of the control is expanded by 4 rows.

start=7, end=11, and the arrays are DIMed to zero elements
Result- Five rows are deleted, and the total size of the control is reduced by 5 rows.

start=7, end=0 (anything less than 7), and the arrays are DIMed to support three rows
Result- Three rows are inserted ahead of row seven and the total content of the control is expanded by three rows

start=5000, end={any value}, the control only has 482 rows, and the source arrays are DIMed to support eleven rows
Result- Eleven rows are appended to the end of the control and become rows 483 through 493.

==== Outputting Ranges of Cells ====

The following examples are valid for versions 4.3 and higher.

Ranges of cells may be output in conjunction with the CELL_RANGE keyword.

PRINT FIELDS "7,8,LIST 10/75, CELL_RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)
- or -

PRINT FIELDS "7,8,GRID 10/75, CELL_RANGE": start, end, MAT Data$

In this case, start and end specify cells instead of rows. If insertion or deletion is indicated by dimensioning the data arrays to greater or fewer elements than are being replaced, then the data must be a multiple of the number of columns. Insertion and deletion is only valid in terms of rows, even when cell subscripts are used to specify ranges. In such cases, if the cell subscripts are not on row boundaries, an error is generated.

PRINT FIELDS "7,8,GRID 10/75, CELL_RANGE": start, start, Data$

In this example, the value in one cell is replaced with the content of a scalar.

==== Using Arrays For Range Specification ====

If the start and end specifications are array denoting multiple ranges, there must be a one to one correspondence between the number of rows specified and those in the data. This method implies replacement only and insertion or deletion is not allowed.

The data flow that this feature was designed to support is one where the user is presented with a LIST or GRID where multiple rows have been either selected or changed before returning control to the program and the program is responding by updating something on those rows.

The program begins by presenting a 2D control to the user and reading the the control with type ROWSUB or SUB. Type SUB only works for GRIDs where all colmns have the same data type. Of course the subscripts are read into a numeric array which BR redimensions as appropriate. Then the program reads the changed or selected data with NOWAIT. (This resets the CHG flags in the control.) The program then changes either row (ROWSUB) or cell (SUB) data and outputs the results using the subscript array as both the start and end specification. Other scenarios are possible but this is the primary intended use.

The following examples are valid for versions 4.3 and higher:

100 ! create and populate a GRID --
200 INPUT FIELDS "row,col,GRID rows/cols,ROWSUB,CHG": MAT Rowsubs
(Reading subscripts does not reset the CHG flags in the control.)
210 INPUT FIELDS "row,col,GRID rows/cols,ROW,CHG,NOWAIT": ( MAT Data1$,
MAT Data2, MAT Data3$ )
BR redimensions the receiving arrays as needed.
(Reading the data also resets the CHG flags in the control.)

220 ! process the changed rows now present in the data arrays --
300 PRINT FIELDS "row,col,GRID rows/cols,RANGE": MAT Rowsubs,
MAT Rowsubs, ( MAT Data1$, MAT Data2, MAT Data3$ )

This outputs the updated rows.

 

==== Grid and List BR_VB Similarities ====
Before introducing grids and lists in BR, similar effects could be achieved using BR_VB to work with Visual Basic. If you were familiar with BR_VB, the following notes may be of interest:

Grid and list controls work like the BR_VB interface except headers now specify the form of each column and a new input type has been added:

A multi column LISTview-

00100 PRINT FIELDS "10,20,LIST 10/80,HEADERS[,hdrs][,fkey]": (MAT HEADINGS$, MAT WIDTHS, MAT FORMS$)

'''Note-''' Widths are expressed in character positions, not percentages like they are in BR_VB.

The populate operation-

00200 PRINT FIELDS "10,20,LIST 10/80,=": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

Read-Ctl type: CNT (in place of CELLROWSUB) returns a single numeric value which is the number of subscripts available to read. In the case of grids, this is the number of cells. In the case of LISTviews, this is the number of rows.

00110 INPUT FIELDS "10,20,LIST 10/80,ROWCNT,SEL": avail_rows ! # of selected rows
00120 MAT DATA$(3 * avail_rows)  ! redimension.. 3 cols x selected rows
00130 INPUT FIELDS "10,20,LIST 10/80,ROW,SEL,NOWAIT": MAT DATA$ ! read rows

====See Also: ====
* [[Grids Tutorial]]
* [[0886]]

<noinclude>
[[Category:Widget]]
</noinclude>

Grid and List

2024-02-05T05:14:33Z

Gordon.dye:

This discussion assumes the reader has a clear understanding of [[INPUT FIELDS]] and [[PRINT FIELDS]] processing with simple fields.

'''Grid''' and '''List''' (a.k.a. '''ListView''') are [[Two dimensional controls]], which means that they contain rows and columns. GRIDs are normally used for data entry, while LISTs are used only for selection. In Business Rules, outputting to these controls is done with [[Print Fields]] and inputting from them is done with [[Input Fields]]. Each field specification pertains to one [[Control]]. However, a single FIELD specification can pertain to a parenthesized group of arrays. When using Grids and Lists, first the header must be populated, and then the data within the rows.

The [[INPUT FIELDS]] specification states Grid or List as the field type. The display area is specified in terms of rows and columns separated by a slash. The following parameter, instead of being leading field attributes, is a secondary keyword indicating the type (CNT/SUB/CELL/ROWCNT/ROWSUB/ROW) of output or input operation to be performed. The next parameter further qualifies the IO operation (CHG/SEL/ALL/CUR/NEXT). Normally this trailing attribute is an [[FKEY]] value which is shifted right one parameter in this context.

It is useful to work with [[2D Controls]] in terms of rows versus cells, particularly when the columns are dissimilar. A complete set of row oriented parameters are provided for that purpose. Output operations support the mass populating of 2D controls row by row. And input operations can be row oriented as well. The keywords associated with row processing are R, ROWCNT, ROWSUB, and ROW.

RINPUT does not work with 2D controls because the output statements are somewhat different from the input statements. The output consists of setting up the columns, including providing the column headings, and populating the control with data. The input consists of identifying what has changed in a manner that enables selective data retrieval and corresponding file updating.

If the user clicks on a column heading the GRID or LIST will be sorted on that column. Sorting is done in terms of rows. Such sorting of these controls has no affect on the BR program. The information returned to BR will be as though no sorting were performed. If a control's population is increased by populating with the plus (+) flag, the control will be resequenced back to its original order before the data is added. One way a program can restore the original displayed order of a GRID or LIST is to populate it incrementally (+) with no data. As of version 4.1 and higher, if a GRID input is attempted on a protected field, BR issues a Bell.

Shift+PgUp and Shift+PgDn selects within a List/Grid.

Grids and lists are compatible with the [[FILTER]] field, which works like a search bar.

In GRIDs and LISTs only, string arrays may be used to process numeric values. BR automatically performs [[VAL]] and [[STR]] conversions as needed. If string data is passed to a numeric field type such as N or DATE then it is automatically converted to numeric form for internal processing (4.2).

As of Business Rules! versions [[4.3]]+, arrays are automatically resized when receiving data from 2D INPUT operations. This also applies to grouped arrays. Automatic resizing only applies to one dimensional arrays and does not occur when INPUTing into two dimensional arrays. For example, where all arrays are one dimensional and may have the incorrect number of elements:

INPUT FIELDS "row,col,LIST rows/cols, ROW, ALL" : ( MAT Array1$, MAT Array2$, MAT Array3, MAT Array4, MAT Array5$ )

====FKey Processing====

An [[FKey]] value can be associated with a LIST or GRID control by specifying the FKey number during either output or input operations. Once an Fkey value is specified, the control retains the setting until it is reset. An FKey value can be cleared by specifying an Fkey value of minus one (-1).

When a LIST or GRID has an FKey value set processing is dependent on whether or not the 2D control is being processed by an INPUT FIELDS statement:

*Displayed but inactive- Single clicking any cell produces the FKey interrupt.
*Active (participating in Input Fields)- Double clicking any cell produces an FKey completion.

Formerly, [[CURROW]] and [[CURCOL]] represented the character position where the cursor was when FIELDS processing is completed. This is still true except when the most recent field processed is a [[2D control]].

When FIELDS processing ends and control is returned to the program while the 'current' control is of type LIST or GRID, CURROW and CURCOL are set to the current cell row and column within the 2D control instead of the character position relative to the window.

====GRID CURSOR MOVEMENT====
When field + or - is keyed BR always returns fkey values of 114 or 115 in both navigation and edit mode and for any type of data.
(This assumes the X attribute or some other attribute returns control to the program.)

Default cursor positioning for Field +/- keys is to perform a down arrow operation, and the Enter key defaults to NONE (no movement).

In edit mode, Field +/- forces the signing of a numeric field, whether or not the field type is PIC.

In edit mode, Field +/- also right truncates any character or numeric data before exiting the field.

A Config statement can be used to override (control) grid cursor movement. When this is used, both Field +/- and Enter produce the same cursor movement:

GRID_CURSOR_MOVE DOWN | RIGHT | NONE | DEFAULT

This determines the field cursor position after keying Enter or Field +/-. Both navigation and edit mode produce the same resulting cursor position.

====Restoring a User Sorted 2D Control====

In versions 4.3 and higher the syntax for sorting a listview is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }

This has been extended to allow a numeric array instead of a scalar. If an array is given, it is assumed to be in the same format that SORT_ORDER returns. The new format is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column-number | numeric-array }

Where the numeric-array has one element for each column left to right. BR will resort the columns in the requested order.

The numeric array values indicating the order of column sorting to be performed do not need to exactly match the standard format. e.g Fractions are allowed, the values can fall within any range, and there does not need to be trailing zero elements for unsorted columns.

==== A multi column LISTview ====

01000 PRINT FIELDS "10,20,LIST 10/80,HEADERS,[HDRS][,fkey]": (MAT HEADINGS$,MAT WIDTHS, MAT FORMS$)

'''Note:''' Widths are expressed in character positions.

The [HDRS] notation refers to an optional CONFIG ATTRIBUTE HDRS specification for setting the appearance of the header row. In this case the brackets [] are required and the term HDRS may be any bracketed attribute name.

If a function key value (e.g. 1520) is given then when the control is not active, it may be clicked to trigger the specified interrupt similar to any other hot control. A function key interrupt is also triggered by double clicking during an Input operation.

{|
|- valign="top"
| width="10%" | '''MAT HEADINGS$'''
| Specifies the titles that will appear at the top of each column in the List or Grid. The format of this row may be specified by an optional parameter following HEADERS in the above example.
|}

{|
|- valign="top"
| width="10%" | '''MAT WIDTHS'''
| Specifies the number of characters in each column. For example if four columns are specified and the widths are given as 10, 15, 10 and 5, then the 2D control occupies 40 character positions (plus a little for the column separators) irrespective of the number of columns specified for the display area. If needed, scroll bars are used to display wider controls within the displayed area.
|}

{|
|- valign="top"
| width="10%" | '''MAT FORMS$'''
| Specifies the display characteristics of each column such as "C 12" or "PIC(z,zzz,zz#.##-)". A "P" following the display parameter will cause the field to be protected and no data entry will be allowed in GRID mode.
|}

 The field form array elements may also include a trailing comma followed by field attributes (e.g. color) that pertain to the column.

PRINT FIELDS "10,20,LIST 10/80, = [,fkey]": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

In this example, the fourth element of the HEADERS FIELD_FORM$ array (above) could specify rounding of WEIGHT to two decimal places. If an fkey value is specified, then double-clicking (or single clicking if S is specified) a cell will generate the specified fkey interrupt.

==== Reading a Listview or Grid ====
When using INPUT FIELDS to read from a 2D control, the leading attributes specification states the type of read operation and the trailing attributes specification is the type of cell or row selection to be performed. The third parameter can optionally specify NOWAIT or an FKEY value. If it is an FKEY value, it signifies that an FKEY event should be triggered when, in navigation mode, a selection is made by double clicking or pressing the Enter key.

===== Syntax =====

[[Image:Grid.png|950px]]

=====Parameters=====
Quotation marks must surround the specifications, and individual parts must be separated by commas.

'''Row''' and '''Column''' specify the space where the grid or list begins.

'''List''' or '''Grid''', followed by rows and columns separated by a slash determine how big the list or grid is going to be. The main difference between a list and grid is that lists are for selection only while information can be added to grids directly.

The following '''Read Types''' are valid for both grids and lists:

{|
|- valign="top"
| width="10%" | '''RowCnt'''
| The number of rows specified.
|- valign="top"
| width="10%" | '''RowSub'''
| The subscripts of the specified rows.
|- valign="top"
| width="10%" | '''Row'''
| Read all cells in each specified row.
|- valign="top"
| width="10%" | '''Colcnt'''
|The number of columns established by the header arrays. e.g. INPUT FIELDS "row,col,LIST rows/cols, COLCNT, ALL" : numeric-variable
|- valign="top"
| width="10%" | '''Sort_Order'''
|(4.3+) Provides a value of zero for each unsorted column and gives the ascending sequence of column sorts that have occurred. If a column has been reversed (double sorted) it's value will be negative. The selection typed used must be ALL. For example: INPUT FIELDS "row,col,GRID rows/cols, SORT_ORDER, ALL" : Mat NumArray, with the following history of sorting a four column GRID:
column 1 (descending most recent)
column 2 (ascending first sorted)
column 3 (not sorted)
column 4 (sorted ascending)

SORT_ORDER would return-
array(1) -> -1
array(2) -> 3
array(3) -> 0
array(4) -> 2
|- valign="top"
| width="10%" | '''HEADERS'''
|(As of 4.30) The read operation returns the original PRINT FIELDS HEADER values. For example: INPUT FIELDS "row,col,LIST rows/cols, HEADERS,ALL,NOWAIT" : (MAT HEADINGS$,MAT WIDTHS, MAT FORMS$) The selection type used must be ALL.
|- valign="top"
| width="10%" | '''MASK'''
|(As of 4.30) MASK can be used with Grids and Lists. As a READ type, this reads the display mask setting, including listviews that have been displayed according to a [[filter]] or filterbox. For example: INPUT FIELDS "row,col,LIST rows/cols,MASK [,NOWAIT]" : mask_array. The mask array affects only the user presentation and not the data. Use RANGE processing or the CHG selection type to selectively read from a 2D control.
|}

These Read Types are valid for Grids only:

{|
|- valign="top"
| width="10%" | '''Cnt'''
| Specify the number of cells specified (see selection types below).
|- valign="top"
| width="10%" | '''Sub'''
| Read the Cell Subscript Values (see example below).
|- valign="top"
| width="10%" | '''Cell'''
| Read each cell specified.
|}

For the "Sel-type" parameter, the following selection types are valid for both grids and lists:

{|
|- valign="top"
| width="10%" | '''Sel'''
| Read one or more selected items.
|- valign="top"
| width="10%" | '''SelOne'''
| Select only one item.
|- valign="top"
| width="10%" | '''All'''
| Read all items in the control (except headings).
|- valign="top"
| width="10%" | '''Cur'''
| Current cell or row number.
|- valign="top"
| width="10%" | '''Next (4.2+)'''
| The cell the cursor is going to next if the user moved it using an arrow or a mouse click.
|- valign="top"
| width="10%" | '''Range'''
|Specifies which portion of a 2D control is to be input. (As of 4.3) [[#Range Input|See Below]].
|- valign="top"
| width="10%" | '''Cell_Range'''
|A special type of output range. (As of 4.3) [[#Range Input|See Below]].
|}

This Selection Type is valid for Grids only:

{|
|- valign="top"
| width="10%" | '''Chg'''
| All items changed since the last '=' populate or the last CHG retrieval of cell/row contents.
|}

The '''Read Qualifier''' is an optional parameter to help the read. As of 4.3 it can be [[DISPLAYED_ORDER]]. #[[PIC]] or #[[FMT]] could be used. #PIC and #FMT allow numeric data from a string to be used. For example: '''DISPLAYED_ORDER''' Indicates that the read operation is to not restore the data into it's original order before returning the results to the program (as of version 4.30). This reads the original row subscripts for all rows - in their present order - and only works with the ALL selection type.

GRIDLINES makes LIST controls look like GRIDs with respect to the display of data (column and row separators).
PRINT FIELDS "10,20,LIST 10/80,GRIDLINES": 1 | 0 (on or off)

The leading attribute values "^select" or "^deselect" may be specified to allow the pre-selection of GRID / LIST Elements:
PRINT FIELDS "nn,nn,GRID 10/40,^select ATTR": (mat start, mat end, mat attr$)

The '''Fkey''' and '''Nowait''' parameters are optional. FKEY means that an FKEY event should be triggered when a selection is made by double clicking or pressing the Enter key, in navigation mode. Nowait simply means that it does not wait for user input.

Following the ending quotation mark, a colon precedes the name of the I/O List.

====DISPLAYED ORDER '''Read Qualifier'''====

As of 4.30, [[DISPLAYED ORDER]] - indicates that the read operation is to not restore the data into it's original order before returning the results to the program, for example:

INPUT FIELDS "row,col,LIST rows/cols, ROWSUB, ALL, DISPLAYED_ORDER, NOWAIT": numeric-array

This reads the original row subscripts for all rows in their present order. This qualifier works only with the ALL selection type. It may be used in conjunction with other qualifiers such as FKEY.

==== Examples ====

===== LIST =====

00210 INPUT FIELDS "10,20,LIST 10/80,ROWCNT,SEL,FKEY": avail_rows ! selected row cnt
00220 ! next INPUT operation does not wait for operator
00230 MAT subscr(avail_rows)  ! redimension with number of selected rows
00240 INPUT FIELDS "10,20,LIST 10/80,ROWSUB,SEL,NOWAIT": MAT subscr ! read subscripts

===== Uniform GRID =====
Contains one data array and multiple columns

00210 INPUT FIELDS "10,20,GRID 10/80,CNT,CHG": cells  ! # of changed cells
00220 MAT subscr(cells)  ! redimension
00230 INPUT FIELDS "10,20,GRID 10/80,SUB,CHG,NOWAIT": MAT subscr ! read subscripts
00240 MAT data$(cells)  ! redimension
00250 INPUT FIELDS "10,20,GRID 10/80,CELL,CHG,NOWAIT": MAT data$ ! read changes

===== Row Oriented GRID =====
00210 INPUT FIELDS "10,20,GRID 10/80,ROWCNT,CHG": rows  ! # of changed rows
00220 MAT subscr(rows)  ! redimension
00230 INPUT FIELDS "10,20,GRID 10/80,ROWSUB,CHG,NOWAIT": MAT subscr ! read subscripts
00240 MAT NAME$(rows) : MAT CITY$(rows) : MAT AGE(rows) : MAT WEIGHT(rows) ! redimension
00250 INPUT FIELDS "10,20,GRID 10/80,ROW,CHG,NOWAIT": (MAT NAME$, MAT CITY$,MAT AGE, MAT WEIGHT)  ! read changed rows

This brings us to the question of what is to be done with the information after it has been read. If it is to be stored in a file, then we should have included a hidden column with master file record numbers of the data in each row. This would support looping through the input array and rewriting the changed data.

While LIST subscripts are expressed in terms of rows, GRID subscripts may be either. In a four column five row GRID, the cell at row three column two has a subscript of ten.

==== Cell Subscript Values of a 5 x 4 GRID ====

1 2 3 4
5 6 7 8
9 10 11 12
13 14 15 16
17 18 19 20

==== Sample Program====
The following example shows use of LIST and GRID controls. There are seven parts in this program.

The first part creates a LIST with 2 columns and 3 rows. On lines 300 - 500, column headings, widths, and form specifications are assigned to the corresponding matrices. Lines 600 and 700 place data into the matrices to be printed in the LIST. The HEADERS operation on line 800 sets the column headings, widths and form specs. Line 900 populates the LIST by row, which is the default.

00100 dim HEADINGS$(2), WIDTHS(2), FORMS$(2), NAMES$(3)*28, CITIES$(3)*18, DATA$(1)*80, SUBSCR(1)
00200 print NEWPAGE
00300 let HEADINGS$(1)="Name": let HEADINGS$(2)="City"
00400 let WIDTHS(1)=30 : let WIDTHS(2)=20
00500 let FORMS$(1)="CC 28" : let FORMS$(2)="CC 18"
00600 let NAMES$(1)="Stalin" : let NAMES$(2)="Napoleon" : let NAMES$(3)="Roosevelt"
00700 let CITIES$(1)="Moscow" : let CITIES$(2)="Paris" : let CITIES$(3)="Washington"
00800 print fields "1,1,list 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$)
00900 print fields "1,1,list 8/60,=R": (MAT NAMES$,MAT CITIES$)
01000 print fields "9,1,C 50" : "Press enter to insert at the end of list"
01100 let KSTAT$(1)

===== Output =====

[[Image:Output1.jpg]]

The second part of the program demonstrates the use of the primary flag +, which adds to the end of any previously populated data. Line 01200 redimensions matrices NAMES$ and CITIES$ to allow room for one extra item in each of them. Line 01300 places new data into the matrices to be printed in the LIST. Line 01400 adds the new data to the LIST.

01200 mat NAMES$(UDIM(NAMES$)+1) : mat CITIES$(UDIM(CITIES$)+1)
01300 let NAMES$(4)="Churchill" : let CITIES$(4)="London"
01400 print fields "1,1,list 8/60,+": (MAT NAMES$(4:4),MAT CITIES$(4:4))
01500 print fields "9,1,C 50" : "Select rows to be read into a matrix"

===== Output =====

[[Image:Output2.jpg]]

The third part of the program demonstrates use of read types ROWSUB and ROWCNT and selection type SEL. Line 1600 inputs the number of selected rows into AVAIL_ROWS. The user may select rows using the mouse or the keyboard and SHIFT and CTRL keys. Line 1700 redimensions matrix SUBSCR to the number of selected rows. Line 1800 inputs the subscripts of the selected rows into matrix SUBSCR. Line 1900 performs a HEADERS operation for a new LIST using the same matrices as were used in the previous LIST. Line 2000 populates the first row of the new LIST with the data from the first selected row from the previous LIST using the primary flag =. If user selects more than one row, then lines 2100 - 2500 add the data from the selected rows using the primary flag +.

01600 input fields "1,1,list 8/60,ROWCNT,SEL": AVAIL_ROWS
01700 mat SUBSCR(AVAIL_ROWS)
01800 input fields "1,1,list 8/60,rowsub,sel,nowait": MAT SUBSCR
01900 print fields "12,1,list 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$)
02000 print fields "12,1,list 8/60,=": (MAT NAMES$(SUBSCR(1):SUBSCR(1)),MAT CITIES$(SUBSCR(1):SUBSCR(1)))
02100 if UDIM(SUBSCR) > 1 then
02200 for I = 2 to UDIM(SUBSCR)
02300 print fields "12,1,list 8/60,+": ( MAT NAMES$(SUBSCR(I):SUBSCR(I)),MAT CITIES$(SUBSCR(I):SUBSCR(I)))
02400 next I
02500 end if
02600 print fields "9,1,C 50" : "Press enter to insert at beginning of list"

===== Output =====

[[Image:Output3.jpg]]

The fourth part of the program demonstrates the use of the primary flag -, which inserts in the beginning of any previously populated data. Line 2800 redimensions matrices NAMES$ and CITIES$ to allow room for one extra item in each of them. Line 2900 places new data into the matrices to be printed in the LIST. Line 3000 adds the new data to the beginning of the LIST ahead of previously populated data.

02700 let KSTAT$(1)
02800 mat NAMES$(UDIM(NAMES$)+1): mat CITIES$(UDIM(CITIES$)+1)
02900 let NAMES$(5)="Castro" :! let CITIES$(5)="Havana"
03000 print fields "1,1,list 8/60,-": (MAT NAMES$(5:5),MAT CITIES$(5:5))
03100 print fields "9,1,C 60" : "Press enter to populate list by column"

===== Output =====

[[Image:Output4.jpg]]

The fifth part of the program, more specifically, Line 3300, demonstrates the use of the secondary flag C to populate the LIST by column. The primary flag = is also used in order to replace any previously populated data.

03200 let KSTAT$(1)
03300 print fields "1,1,list 8/60,=C": (MAT NAMES$,MAT CITIES$)

===== Output =====

[[Image:Output5.jpg]]

The sixth part of the program creates a GRID. The HEADERS operation on line 3600 uses the same HEADINGS$, WIDTHS, and FORMS$ as the previously constructed LISTs. Line 3700 sets CURFLD to be on the sixth cell of the GRID (this is discussed in the next section). Line 3800 populates the GRID. The user may change the contents of the cells.

03400 print fields "23,1,C 50" : "Press enter to continue": let KSTAT$(1)
03500 print NEWPAGE
03600 print fields "1,1,grid 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$)
03700 let CURFLD (1,6)
03800 print fields "1,1,grid 8/60,=": (MAT NAMES$,MAT CITIES$)

===== Output =====

[[Image:Output6.jpg]]

The seventh part of the program demonstrates the use of read types CNT, CELL, and SUB and selection type CHG. Line 3900 counts the number of changed cells and inputs that number into variable CELLS. Line 4000 redimensions the matrix SUBSCR to the number of changed cells. Line 4100 inputs the changed cells into SUBSCR. Line 4200 redimensions the matrix DATA$. Line 4300 inputs the subscripts of the changed cells into matrix DATA$. Line 4400 prints DATA$.

03900 input fields "1,1,grid 8/60,cnt,chg": CELLS
04000 mat SUBSCR(CELLS)
04100 input fields "1,1,grid 8/60,sub,chg,nowait": MAT SUBSCR
04200 mat DATA$(CELLS)
04300 input fields "1,1,grid 8/60,cell,chg,nowait": MAT DATA$
04400 print MAT DATA$

===== Output =====

[[Image:Output6b.jpg]]

===== Output of line 04400 =====

[[Image:Output7.jpg]]

=== Displaying a List or Grid (Output Operations) ===
[[file:Grid2.png|900px]]

To display a listview or a grid, you must set the headers first, using a special PRINT FIELDS operation.

====HEADERS====
The HEADERS operation sets the column headings and widths. The corresponding input/output list value must be a parenthesized group of three arrays, for example:

00250 PRINT FIELDS "10,20,LIST 10/80,HEADERS": (MAT HEADINGS$, MAT WIDTHS, MAT FIELD_FORMS$)
- or -
00250 PRINT FIELDS "10,20,GRID 10/80,HEADERS,[hdrs],1520": (MAT HEADINGS$, MAT WIDTHS,MAT FIELD_FORMS$)

The [hdrs] notation refers to an optional CONFIG ATTRIBUTE [HDRS] specification for setting the appearance of the header row. In this case the [] brackets are required.

If a function key value (e.g. 1520) is given then when the control is not active, it may be clicked to trigger the specified interrupt similar to any other hot control. A function key interrupt is also triggered by double clicking during an Input operation.

MAT HEADINGS$ Contains the column titles that will be displayed at the top of each column. The font, color and shading of these titles can be set through the [HDRS] or similar substitution attribute.

MAT WIDTHS specifies DISPLAYED Column Widths and is expressed as the number of character positions occupied by each column. Scrollbars are provided as needed to honor overall control size specified in the FIELDS specification.

For example, if four columns are specified and the widths are given as 10, 15, 10 and 5, then the 2D control occupies 40 character positions (plus a little for the column separators) irrespective of the number of columns specified for the display area. If needed, scroll bars are used to display wider controls within the displayed area.

Displayed widths of zero characters are allowed. This enables the use of hidden columns for storing things like record numbers and record keys.

MAT FIELD_FORMS$ provides the BR FORM for each column. e.g. C 15 stipulates a maximum field capacity of 15. The actual displayed length is a function of the grid size and the column relative width.

The field form array elements may also include a comma followed by leading field attributes (e.g. color) pertaining to the column.

The number of columns must be set with HEADERS prior to Populating a control (loading data into it).

====MASKing====

As of 4.3, LIST and GRID support the MASK operation, both in READs and Populating, as seen in this section. For example:

PRINT FIELDS "row,col,LIST rows/cols,MASK" : mask_array

This restricts the rows (for both LIST and GRID) previously displayed to those corresponding to a “true” value in mask_array. A true value is represented in a numeric array as a value greater than zero. Negative values are not allowed in mask arrays. A string mask array may also be used with “T” and “F” values. The MASK stays in effect until 1) a new MASK is specified or 2) the contents of the control are changed with PRINT ( <nowiki>=, +, -,</nowiki> see primary flags below). Also, the mask array affects only the user presentation, not the result set.

====Populating====

The populate operation loads data into the control. In the following example four columns are loaded:

03010 PRINT FIELDS "10,20,LIST 10/80, =": (MAT NAME$, MAT CITY$,MAT AGE, MAT WEIGHT)
- or -
03020 PRINT FIELDS "10,20,GRID 10/80, =": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

In this example, the fourth element of the HEADERS FIELD_FORM$ array (above) could specify rounding of WEIGHT to two decimal places. If an fkey value is specified, then double-clicking (or single clicking if S is specified) a cell will generate the specified fkey interrupt.

Permissible leading attribute values are:

===== Primary Flags =====

{|
|- valign="top"
| width="10%" | '''='''
| Replace any previous data
|- valign="top"
| width="10%" | '''+'''
| Add to any previously populated data (this allows loading in chunks)
|}

{|
|- valign="top"
| width="10%" | '''-'''
| Insert data ahead of previously populated data (4.16+)
|}

==== Secondary Flags ====

{|
|- valign="top"
| width="10%" | '''R'''
| Load one row at a time (the default - use grouped IO parens)
|- valign="top"
| width="10%" | '''C'''
| Load one column at a time - This is for loading multiple columns of the same data type
|- valign="top"
| width="10%" | '''L'''
| Provide the FKEY (see INPUT below) or Enter interrupt if the user presses up arrow or page up in the first field, or down arrow or page down in the last field. Note that this is not specified in the individual field leading attributes.
|- valign="top"
| width="10%" | '''S'''
| Single click to activate an Enter or FKEY event (otherwise a double click is required) (4.17+)
|}

 Note that the following example will NOT work-

00100 PRINT FIELDS "10,20,LIST 10/80,=C": MAT NAME$,MAT CITY$,MAT AGE,MAT WEIGHT

The reason is that only MAT NAME$ will reach the list. MAT CITY$, MAT AGE and MAT WEIGHT will be associated with subsequent fields. Multiple arrays provided to a single control must be grouped with parentheses.

Populating a two-dimensional object by row with grouped IO means NAME$(1) will go into (1,1), AGE(1) will go into (1,2) and WGT(1) will go into (1,3) and so on. If a single array (MAT DATA$) is specified instead of a group, MAT DATA$ is applied horizontally instead of vertically. So DATA$(1) - DATA$(3) will be the first row and DATA$(4) - DATA$(6) will be the next row and so on.

Populating a two dimensional grid by column with an array named DATA$ means that DATA$(1) goes in (1,1) and DATA$(2) goes in (2,1) and DATA$(3) goes in (3,1). Therefore the first however many values of DATA refer to the first column and the second however many values of DATA refer to the second column. So if there are 3 columns and UDIM(DATA$) = 90 then DATA$(1)-DATA$(30) is the first column, and DATA$(31) - DATA$(60) is the second column and DATA$(61) - DATA$(90) is the last column.

For example, using the following information, each example demonstrates how the grid will be filled:

MAT NAME$ = George, Peter, Tom

MAT CITY$ = Dallas, Detroit, Denver

MAT AGE$ = 42, 23, 35

MAT WEIGHT$ = 180, 212, 193

00200 PRINT FIELDS "10,20,GRID 10/80, =": (MAT NAME$, MAT CITY$,MAT AGE$, MAT WEIGHT$)

Peter, Detroit, 23, 212

Tom, Denver, 35, 193

00200 PRINT FIELDS "10,20,GRID 10/80, =C": (MAT NAME$, MAT CITY$,MAT AGE$, MAT WEIGHT$)

Dallas, Detroit, Denver

42, 23, 35

180, 212, 193

As you can see using C with grouped arrays is counter-intuitive and doesn't fit well. C is most useful with a single array that should be loaded vertically down several columns.

===== Grid Validation =====

GRIDs are now validated as each cell is exited instead of when control is passed to the BR program after all data is entered.

===== Color and Font changes in Cells =====

The attributes that determine font, color and style in each cell can be set for an entire column by including these parameters in the heading FORM array. Individual cells can then be changed using a PRINT statement.

The format of the print statement is

00100 PRINT #WINNO, fields "2,2,LIST 10/60,ATTR":(mat start, mat end, mat attribute$)

With the following parameter descriptions:

{|
|- valign="top"
| width="10%" | '''mat start'''
| contains the cell number(s) where the attribute chain begins,
|- valign="top"
| width="10%" | '''mat end'''
| contains the last cell number where the attribute applies
|- valign="top"
| width="10%" | '''mat attribute$'''
| contains the attribute specification that should be applied to the cell range(s) specified.
|}

If the 2d control is a GRID, then mat Start and mat End refer to starting and ending Cell Numbers. If the 2d control is a listview, then mat Start and mat End refer to starting and ending Row Numbers.

The attributes specified for any COLUMN can be overridden on a cell basis by specifying the starting cell number, ending cell number, and the overriding attributes in three arrays that are printed to the grid window with the same grid specificatoins and the key word "ATTR".

02420 PRINT #BLISTWIN,FIELDS BLISTSPEC$&",ATTR": (MAT BROWS,MAT BROWE,MAT BATT$)

In the above example, BLISTWIN is the window number, BLISTSPEC$ is the grid specification ("GRID 10/40" for example), BROWS is an array holding the starting cell number, BROWE is an array holding the ending cell number, and BATT$ is an array holding the overriding attributes. In a list the attributes of the first cell in the row controls the appearance of the entire row.

01500 PRINT FIELDS "nn,nn,GRID 10/40,ATTR": (mat start, mat end, mat attr$)

The above example overrides the attributes of a range of cells/rows for a GRID/LIST display. This allows you to shade or otherwise alter the display of a range of cells / rows in a 2D control.

====Aggregate Sorting====
BR supports aggregated sorting for LISTs and GRIDs. This means when clicking
on various column headings or programmatically sorting columns, fields of
equal values retain their previous order within their new groupings (4.2).

==== Numeric Column Sorting ====

2D controls now facilitate numeric column sorting. This works well in conjunction with the new [[Date (Format Specification)|DATE]] field format (see release notes [[4.16]]) where the data is stored as day of century, but is displayed as a formatted date. It also works with all numeric columns.

If a listview columns form spec if given as DATE(mm/dd/ccyy), for example, then any time that column is sorted, either as a result of the user clicking on the column heading, or the program giving the sort command (shown below), the dates are properly sorted even though they're displayed as mm/dd/ccyy. For this to work, the data has to be given in the julian days format, see the [[DAYS]] function for more information.

In versions 4.2 and higher the syntax for sorting a listview is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }

To sort in reverse order, sort the column twice:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }
PRINT FIELDS "nn,nn,GRID 10/40,SORT": { same column number }

This has been extended in version 4.3 to allow a numeric array instead of a scalar. If an array is given, it is assumed to be in the same format that SORT_ORDER returns. The new format is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column-number | numeric-array }

Where the numeric-array has one element for each column left to right. BR will resort the columns in the requested order.

The numeric array values indicating the order of column sorting to be performed do not need to exactly match the standard format. e.g Fractions are allowed, the values can fall within any range, and there does not need to be trailing zero elements for unsorted columns.

==== NOSORT for Columns ====
As of 4.2, the '''NoSort''' parameter is used to prevent users from sorting columns of a Grid or List.

For the statement:

PRINT FIELDS "10,20,GRID 10/80,HEADERS,[hdrs],1520": (MAT HEADINGS$, MAT WIDTHS, MAT FIELD_FORMS$)

The field attribute "^nosort" appearing in the MAT FIELD_FORM$ prevents the sorting of a grid or listview in response to the user clicking on the corresponding column header. This does not prevent programs from sorting on those columns.

==== Range Input ====

The following examples are used in versions 4.3 and higher. In these examples BR will redimension the receiving arrays as needed:

INPUT FIELDS "row,col,LIST rows/cols, CELL, RANGE" :
start, end, MAT Data$

This reads the specified range of cells. BR redimensions MAT Data$ as needed. Note that CELL may now be used with LIST. Previously, LISTs were only addressable by row.

INPUT FIELDS "row,col,LIST rows/cols, ROW, RANGE" :
(start:=7), (end:=11), ( MAT Array1$, MAT Array2, MAT Array3$ )

This reads the cells in rows 7 through 11. The receiving arrays are re-dimensioned as appropriate.

INPUT FIELDS "row,col,GRID rows/cols, ROW, RANGE":
MAT start, MAT end, ( MAT Data1$, MAT Data2$, MAT Data3 )

This reads one or more ranges of rows.

A more detailed example of this is:

100 ! create and populate a LIST control
200 MAT START(3) : MAT END(3)
210 READ MAT START, MAT END
220 DATA 7,21,33
230 DATA 11,21,38
240 INPUT FIELDS "row,col,LIST rows/cols, ROW, RANGE" : MAT START,
MAT END, ( MAT Array1$, MAT Array2, MAT Array3$ )

This reads 12 rows of data ( row 7-11, row 21 and rows 33-38 ).

==== Range Output ====

The following examples are valid for versions [[4.3]] and higher. By default, RANGE output refers to rows. The special keyword CELL_RANGE is used to denote the specification of cell ranges. Additionally, the use of scalars versus arrays for start and end values determines important characteristics of the output process.

 Using Scalars For Range Specification

PRINT FIELDS "7,8,GRID 10/75, RANGE": start, end, MAT Data$

This replaces the values in rows numbered 'start' through 'end' with the data in MAT Data$. The size of MAT Data$ must be a multiple of the number of columns in the GRID or an error is generated.

PRINT FIELDS "7,8,LIST 10/75, RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

This replaces the values in ROWs numbered 'start' through 'end' with the data from MATs NAME$, CITY$, AGE and WEIGHT. The data arrays must all be dimensioned the same.

==== Insertion and Deletion with RANGE ====

The number of rows being output do not need to match the number of rows being replaced. To delete a range of rows, output one or more grouped arrays with zero elements.

The following examples are valid for versions 4.3 and higher. Using the following statement, various scenarios are described.

PRINT FIELDS "7,8,LIST 10/75, RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

start=7, end=11, and the arrays have been DIMed to nine elements
Result- Nine rows replace five, and the total content of the control is expanded by 4 rows.

start=7, end=11, and the arrays are DIMed to zero elements
Result- Five rows are deleted, and the total size of the control is reduced by 5 rows.

start=7, end=0 (anything less than 7), and the arrays are DIMed to support three rows
Result- Three rows are inserted ahead of row seven and the total content of the control is expanded by three rows

start=5000, end={any value}, the control only has 482 rows, and the source arrays are DIMed to support eleven rows
Result- Eleven rows are appended to the end of the control and become rows 483 through 493.

==== Outputting Ranges of Cells ====

The following examples are valid for versions 4.3 and higher.

Ranges of cells may be output in conjunction with the CELL_RANGE keyword.

PRINT FIELDS "7,8,LIST 10/75, CELL_RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)
- or -

PRINT FIELDS "7,8,GRID 10/75, CELL_RANGE": start, end, MAT Data$

In this case, start and end specify cells instead of rows. If insertion or deletion is indicated by dimensioning the data arrays to greater or fewer elements than are being replaced, then the data must be a multiple of the number of columns. Insertion and deletion is only valid in terms of rows, even when cell subscripts are used to specify ranges. In such cases, if the cell subscripts are not on row boundaries, an error is generated.

PRINT FIELDS "7,8,GRID 10/75, CELL_RANGE": start, start, Data$

In this example, the value in one cell is replaced with the content of a scalar.

==== Using Arrays For Range Specification ====

If the start and end specifications are array denoting multiple ranges, there must be a one to one correspondence between the number of rows specified and those in the data. This method implies replacement only and insertion or deletion is not allowed.

The data flow that this feature was designed to support is one where the user is presented with a LIST or GRID where multiple rows have been either selected or changed before returning control to the program and the program is responding by updating something on those rows.

The program begins by presenting a 2D control to the user and reading the the control with type ROWSUB or SUB. Type SUB only works for GRIDs where all colmns have the same data type. Of course the subscripts are read into a numeric array which BR redimensions as appropriate. Then the program reads the changed or selected data with NOWAIT. (This resets the CHG flags in the control.) The program then changes either row (ROWSUB) or cell (SUB) data and outputs the results using the subscript array as both the start and end specification. Other scenarios are possible but this is the primary intended use.

The following examples are valid for versions 4.3 and higher:

100 ! create and populate a GRID --
200 INPUT FIELDS "row,col,GRID rows/cols,ROWSUB,CHG": MAT Rowsubs
(Reading subscripts does not reset the CHG flags in the control.)
210 INPUT FIELDS "row,col,GRID rows/cols,ROW,CHG,NOWAIT": ( MAT Data1$,
MAT Data2, MAT Data3$ )
BR redimensions the receiving arrays as needed.
(Reading the data also resets the CHG flags in the control.)

220 ! process the changed rows now present in the data arrays --
300 PRINT FIELDS "row,col,GRID rows/cols,RANGE": MAT Rowsubs,
MAT Rowsubs, ( MAT Data1$, MAT Data2, MAT Data3$ )

This outputs the updated rows.

 

==== Grid and List BR_VB Similarities ====
Before introducing grids and lists in BR, similar effects could be achieved using BR_VB to work with Visual Basic. If you were familiar with BR_VB, the following notes may be of interest:

Grid and list controls work like the BR_VB interface except headers now specify the form of each column and a new input type has been added:

A multi column LISTview-

00100 PRINT FIELDS "10,20,LIST 10/80,HEADERS[,hdrs][,fkey]": (MAT HEADINGS$, MAT WIDTHS, MAT FORMS$)

'''Note-''' Widths are expressed in character positions, not percentages like they are in BR_VB.

The populate operation-

00200 PRINT FIELDS "10,20,LIST 10/80,=": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

Read-Ctl type: CNT (in place of CELLROWSUB) returns a single numeric value which is the number of subscripts available to read. In the case of grids, this is the number of cells. In the case of LISTviews, this is the number of rows.

00110 INPUT FIELDS "10,20,LIST 10/80,ROWCNT,SEL": avail_rows ! # of selected rows
00120 MAT DATA$(3 * avail_rows)  ! redimension.. 3 cols x selected rows
00130 INPUT FIELDS "10,20,LIST 10/80,ROW,SEL,NOWAIT": MAT DATA$ ! read rows

====See Also: ====
* [[Grids Tutorial]]
* [[0886]]

<noinclude>
[[Category:Widget]]
</noinclude>

Grid and List

2024-02-05T05:03:13Z

Gordon.dye: /* GRID CURSOR MOVEMENT */

'''Grid''' and '''List''' (a.k.a. '''ListView''') are [[Two dimensional controls]], which means that they contain rows and columns. GRIDs are normally used for data entry, while LISTs are used only for selection. In Business Rules, outputting to these controls is done with [[Print Fields]] and inputting from them is done with [[Input Fields]]. Each field specification pertains to one [[Control]]. However, a single FIELD specification can pertain to a parenthesized group of arrays. When using Grids and Lists, first the header must be populated, and then the data within the rows.

The [[INPUT FIELDS]] specification states Grid or List as the field type. The display area is specified in terms of rows and columns separated by a slash. The following parameter, instead of being leading field attributes, is a secondary keyword indicating the type (CNT/SUB/CELL/ROWCNT/ROWSUB/ROW) of output or input operation to be performed. The next parameter further qualifies the IO operation (CHG/SEL/ALL/CUR/NEXT). Normally this trailing attribute is an [[FKEY]] value which is shifted right one parameter in this context.

It is useful to work with [[2D Controls]] in terms of rows versus cells, particularly when the columns are dissimilar. A complete set of row oriented parameters are provided for that purpose. Output operations support the mass populating of 2D controls row by row. And input operations can be row oriented as well. The keywords associated with row processing are R, ROWCNT, ROWSUB, and ROW.

RINPUT does not work with 2D controls because the output statements are somewhat different from the input statements. The output consists of setting up the columns, including providing the column headings, and populating the control with data. The input consists of identifying what has changed in a manner that enables selective data retrieval and corresponding file updating.

If the user clicks on a column heading the GRID or LIST will be sorted on that column. Sorting is done in terms of rows. Such sorting of these controls has no affect on the BR program. The information returned to BR will be as though no sorting were performed. If a control's population is increased by populating with the plus (+) flag, the control will be resequenced back to its original order before the data is added. One way a program can restore the original displayed order of a GRID or LIST is to populate it incrementally (+) with no data. As of version 4.1 and higher, if a GRID input is attempted on a protected field, BR issues a Bell.

Shift+PgUp and Shift+PgDn selects within a List/Grid.

Grids and lists are compatible with the [[FILTER]] field, which works like a search bar.

In GRIDs and LISTs only, string arrays may be used to process numeric values. BR automatically performs [[VAL]] and [[STR]] conversions as needed. If string data is passed to a numeric field type such as N or DATE then it is automatically converted to numeric form for internal processing (4.2).

As of Business Rules! versions [[4.3]]+, arrays are automatically resized when receiving data from 2D INPUT operations. This also applies to grouped arrays. Automatic resizing only applies to one dimensional arrays and does not occur when INPUTing into two dimensional arrays. For example, where all arrays are one dimensional and may have the incorrect number of elements:

INPUT FIELDS "row,col,LIST rows/cols, ROW, ALL" : ( MAT Array1$, MAT Array2$, MAT Array3, MAT Array4, MAT Array5$ )

====FKey Processing====

An [[FKey]] value can be associated with a LIST or GRID control by specifying the FKey number during either output or input operations. Once an Fkey value is specified, the control retains the setting until it is reset. An FKey value can be cleared by specifying an Fkey value of minus one (-1).

When a LIST or GRID has an FKey value set processing is dependent on whether or not the 2D control is being processed by an INPUT FIELDS statement:

*Displayed but inactive- Single clicking any cell produces the FKey interrupt.
*Active (participating in Input Fields)- Double clicking any cell produces an FKey completion.

Formerly, [[CURROW]] and [[CURCOL]] represented the character position where the cursor was when FIELDS processing is completed. This is still true except when the most recent field processed is a [[2D control]].

When FIELDS processing ends and control is returned to the program while the 'current' control is of type LIST or GRID, CURROW and CURCOL are set to the current cell row and column within the 2D control instead of the character position relative to the window.

====GRID CURSOR MOVEMENT====
When field + or - is keyed BR always returns fkey values of 114 or 115 in both navigation and edit mode and for any type of data.
(This assumes the X attribute or some other attribute returns control to the program.)

Default cursor positioning for Field +/- keys is to perform a down arrow operation, and the Enter key defaults to NONE (no movement).

In edit mode, Field +/- forces the signing of a numeric field, whether or not the field type is PIC.

In edit mode, Field +/- also right truncates any character or numeric data before exiting the field.

A Config statement can be used to override (control) grid cursor movement. When this is used, both Field +/- and Enter produce the same cursor movement:

GRID_CURSOR_MOVE DOWN | RIGHT | NONE | DEFAULT

This determines the field cursor position after keying Enter or Field +/-. Both navigation and edit mode produce the same resulting cursor position.

====Restoring a User Sorted 2D Control====

In versions 4.3 and higher the syntax for sorting a listview is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }

This has been extended to allow a numeric array instead of a scalar. If an array is given, it is assumed to be in the same format that SORT_ORDER returns. The new format is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column-number | numeric-array }

Where the numeric-array has one element for each column left to right. BR will resort the columns in the requested order.

The numeric array values indicating the order of column sorting to be performed do not need to exactly match the standard format. e.g Fractions are allowed, the values can fall within any range, and there does not need to be trailing zero elements for unsorted columns.

==== A multi column LISTview ====

01000 PRINT FIELDS "10,20,LIST 10/80,HEADERS,[HDRS][,fkey]": (MAT HEADINGS$,MAT WIDTHS, MAT FORMS$)

'''Note:''' Widths are expressed in character positions.

The [HDRS] notation refers to an optional CONFIG ATTRIBUTE HDRS specification for setting the appearance of the header row. In this case the brackets [] are required and the term HDRS may be any bracketed attribute name.

If a function key value (e.g. 1520) is given then when the control is not active, it may be clicked to trigger the specified interrupt similar to any other hot control. A function key interrupt is also triggered by double clicking during an Input operation.

{|
|- valign="top"
| width="10%" | '''MAT HEADINGS$'''
| Specifies the titles that will appear at the top of each column in the List or Grid. The format of this row may be specified by an optional parameter following HEADERS in the above example.
|}

{|
|- valign="top"
| width="10%" | '''MAT WIDTHS'''
| Specifies the number of characters in each column. For example if four columns are specified and the widths are given as 10, 15, 10 and 5, then the 2D control occupies 40 character positions (plus a little for the column separators) irrespective of the number of columns specified for the display area. If needed, scroll bars are used to display wider controls within the displayed area.
|}

{|
|- valign="top"
| width="10%" | '''MAT FORMS$'''
| Specifies the display characteristics of each column such as "C 12" or "PIC(z,zzz,zz#.##-)". A "P" following the display parameter will cause the field to be protected and no data entry will be allowed in GRID mode.
|}

 The field form array elements may also include a trailing comma followed by field attributes (e.g. color) that pertain to the column.

PRINT FIELDS "10,20,LIST 10/80, = [,fkey]": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

In this example, the fourth element of the HEADERS FIELD_FORM$ array (above) could specify rounding of WEIGHT to two decimal places. If an fkey value is specified, then double-clicking (or single clicking if S is specified) a cell will generate the specified fkey interrupt.

==== Reading a Listview or Grid ====
When using INPUT FIELDS to read from a 2D control, the leading attributes specification states the type of read operation and the trailing attributes specification is the type of cell or row selection to be performed. The third parameter can optionally specify NOWAIT or an FKEY value. If it is an FKEY value, it signifies that an FKEY event should be triggered when, in navigation mode, a selection is made by double clicking or pressing the Enter key.

===== Syntax =====

[[Image:Grid.png|950px]]

=====Parameters=====
Quotation marks must surround the specifications, and individual parts must be separated by commas.

'''Row''' and '''Column''' specify the space where the grid or list begins.

'''List''' or '''Grid''', followed by rows and columns separated by a slash determine how big the list or grid is going to be. The main difference between a list and grid is that lists are for selection only while information can be added to grids directly.

The following '''Read Types''' are valid for both grids and lists:

{|
|- valign="top"
| width="10%" | '''RowCnt'''
| The number of rows specified.
|- valign="top"
| width="10%" | '''RowSub'''
| The subscripts of the specified rows.
|- valign="top"
| width="10%" | '''Row'''
| Read all cells in each specified row.
|- valign="top"
| width="10%" | '''Colcnt'''
|The number of columns established by the header arrays. e.g. INPUT FIELDS "row,col,LIST rows/cols, COLCNT, ALL" : numeric-variable
|- valign="top"
| width="10%" | '''Sort_Order'''
|(4.3+) Provides a value of zero for each unsorted column and gives the ascending sequence of column sorts that have occurred. If a column has been reversed (double sorted) it's value will be negative. The selection typed used must be ALL. For example: INPUT FIELDS "row,col,GRID rows/cols, SORT_ORDER, ALL" : Mat NumArray, with the following history of sorting a four column GRID:
column 1 (descending most recent)
column 2 (ascending first sorted)
column 3 (not sorted)
column 4 (sorted ascending)

SORT_ORDER would return-
array(1) -> -1
array(2) -> 3
array(3) -> 0
array(4) -> 2
|- valign="top"
| width="10%" | '''HEADERS'''
|(As of 4.30) The read operation returns the original PRINT FIELDS HEADER values. For example: INPUT FIELDS "row,col,LIST rows/cols, HEADERS,ALL,NOWAIT" : (MAT HEADINGS$,MAT WIDTHS, MAT FORMS$) The selection type used must be ALL.
|- valign="top"
| width="10%" | '''MASK'''
|(As of 4.30) MASK can be used with Grids and Lists. As a READ type, this reads the display mask setting, including listviews that have been displayed according to a [[filter]] or filterbox. For example: INPUT FIELDS "row,col,LIST rows/cols,MASK [,NOWAIT]" : mask_array. The mask array affects only the user presentation and not the data. Use RANGE processing or the CHG selection type to selectively read from a 2D control.
|}

These Read Types are valid for Grids only:

{|
|- valign="top"
| width="10%" | '''Cnt'''
| Specify the number of cells specified (see selection types below).
|- valign="top"
| width="10%" | '''Sub'''
| Read the Cell Subscript Values (see example below).
|- valign="top"
| width="10%" | '''Cell'''
| Read each cell specified.
|}

For the "Sel-type" parameter, the following selection types are valid for both grids and lists:

{|
|- valign="top"
| width="10%" | '''Sel'''
| Read one or more selected items.
|- valign="top"
| width="10%" | '''SelOne'''
| Select only one item.
|- valign="top"
| width="10%" | '''All'''
| Read all items in the control (except headings).
|- valign="top"
| width="10%" | '''Cur'''
| Current cell or row number.
|- valign="top"
| width="10%" | '''Next (4.2+)'''
| The cell the cursor is going to next if the user moved it using an arrow or a mouse click.
|- valign="top"
| width="10%" | '''Range'''
|Specifies which portion of a 2D control is to be input. (As of 4.3) [[#Range Input|See Below]].
|- valign="top"
| width="10%" | '''Cell_Range'''
|A special type of output range. (As of 4.3) [[#Range Input|See Below]].
|}

This Selection Type is valid for Grids only:

{|
|- valign="top"
| width="10%" | '''Chg'''
| All items changed since the last '=' populate or the last CHG retrieval of cell/row contents.
|}

The '''Read Qualifier''' is an optional parameter to help the read. As of 4.3 it can be [[DISPLAYED_ORDER]]. #[[PIC]] or #[[FMT]] could be used. #PIC and #FMT allow numeric data from a string to be used. For example: '''DISPLAYED_ORDER''' Indicates that the read operation is to not restore the data into it's original order before returning the results to the program (as of version 4.30). This reads the original row subscripts for all rows - in their present order - and only works with the ALL selection type.

GRIDLINES makes LIST controls look like GRIDs with respect to the display of data (column and row separators).
PRINT FIELDS "10,20,LIST 10/80,GRIDLINES": 1 | 0 (on or off)

The leading attribute values "^select" or "^deselect" may be specified to allow the pre-selection of GRID / LIST Elements:
PRINT FIELDS "nn,nn,GRID 10/40,^select ATTR": (mat start, mat end, mat attr$)

The '''Fkey''' and '''Nowait''' parameters are optional. FKEY means that an FKEY event should be triggered when a selection is made by double clicking or pressing the Enter key, in navigation mode. Nowait simply means that it does not wait for user input.

Following the ending quotation mark, a colon precedes the name of the I/O List.

====DISPLAYED ORDER '''Read Qualifier'''====

As of 4.30, [[DISPLAYED ORDER]] - indicates that the read operation is to not restore the data into it's original order before returning the results to the program, for example:

INPUT FIELDS "row,col,LIST rows/cols, ROWSUB, ALL, DISPLAYED_ORDER, NOWAIT": numeric-array

This reads the original row subscripts for all rows in their present order. This qualifier works only with the ALL selection type. It may be used in conjunction with other qualifiers such as FKEY.

==== Examples ====

===== LIST =====

00210 INPUT FIELDS "10,20,LIST 10/80,ROWCNT,SEL,FKEY": avail_rows ! selected row cnt
00220 ! next INPUT operation does not wait for operator
00230 MAT subscr(avail_rows)  ! redimension with number of selected rows
00240 INPUT FIELDS "10,20,LIST 10/80,ROWSUB,SEL,NOWAIT": MAT subscr ! read subscripts

===== Uniform GRID =====
Contains one data array and multiple columns

00210 INPUT FIELDS "10,20,GRID 10/80,CNT,CHG": cells  ! # of changed cells
00220 MAT subscr(cells)  ! redimension
00230 INPUT FIELDS "10,20,GRID 10/80,SUB,CHG,NOWAIT": MAT subscr ! read subscripts
00240 MAT data$(cells)  ! redimension
00250 INPUT FIELDS "10,20,GRID 10/80,CELL,CHG,NOWAIT": MAT data$ ! read changes

===== Row Oriented GRID =====
00210 INPUT FIELDS "10,20,GRID 10/80,ROWCNT,CHG": rows  ! # of changed rows
00220 MAT subscr(rows)  ! redimension
00230 INPUT FIELDS "10,20,GRID 10/80,ROWSUB,CHG,NOWAIT": MAT subscr ! read subscripts
00240 MAT NAME$(rows) : MAT CITY$(rows) : MAT AGE(rows) : MAT WEIGHT(rows) ! redimension
00250 INPUT FIELDS "10,20,GRID 10/80,ROW,CHG,NOWAIT": (MAT NAME$, MAT CITY$,MAT AGE, MAT WEIGHT)  ! read changed rows

This brings us to the question of what is to be done with the information after it has been read. If it is to be stored in a file, then we should have included a hidden column with master file record numbers of the data in each row. This would support looping through the input array and rewriting the changed data.

While LIST subscripts are expressed in terms of rows, GRID subscripts may be either. In a four column five row GRID, the cell at row three column two has a subscript of ten.

==== Cell Subscript Values of a 5 x 4 GRID ====

1 2 3 4
5 6 7 8
9 10 11 12
13 14 15 16
17 18 19 20

==== Sample Program====
The following example shows use of LIST and GRID controls. There are seven parts in this program.

The first part creates a LIST with 2 columns and 3 rows. On lines 300 - 500, column headings, widths, and form specifications are assigned to the corresponding matrices. Lines 600 and 700 place data into the matrices to be printed in the LIST. The HEADERS operation on line 800 sets the column headings, widths and form specs. Line 900 populates the LIST by row, which is the default.

00100 dim HEADINGS$(2), WIDTHS(2), FORMS$(2), NAMES$(3)*28, CITIES$(3)*18, DATA$(1)*80, SUBSCR(1)
00200 print NEWPAGE
00300 let HEADINGS$(1)="Name": let HEADINGS$(2)="City"
00400 let WIDTHS(1)=30 : let WIDTHS(2)=20
00500 let FORMS$(1)="CC 28" : let FORMS$(2)="CC 18"
00600 let NAMES$(1)="Stalin" : let NAMES$(2)="Napoleon" : let NAMES$(3)="Roosevelt"
00700 let CITIES$(1)="Moscow" : let CITIES$(2)="Paris" : let CITIES$(3)="Washington"
00800 print fields "1,1,list 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$)
00900 print fields "1,1,list 8/60,=R": (MAT NAMES$,MAT CITIES$)
01000 print fields "9,1,C 50" : "Press enter to insert at the end of list"
01100 let KSTAT$(1)

===== Output =====

[[Image:Output1.jpg]]

The second part of the program demonstrates the use of the primary flag +, which adds to the end of any previously populated data. Line 01200 redimensions matrices NAMES$ and CITIES$ to allow room for one extra item in each of them. Line 01300 places new data into the matrices to be printed in the LIST. Line 01400 adds the new data to the LIST.

01200 mat NAMES$(UDIM(NAMES$)+1) : mat CITIES$(UDIM(CITIES$)+1)
01300 let NAMES$(4)="Churchill" : let CITIES$(4)="London"
01400 print fields "1,1,list 8/60,+": (MAT NAMES$(4:4),MAT CITIES$(4:4))
01500 print fields "9,1,C 50" : "Select rows to be read into a matrix"

===== Output =====

[[Image:Output2.jpg]]

The third part of the program demonstrates use of read types ROWSUB and ROWCNT and selection type SEL. Line 1600 inputs the number of selected rows into AVAIL_ROWS. The user may select rows using the mouse or the keyboard and SHIFT and CTRL keys. Line 1700 redimensions matrix SUBSCR to the number of selected rows. Line 1800 inputs the subscripts of the selected rows into matrix SUBSCR. Line 1900 performs a HEADERS operation for a new LIST using the same matrices as were used in the previous LIST. Line 2000 populates the first row of the new LIST with the data from the first selected row from the previous LIST using the primary flag =. If user selects more than one row, then lines 2100 - 2500 add the data from the selected rows using the primary flag +.

01600 input fields "1,1,list 8/60,ROWCNT,SEL": AVAIL_ROWS
01700 mat SUBSCR(AVAIL_ROWS)
01800 input fields "1,1,list 8/60,rowsub,sel,nowait": MAT SUBSCR
01900 print fields "12,1,list 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$)
02000 print fields "12,1,list 8/60,=": (MAT NAMES$(SUBSCR(1):SUBSCR(1)),MAT CITIES$(SUBSCR(1):SUBSCR(1)))
02100 if UDIM(SUBSCR) > 1 then
02200 for I = 2 to UDIM(SUBSCR)
02300 print fields "12,1,list 8/60,+": ( MAT NAMES$(SUBSCR(I):SUBSCR(I)),MAT CITIES$(SUBSCR(I):SUBSCR(I)))
02400 next I
02500 end if
02600 print fields "9,1,C 50" : "Press enter to insert at beginning of list"

===== Output =====

[[Image:Output3.jpg]]

The fourth part of the program demonstrates the use of the primary flag -, which inserts in the beginning of any previously populated data. Line 2800 redimensions matrices NAMES$ and CITIES$ to allow room for one extra item in each of them. Line 2900 places new data into the matrices to be printed in the LIST. Line 3000 adds the new data to the beginning of the LIST ahead of previously populated data.

02700 let KSTAT$(1)
02800 mat NAMES$(UDIM(NAMES$)+1): mat CITIES$(UDIM(CITIES$)+1)
02900 let NAMES$(5)="Castro" :! let CITIES$(5)="Havana"
03000 print fields "1,1,list 8/60,-": (MAT NAMES$(5:5),MAT CITIES$(5:5))
03100 print fields "9,1,C 60" : "Press enter to populate list by column"

===== Output =====

[[Image:Output4.jpg]]

The fifth part of the program, more specifically, Line 3300, demonstrates the use of the secondary flag C to populate the LIST by column. The primary flag = is also used in order to replace any previously populated data.

03200 let KSTAT$(1)
03300 print fields "1,1,list 8/60,=C": (MAT NAMES$,MAT CITIES$)

===== Output =====

[[Image:Output5.jpg]]

The sixth part of the program creates a GRID. The HEADERS operation on line 3600 uses the same HEADINGS$, WIDTHS, and FORMS$ as the previously constructed LISTs. Line 3700 sets CURFLD to be on the sixth cell of the GRID (this is discussed in the next section). Line 3800 populates the GRID. The user may change the contents of the cells.

03400 print fields "23,1,C 50" : "Press enter to continue": let KSTAT$(1)
03500 print NEWPAGE
03600 print fields "1,1,grid 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$)
03700 let CURFLD (1,6)
03800 print fields "1,1,grid 8/60,=": (MAT NAMES$,MAT CITIES$)

===== Output =====

[[Image:Output6.jpg]]

The seventh part of the program demonstrates the use of read types CNT, CELL, and SUB and selection type CHG. Line 3900 counts the number of changed cells and inputs that number into variable CELLS. Line 4000 redimensions the matrix SUBSCR to the number of changed cells. Line 4100 inputs the changed cells into SUBSCR. Line 4200 redimensions the matrix DATA$. Line 4300 inputs the subscripts of the changed cells into matrix DATA$. Line 4400 prints DATA$.

03900 input fields "1,1,grid 8/60,cnt,chg": CELLS
04000 mat SUBSCR(CELLS)
04100 input fields "1,1,grid 8/60,sub,chg,nowait": MAT SUBSCR
04200 mat DATA$(CELLS)
04300 input fields "1,1,grid 8/60,cell,chg,nowait": MAT DATA$
04400 print MAT DATA$

===== Output =====

[[Image:Output6b.jpg]]

===== Output of line 04400 =====

[[Image:Output7.jpg]]

=== Displaying a List or Grid (Output Operations) ===
[[file:Grid2.png|900px]]

To display a listview or a grid, you must set the headers first, using a special PRINT FIELDS operation.

====HEADERS====
The HEADERS operation sets the column headings and widths. The corresponding input/output list value must be a parenthesized group of three arrays, for example:

00250 PRINT FIELDS "10,20,LIST 10/80,HEADERS": (MAT HEADINGS$, MAT WIDTHS, MAT FIELD_FORMS$)
- or -
00250 PRINT FIELDS "10,20,GRID 10/80,HEADERS,[hdrs],1520": (MAT HEADINGS$, MAT WIDTHS,MAT FIELD_FORMS$)

The [hdrs] notation refers to an optional CONFIG ATTRIBUTE [HDRS] specification for setting the appearance of the header row. In this case the [] brackets are required.

If a function key value (e.g. 1520) is given then when the control is not active, it may be clicked to trigger the specified interrupt similar to any other hot control. A function key interrupt is also triggered by double clicking during an Input operation.

MAT HEADINGS$ Contains the column titles that will be displayed at the top of each column. The font, color and shading of these titles can be set through the [HDRS] or similar substitution attribute.

MAT WIDTHS specifies DISPLAYED Column Widths and is expressed as the number of character positions occupied by each column. Scrollbars are provided as needed to honor overall control size specified in the FIELDS specification.

For example, if four columns are specified and the widths are given as 10, 15, 10 and 5, then the 2D control occupies 40 character positions (plus a little for the column separators) irrespective of the number of columns specified for the display area. If needed, scroll bars are used to display wider controls within the displayed area.

Displayed widths of zero characters are allowed. This enables the use of hidden columns for storing things like record numbers and record keys.

MAT FIELD_FORMS$ provides the BR FORM for each column. e.g. C 15 stipulates a maximum field capacity of 15. The actual displayed length is a function of the grid size and the column relative width.

The field form array elements may also include a comma followed by leading field attributes (e.g. color) pertaining to the column.

The number of columns must be set with HEADERS prior to Populating a control (loading data into it).

====MASKing====

As of 4.3, LIST and GRID support the MASK operation, both in READs and Populating, as seen in this section. For example:

PRINT FIELDS "row,col,LIST rows/cols,MASK" : mask_array

This restricts the rows (for both LIST and GRID) previously displayed to those corresponding to a “true” value in mask_array. A true value is represented in a numeric array as a value greater than zero. Negative values are not allowed in mask arrays. A string mask array may also be used with “T” and “F” values. The MASK stays in effect until 1) a new MASK is specified or 2) the contents of the control are changed with PRINT ( <nowiki>=, +, -,</nowiki> see primary flags below). Also, the mask array affects only the user presentation, not the result set.

====Populating====

The populate operation loads data into the control. In the following example four columns are loaded:

03010 PRINT FIELDS "10,20,LIST 10/80, =": (MAT NAME$, MAT CITY$,MAT AGE, MAT WEIGHT)
- or -
03020 PRINT FIELDS "10,20,GRID 10/80, =": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

In this example, the fourth element of the HEADERS FIELD_FORM$ array (above) could specify rounding of WEIGHT to two decimal places. If an fkey value is specified, then double-clicking (or single clicking if S is specified) a cell will generate the specified fkey interrupt.

Permissible leading attribute values are:

===== Primary Flags =====

{|
|- valign="top"
| width="10%" | '''='''
| Replace any previous data
|- valign="top"
| width="10%" | '''+'''
| Add to any previously populated data (this allows loading in chunks)
|}

{|
|- valign="top"
| width="10%" | '''-'''
| Insert data ahead of previously populated data (4.16+)
|}

==== Secondary Flags ====

{|
|- valign="top"
| width="10%" | '''R'''
| Load one row at a time (the default - use grouped IO parens)
|- valign="top"
| width="10%" | '''C'''
| Load one column at a time - This is for loading multiple columns of the same data type
|- valign="top"
| width="10%" | '''L'''
| Provide the FKEY (see INPUT below) or Enter interrupt if the user presses up arrow or page up in the first field, or down arrow or page down in the last field. Note that this is not specified in the individual field leading attributes.
|- valign="top"
| width="10%" | '''S'''
| Single click to activate an Enter or FKEY event (otherwise a double click is required) (4.17+)
|}

 Note that the following example will NOT work-

00100 PRINT FIELDS "10,20,LIST 10/80,=C": MAT NAME$,MAT CITY$,MAT AGE,MAT WEIGHT

The reason is that only MAT NAME$ will reach the list. MAT CITY$, MAT AGE and MAT WEIGHT will be associated with subsequent fields. Multiple arrays provided to a single control must be grouped with parentheses.

Populating a two-dimensional object by row with grouped IO means NAME$(1) will go into (1,1), AGE(1) will go into (1,2) and WGT(1) will go into (1,3) and so on. If a single array (MAT DATA$) is specified instead of a group, MAT DATA$ is applied horizontally instead of vertically. So DATA$(1) - DATA$(3) will be the first row and DATA$(4) - DATA$(6) will be the next row and so on.

Populating a two dimensional grid by column with an array named DATA$ means that DATA$(1) goes in (1,1) and DATA$(2) goes in (2,1) and DATA$(3) goes in (3,1). Therefore the first however many values of DATA refer to the first column and the second however many values of DATA refer to the second column. So if there are 3 columns and UDIM(DATA$) = 90 then DATA$(1)-DATA$(30) is the first column, and DATA$(31) - DATA$(60) is the second column and DATA$(61) - DATA$(90) is the last column.

For example, using the following information, each example demonstrates how the grid will be filled:

MAT NAME$ = George, Peter, Tom

MAT CITY$ = Dallas, Detroit, Denver

MAT AGE$ = 42, 23, 35

MAT WEIGHT$ = 180, 212, 193

00200 PRINT FIELDS "10,20,GRID 10/80, =": (MAT NAME$, MAT CITY$,MAT AGE$, MAT WEIGHT$)

Peter, Detroit, 23, 212

Tom, Denver, 35, 193

00200 PRINT FIELDS "10,20,GRID 10/80, =C": (MAT NAME$, MAT CITY$,MAT AGE$, MAT WEIGHT$)

Dallas, Detroit, Denver

42, 23, 35

180, 212, 193

As you can see using C with grouped arrays is counter-intuitive and doesn't fit well. C is most useful with a single array that should be loaded vertically down several columns.

===== Grid Validation =====

GRIDs are now validated as each cell is exited instead of when control is passed to the BR program after all data is entered.

===== Color and Font changes in Cells =====

The attributes that determine font, color and style in each cell can be set for an entire column by including these parameters in the heading FORM array. Individual cells can then be changed using a PRINT statement.

The format of the print statement is

00100 PRINT #WINNO, fields "2,2,LIST 10/60,ATTR":(mat start, mat end, mat attribute$)

With the following parameter descriptions:

{|
|- valign="top"
| width="10%" | '''mat start'''
| contains the cell number(s) where the attribute chain begins,
|- valign="top"
| width="10%" | '''mat end'''
| contains the last cell number where the attribute applies
|- valign="top"
| width="10%" | '''mat attribute$'''
| contains the attribute specification that should be applied to the cell range(s) specified.
|}

If the 2d control is a GRID, then mat Start and mat End refer to starting and ending Cell Numbers. If the 2d control is a listview, then mat Start and mat End refer to starting and ending Row Numbers.

The attributes specified for any COLUMN can be overridden on a cell basis by specifying the starting cell number, ending cell number, and the overriding attributes in three arrays that are printed to the grid window with the same grid specificatoins and the key word "ATTR".

02420 PRINT #BLISTWIN,FIELDS BLISTSPEC$&",ATTR": (MAT BROWS,MAT BROWE,MAT BATT$)

In the above example, BLISTWIN is the window number, BLISTSPEC$ is the grid specification ("GRID 10/40" for example), BROWS is an array holding the starting cell number, BROWE is an array holding the ending cell number, and BATT$ is an array holding the overriding attributes. In a list the attributes of the first cell in the row controls the appearance of the entire row.

01500 PRINT FIELDS "nn,nn,GRID 10/40,ATTR": (mat start, mat end, mat attr$)

The above example overrides the attributes of a range of cells/rows for a GRID/LIST display. This allows you to shade or otherwise alter the display of a range of cells / rows in a 2D control.

====Aggregate Sorting====
BR supports aggregated sorting for LISTs and GRIDs. This means when clicking
on various column headings or programmatically sorting columns, fields of
equal values retain their previous order within their new groupings (4.2).

==== Numeric Column Sorting ====

2D controls now facilitate numeric column sorting. This works well in conjunction with the new [[Date (Format Specification)|DATE]] field format (see release notes [[4.16]]) where the data is stored as day of century, but is displayed as a formatted date. It also works with all numeric columns.

If a listview columns form spec if given as DATE(mm/dd/ccyy), for example, then any time that column is sorted, either as a result of the user clicking on the column heading, or the program giving the sort command (shown below), the dates are properly sorted even though they're displayed as mm/dd/ccyy. For this to work, the data has to be given in the julian days format, see the [[DAYS]] function for more information.

In versions 4.2 and higher the syntax for sorting a listview is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }

To sort in reverse order, sort the column twice:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }
PRINT FIELDS "nn,nn,GRID 10/40,SORT": { same column number }

This has been extended in version 4.3 to allow a numeric array instead of a scalar. If an array is given, it is assumed to be in the same format that SORT_ORDER returns. The new format is:

PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column-number | numeric-array }

Where the numeric-array has one element for each column left to right. BR will resort the columns in the requested order.

The numeric array values indicating the order of column sorting to be performed do not need to exactly match the standard format. e.g Fractions are allowed, the values can fall within any range, and there does not need to be trailing zero elements for unsorted columns.

==== NOSORT for Columns ====
As of 4.2, the '''NoSort''' parameter is used to prevent users from sorting columns of a Grid or List.

For the statement:

PRINT FIELDS "10,20,GRID 10/80,HEADERS,[hdrs],1520": (MAT HEADINGS$, MAT WIDTHS, MAT FIELD_FORMS$)

The field attribute "^nosort" appearing in the MAT FIELD_FORM$ prevents the sorting of a grid or listview in response to the user clicking on the corresponding column header. This does not prevent programs from sorting on those columns.

==== Range Input ====

The following examples are used in versions 4.3 and higher. In these examples BR will redimension the receiving arrays as needed:

INPUT FIELDS "row,col,LIST rows/cols, CELL, RANGE" :
start, end, MAT Data$

This reads the specified range of cells. BR redimensions MAT Data$ as needed. Note that CELL may now be used with LIST. Previously, LISTs were only addressable by row.

INPUT FIELDS "row,col,LIST rows/cols, ROW, RANGE" :
(start:=7), (end:=11), ( MAT Array1$, MAT Array2, MAT Array3$ )

This reads the cells in rows 7 through 11. The receiving arrays are re-dimensioned as appropriate.

INPUT FIELDS "row,col,GRID rows/cols, ROW, RANGE":
MAT start, MAT end, ( MAT Data1$, MAT Data2$, MAT Data3 )

This reads one or more ranges of rows.

A more detailed example of this is:

100 ! create and populate a LIST control
200 MAT START(3) : MAT END(3)
210 READ MAT START, MAT END
220 DATA 7,21,33
230 DATA 11,21,38
240 INPUT FIELDS "row,col,LIST rows/cols, ROW, RANGE" : MAT START,
MAT END, ( MAT Array1$, MAT Array2, MAT Array3$ )

This reads 12 rows of data ( row 7-11, row 21 and rows 33-38 ).

==== Range Output ====

The following examples are valid for versions [[4.3]] and higher. By default, RANGE output refers to rows. The special keyword CELL_RANGE is used to denote the specification of cell ranges. Additionally, the use of scalars versus arrays for start and end values determines important characteristics of the output process.

 Using Scalars For Range Specification

PRINT FIELDS "7,8,GRID 10/75, RANGE": start, end, MAT Data$

This replaces the values in rows numbered 'start' through 'end' with the data in MAT Data$. The size of MAT Data$ must be a multiple of the number of columns in the GRID or an error is generated.

PRINT FIELDS "7,8,LIST 10/75, RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

This replaces the values in ROWs numbered 'start' through 'end' with the data from MATs NAME$, CITY$, AGE and WEIGHT. The data arrays must all be dimensioned the same.

==== Insertion and Deletion with RANGE ====

The number of rows being output do not need to match the number of rows being replaced. To delete a range of rows, output one or more grouped arrays with zero elements.

The following examples are valid for versions 4.3 and higher. Using the following statement, various scenarios are described.

PRINT FIELDS "7,8,LIST 10/75, RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

start=7, end=11, and the arrays have been DIMed to nine elements
Result- Nine rows replace five, and the total content of the control is expanded by 4 rows.

start=7, end=11, and the arrays are DIMed to zero elements
Result- Five rows are deleted, and the total size of the control is reduced by 5 rows.

start=7, end=0 (anything less than 7), and the arrays are DIMed to support three rows
Result- Three rows are inserted ahead of row seven and the total content of the control is expanded by three rows

start=5000, end={any value}, the control only has 482 rows, and the source arrays are DIMed to support eleven rows
Result- Eleven rows are appended to the end of the control and become rows 483 through 493.

==== Outputting Ranges of Cells ====

The following examples are valid for versions 4.3 and higher.

Ranges of cells may be output in conjunction with the CELL_RANGE keyword.

PRINT FIELDS "7,8,LIST 10/75, CELL_RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)
- or -

PRINT FIELDS "7,8,GRID 10/75, CELL_RANGE": start, end, MAT Data$

In this case, start and end specify cells instead of rows. If insertion or deletion is indicated by dimensioning the data arrays to greater or fewer elements than are being replaced, then the data must be a multiple of the number of columns. Insertion and deletion is only valid in terms of rows, even when cell subscripts are used to specify ranges. In such cases, if the cell subscripts are not on row boundaries, an error is generated.

PRINT FIELDS "7,8,GRID 10/75, CELL_RANGE": start, start, Data$

In this example, the value in one cell is replaced with the content of a scalar.

==== Using Arrays For Range Specification ====

If the start and end specifications are array denoting multiple ranges, there must be a one to one correspondence between the number of rows specified and those in the data. This method implies replacement only and insertion or deletion is not allowed.

The data flow that this feature was designed to support is one where the user is presented with a LIST or GRID where multiple rows have been either selected or changed before returning control to the program and the program is responding by updating something on those rows.

The program begins by presenting a 2D control to the user and reading the the control with type ROWSUB or SUB. Type SUB only works for GRIDs where all colmns have the same data type. Of course the subscripts are read into a numeric array which BR redimensions as appropriate. Then the program reads the changed or selected data with NOWAIT. (This resets the CHG flags in the control.) The program then changes either row (ROWSUB) or cell (SUB) data and outputs the results using the subscript array as both the start and end specification. Other scenarios are possible but this is the primary intended use.

The following examples are valid for versions 4.3 and higher:

100 ! create and populate a GRID --
200 INPUT FIELDS "row,col,GRID rows/cols,ROWSUB,CHG": MAT Rowsubs
(Reading subscripts does not reset the CHG flags in the control.)
210 INPUT FIELDS "row,col,GRID rows/cols,ROW,CHG,NOWAIT": ( MAT Data1$,
MAT Data2, MAT Data3$ )
BR redimensions the receiving arrays as needed.
(Reading the data also resets the CHG flags in the control.)

220 ! process the changed rows now present in the data arrays --
300 PRINT FIELDS "row,col,GRID rows/cols,RANGE": MAT Rowsubs,
MAT Rowsubs, ( MAT Data1$, MAT Data2, MAT Data3$ )

This outputs the updated rows.

 

==== Grid and List BR_VB Similarities ====
Before introducing grids and lists in BR, similar effects could be achieved using BR_VB to work with Visual Basic. If you were familiar with BR_VB, the following notes may be of interest:

Grid and list controls work like the BR_VB interface except headers now specify the form of each column and a new input type has been added:

A multi column LISTview-

00100 PRINT FIELDS "10,20,LIST 10/80,HEADERS[,hdrs][,fkey]": (MAT HEADINGS$, MAT WIDTHS, MAT FORMS$)

'''Note-''' Widths are expressed in character positions, not percentages like they are in BR_VB.

The populate operation-

00200 PRINT FIELDS "10,20,LIST 10/80,=": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)

Read-Ctl type: CNT (in place of CELLROWSUB) returns a single numeric value which is the number of subscripts available to read. In the case of grids, this is the number of cells. In the case of LISTviews, this is the number of rows.

00110 INPUT FIELDS "10,20,LIST 10/80,ROWCNT,SEL": avail_rows ! # of selected rows
00120 MAT DATA$(3 * avail_rows)  ! redimension.. 3 cols x selected rows
00130 INPUT FIELDS "10,20,LIST 10/80,ROW,SEL,NOWAIT": MAT DATA$ ! read rows

====See Also: ====
* [[Grids Tutorial]]
* [[0886]]

<noinclude>
[[Category:Widget]]
</noinclude>

DATABASE

2023-07-31T02:29:59Z

Gordon.dye: /* DSN */

In version 4.3 and higher [[CONFIG]] DATABASE may use one of 3 methods for connecting to SQL Sources:
*DSN
*CONNECTSTRING
*ODBC-MANAGER

===DSN===
Syntax:
CONFIG DATABASE <db-ref> DSN=<dsn-ref> [, USER= <department> | LOGIN_NAME | ? ] [, PASSWORD= <dept-password> | BR_PASSWORD | ? | PASSWORDD=<encrypted-password> ]
The ? indicates prompt

Example:
EXECUTE 'CONFIG DATABASE CLS_Data DSN="MyData" , PASSWORDD= <encrypted-password>'

''[[Encrypt$|Encrypted passwords]]'' are expressed as hexadecimal values. BR will ''[[UnHex$|Unhex]]'' the value and then ''[[Decrypt$|Decrypt]]'' it before presenting it to SQL Server.

===CONNECTSTRING (DSN Less)===
Syntax:
CONFIG DATABASE <db-ref> CONNECTSTRING="<Driver>={Microsoft Access Driver (*.mdb)} DBQ=C:\inetpub\wwwroot\BegASP\Chapter.14\Contact.mdb" [, USER= <department> | LOGIN_NAME | ? ] [, PASSWORD= <dept-password> | BR_PASSWORD | ? | PASSWORDD=<encrypted-password> ]

'''Sample Connection Strings:'''

Using a SQL Server /w SQL Login:
CONFIG database db-ref connectstring="DRIVER=SQL Server;SERVER=server;Initial Catalog=database;UID=username;PWD=password"

"db-ref" is the database reference.

"server" is the SQL Server [FQDN] or IP Address.

"database" is the [SQL Server Database].

"username" is the [SQL Server User Name].

"password" is the [SQL Server Password].

Using a SQL Server with Windows Authentication:
CONFIG database db-ref connectstring="DRIVER=SQL Server;Initial Catalog=database;Persist Security Info=True;MultipleBC_TableResultSets=True; Database=database;SERVER=server" User=LOGIN_NAME Password=BR_PASSWORD

Notice that the connection string, placed within quotes, is separate from the '''User=''' and '''Password=''' parameters. If the additional parameters are specified, BR will augment the connection string with '''UID=''' and '''PWD=''' parameters. Do not confuse connection string valid parameters with BR augmentation parameters.

"db-ref" is the database reference.

"server" is the SQL Server [FQDN] or IP Address.

"database" is the [SQL Server Database].

"username" is the [SQL Server User Name].

BR_PASSWORD will use the users Active Directory password to connect to the SQL Server.

"SQL Server" is one of several choices for SQL Server, another choice would be SQL Server Native Client 11.0.

===ODBC-MANAGER===
Syntax:
CONFIG DATABASE <db-ref> ODBC-MANAGER

Using ODBC Manager as the parameter will allow the end user to select the desired data source.

The following is a sample program that will use the ODBC-MANAGER to identify the proper connection string.
* Note: This will not work in Client Server because the operation is performed on the server and this process depends on the user's settings.

00010 PRINT Newpage
00011 IF Env$("br_model")="CLIENT_SERVER" THEN PRINT "Warning, you cannot connect to ODBC-MANAGER in Client Server Mode"
00020 EXECUTE "Config Database Test_DB ODBC-MANAGER" ERROR CONNECT_ERROR
00030 PRINT "Connection String is:" !:
PRINT Env$("STATUS.DATABASE.[TEST_DB].CONNECTSTRING")
00099 STOP
00100 CONNECT_ERROR: !
00110 PRINT "Error Connecting - Err:";Err;" Line:";Line;" Syserr:";Syserr$

[[Category:All Parameters]]

DATABASE

2023-07-31T02:19:36Z

Gordon.dye: /* DSN */

In version 4.3 and higher [[CONFIG]] DATABASE may use one of 3 methods for connecting to SQL Sources:
*DSN
*CONNECTSTRING
*ODBC-MANAGER

===DSN===
Syntax:
CONFIG DATABASE <db-ref> DSN=<dsn-ref> [, USER= <department> | LOGIN_NAME | ? ] [, PASSWORD= <dept-password> | BR_PASSWORD | ? | PASSWORDD=<encrypted-password> ]
The ? indicates prompt

Example:
EXECUTE 'CONFIG DATABASE CLS_Data DSN="MyData" , PASSWORDD= <encrypted-password>'

[[Encrypt$|Encrypted passwords]] are expressed as hexadecimal values.

===CONNECTSTRING (DSN Less)===
Syntax:
CONFIG DATABASE <db-ref> CONNECTSTRING="<Driver>={Microsoft Access Driver (*.mdb)} DBQ=C:\inetpub\wwwroot\BegASP\Chapter.14\Contact.mdb" [, USER= <department> | LOGIN_NAME | ? ] [, PASSWORD= <dept-password> | BR_PASSWORD | ? | PASSWORDD=<encrypted-password> ]

'''Sample Connection Strings:'''

Using a SQL Server /w SQL Login:
CONFIG database db-ref connectstring="DRIVER=SQL Server;SERVER=server;Initial Catalog=database;UID=username;PWD=password"

"db-ref" is the database reference.

"server" is the SQL Server [FQDN] or IP Address.

"database" is the [SQL Server Database].

"username" is the [SQL Server User Name].

"password" is the [SQL Server Password].

Using a SQL Server with Windows Authentication:
CONFIG database db-ref connectstring="DRIVER=SQL Server;Initial Catalog=database;Persist Security Info=True;MultipleBC_TableResultSets=True; Database=database;SERVER=server" User=LOGIN_NAME Password=BR_PASSWORD

Notice that the connection string, placed within quotes, is separate from the '''User=''' and '''Password=''' parameters. If the additional parameters are specified, BR will augment the connection string with '''UID=''' and '''PWD=''' parameters. Do not confuse connection string valid parameters with BR augmentation parameters.

"db-ref" is the database reference.

"server" is the SQL Server [FQDN] or IP Address.

"database" is the [SQL Server Database].

"username" is the [SQL Server User Name].

BR_PASSWORD will use the users Active Directory password to connect to the SQL Server.

"SQL Server" is one of several choices for SQL Server, another choice would be SQL Server Native Client 11.0.

===ODBC-MANAGER===
Syntax:
CONFIG DATABASE <db-ref> ODBC-MANAGER

Using ODBC Manager as the parameter will allow the end user to select the desired data source.

The following is a sample program that will use the ODBC-MANAGER to identify the proper connection string.
* Note: This will not work in Client Server because the operation is performed on the server and this process depends on the user's settings.

00010 PRINT Newpage
00011 IF Env$("br_model")="CLIENT_SERVER" THEN PRINT "Warning, you cannot connect to ODBC-MANAGER in Client Server Mode"
00020 EXECUTE "Config Database Test_DB ODBC-MANAGER" ERROR CONNECT_ERROR
00030 PRINT "Connection String is:" !:
PRINT Env$("STATUS.DATABASE.[TEST_DB].CONNECTSTRING")
00099 STOP
00100 CONNECT_ERROR: !
00110 PRINT "Error Connecting - Err:";Err;" Line:";Line;" Syserr:";Syserr$

[[Category:All Parameters]]

DATABASE

2023-07-31T02:11:32Z

Gordon.dye: /* CONNECTSTRING (DSN Less) */

In version 4.3 and higher [[CONFIG]] DATABASE may use one of 3 methods for connecting to SQL Sources:
*DSN
*CONNECTSTRING
*ODBC-MANAGER

===DSN===
Syntax:
CONFIG DATABASE <db-ref> DSN=<dsn-ref> [, USER= <department> | LOGIN_NAME | ? ] [, PASSWORD= <dept-password> | BR_PASSWORD | ? | PASSWORDD=<encrypted-password> ]
The ? indicates prompt

Example:
EXECUTE 'CONFIG DATABASE CLS_Data DSN="MyData" , PASSWORDD= <encrypted-password>'

===CONNECTSTRING (DSN Less)===
Syntax:
CONFIG DATABASE <db-ref> CONNECTSTRING="<Driver>={Microsoft Access Driver (*.mdb)} DBQ=C:\inetpub\wwwroot\BegASP\Chapter.14\Contact.mdb" [, USER= <department> | LOGIN_NAME | ? ] [, PASSWORD= <dept-password> | BR_PASSWORD | ? | PASSWORDD=<encrypted-password> ]

'''Sample Connection Strings:'''

Using a SQL Server /w SQL Login:
CONFIG database db-ref connectstring="DRIVER=SQL Server;SERVER=server;Initial Catalog=database;UID=username;PWD=password"

"db-ref" is the database reference.

"server" is the SQL Server [FQDN] or IP Address.

"database" is the [SQL Server Database].

"username" is the [SQL Server User Name].

"password" is the [SQL Server Password].

Using a SQL Server with Windows Authentication:
CONFIG database db-ref connectstring="DRIVER=SQL Server;Initial Catalog=database;Persist Security Info=True;MultipleBC_TableResultSets=True; Database=database;SERVER=server" User=LOGIN_NAME Password=BR_PASSWORD

Notice that the connection string, placed within quotes, is separate from the '''User=''' and '''Password=''' parameters. If the additional parameters are specified, BR will augment the connection string with '''UID=''' and '''PWD=''' parameters. Do not confuse connection string valid parameters with BR augmentation parameters.

"db-ref" is the database reference.

"server" is the SQL Server [FQDN] or IP Address.

"database" is the [SQL Server Database].

"username" is the [SQL Server User Name].

BR_PASSWORD will use the users Active Directory password to connect to the SQL Server.

"SQL Server" is one of several choices for SQL Server, another choice would be SQL Server Native Client 11.0.

===ODBC-MANAGER===
Syntax:
CONFIG DATABASE <db-ref> ODBC-MANAGER

Using ODBC Manager as the parameter will allow the end user to select the desired data source.

The following is a sample program that will use the ODBC-MANAGER to identify the proper connection string.
* Note: This will not work in Client Server because the operation is performed on the server and this process depends on the user's settings.

00010 PRINT Newpage
00011 IF Env$("br_model")="CLIENT_SERVER" THEN PRINT "Warning, you cannot connect to ODBC-MANAGER in Client Server Mode"
00020 EXECUTE "Config Database Test_DB ODBC-MANAGER" ERROR CONNECT_ERROR
00030 PRINT "Connection String is:" !:
PRINT Env$("STATUS.DATABASE.[TEST_DB].CONNECTSTRING")
00099 STOP
00100 CONNECT_ERROR: !
00110 PRINT "Error Connecting - Err:";Err;" Line:";Line;" Syserr:";Syserr$

[[Category:All Parameters]]

DATABASE

2023-07-31T02:09:56Z

Gordon.dye: /* CONNECTSTRING (DSN Less) */

In version 4.3 and higher [[CONFIG]] DATABASE may use one of 3 methods for connecting to SQL Sources:
*DSN
*CONNECTSTRING
*ODBC-MANAGER

===DSN===
Syntax:
CONFIG DATABASE <db-ref> DSN=<dsn-ref> [, USER= <department> | LOGIN_NAME | ? ] [, PASSWORD= <dept-password> | BR_PASSWORD | ? | PASSWORDD=<encrypted-password> ]
The ? indicates prompt

Example:
EXECUTE 'CONFIG DATABASE CLS_Data DSN="MyData" , PASSWORDD= <encrypted-password>'

===CONNECTSTRING (DSN Less)===
Syntax:
CONFIG DATABASE <db-ref> CONNECTSTRING="<Driver>={Microsoft Access Driver (*.mdb)} DBQ=C:\inetpub\wwwroot\BegASP\Chapter.14\Contact.mdb" [, USER= <department> | LOGIN_NAME | ? ] [, PASSWORD= <dept-password> | BR_PASSWORD | ? | PASSWORDD=<encrypted-password> ]

'''Sample Connection Strings:'''

Using a SQL Server /w SQL Login:
CONFIG database db-ref connectstring="DRIVER=SQL Server;SERVER=server;Initial Catalog=database;UID=username;PWD=password"

"db-ref" is the database reference.

"server" is the SQL Server [FQDN] or IP Address.

"database" is the [SQL Server Database].

"username" is the [SQL Server User Name].

"password" is the [SQL Server Password].

Using a SQL Server with Windows Authentication:
CONFIG database db-ref connectstring="DRIVER=SQL Server;Initial Catalog=database;Persist Security Info=True;MultipleBC_TableResultSets=True; Database=database;SERVER=server" User=LOGIN_NAME Password=BR_PASSWORD

Notice that the connection string, placed within quotes, is separate from the '''User=''' and '''Password=''' parameters. If the additional parameters are specified, BR will augment the connection string with '''UID=''' and '''PWD=''' parameters. Do not confuse connection string valid parameters with BR augmentation parameters.

"db-ref" is the database reference.

"server" is the SQL Server [FQDN] or IP Address.

"database" is the [SQL Server Database].

"username" is the [SQL Server User Name].

BR_PASSWORD will use the users Active Directory password to connect to the SQL Server.

"SQL Server" is one of several choices for SQL Server, another choice would be SQL Server Native Client 11.0.

===ODBC-MANAGER===
Syntax:
CONFIG DATABASE <db-ref> ODBC-MANAGER

Using ODBC Manager as the parameter will allow the end user to select the desired data source.

The following is a sample program that will use the ODBC-MANAGER to identify the proper connection string.
* Note: This will not work in Client Server because the operation is performed on the server and this process depends on the user's settings.

00010 PRINT Newpage
00011 IF Env$("br_model")="CLIENT_SERVER" THEN PRINT "Warning, you cannot connect to ODBC-MANAGER in Client Server Mode"
00020 EXECUTE "Config Database Test_DB ODBC-MANAGER" ERROR CONNECT_ERROR
00030 PRINT "Connection String is:" !:
PRINT Env$("STATUS.DATABASE.[TEST_DB].CONNECTSTRING")
00099 STOP
00100 CONNECT_ERROR: !
00110 PRINT "Error Connecting - Err:";Err;" Line:";Line;" Syserr:";Syserr$

[[Category:All Parameters]]

DATABASE

2023-07-31T01:30:56Z

Gordon.dye: /* ODBC-MANAGER */

In version 4.3 and higher [[CONFIG]] DATABASE may use one of 3 methods for connecting to SQL Sources:
*DSN
*CONNECTSTRING
*ODBC-MANAGER

===DSN===
Syntax:
CONFIG DATABASE <db-ref> DSN=<dsn-ref> [, USER= <department> | LOGIN_NAME | ? ] [, PASSWORD= <dept-password> | BR_PASSWORD | ? | PASSWORDD=<encrypted-password> ]
The ? indicates prompt

Example:
EXECUTE 'CONFIG DATABASE CLS_Data DSN="MyData" , PASSWORDD= <encrypted-password>'

===CONNECTSTRING (DSN Less)===
Syntax:
CONFIG DATABASE <db-ref> CONNECTSTRING="<Driver>={Microsoft Access Driver (*.mdb)} DBQ=C:\inetpub\wwwroot\BegASP\Chapter.14\Contact.mdb" [, USER= <department> | LOGIN_NAME | ? ] [, PASSWORD= <dept-password> | BR_PASSWORD | ? | PASSWORDD=<encrypted-password> ]

'''Sample Connection Strings:'''

Using a SQL Server /w SQL Login:
CONFIG database db-ref connectstring="DRIVER=SQL Server;SERVER=server;Initial Catalog=database;UID=username;PWD=password"

"db-ref" is the database reference.

"server" is the SQL Server [FQDN] or IP Address.

"database" is the [SQL Server Database].

"username" is the [SQL Server User Name].

"password" is the [SQL Server Password].

Using a SQL Server /w Windows Authentication:
CONFIG database db-ref connectstring="DRIVER=SQL Server;Initial Catalog=database;Persist Security Info=True;MultipleBC_TableResultSets=True; Database=database;SERVER=server" User=username Password=BR_PASSWORD

Notice that the connection string, placed within quotes, is separate from the '''User=''' and '''Password=''' parameters. If the additional parameters are specified, BR will augment the connection string with '''UID=''' and '''PWD=''' parameters. Do not confuse connection string valid parameters with BR augmentation parameters.

"db-ref" is the database reference.

"server" is the SQL Server [FQDN] or IP Address.

"database" is the [SQL Server Database].

"username" is the [SQL Server User Name].

BR_PASSWORD will use the users Active Directory password to connect to the SQL Server.

"SQL Server" is one of several choices for SQL Server, another choice would be SQL Server Native Client 11.0.

===ODBC-MANAGER===
Syntax:
CONFIG DATABASE <db-ref> ODBC-MANAGER

Using ODBC Manager as the parameter will allow the end user to select the desired data source.

The following is a sample program that will use the ODBC-MANAGER to identify the proper connection string.
* Note: This will not work in Client Server because the operation is performed on the server and this process depends on the user's settings.

00010 PRINT Newpage
00011 IF Env$("br_model")="CLIENT_SERVER" THEN PRINT "Warning, you cannot connect to ODBC-MANAGER in Client Server Mode"
00020 EXECUTE "Config Database Test_DB ODBC-MANAGER" ERROR CONNECT_ERROR
00030 PRINT "Connection String is:" !:
PRINT Env$("STATUS.DATABASE.[TEST_DB].CONNECTSTRING")
00099 STOP
00100 CONNECT_ERROR: !
00110 PRINT "Error Connecting - Err:";Err;" Line:";Line;" Syserr:";Syserr$

[[Category:All Parameters]]

DATABASE

2023-07-31T01:25:25Z

Gordon.dye: /* CONNECTSTRING (DSN Less) */

In version 4.3 and higher [[CONFIG]] DATABASE may use one of 3 methods for connecting to SQL Sources:
*DSN
*CONNECTSTRING
*ODBC-MANAGER

===DSN===
Syntax:
CONFIG DATABASE <db-ref> DSN=<dsn-ref> [, USER= <department> | LOGIN_NAME | ? ] [, PASSWORD= <dept-password> | BR_PASSWORD | ? | PASSWORDD=<encrypted-password> ]
The ? indicates prompt

Example:
EXECUTE 'CONFIG DATABASE CLS_Data DSN="MyData" , PASSWORDD= <encrypted-password>'

===CONNECTSTRING (DSN Less)===
Syntax:
CONFIG DATABASE <db-ref> CONNECTSTRING="<Driver>={Microsoft Access Driver (*.mdb)} DBQ=C:\inetpub\wwwroot\BegASP\Chapter.14\Contact.mdb" [, USER= <department> | LOGIN_NAME | ? ] [, PASSWORD= <dept-password> | BR_PASSWORD | ? | PASSWORDD=<encrypted-password> ]

'''Sample Connection Strings:'''

Using a SQL Server /w SQL Login:
CONFIG database db-ref connectstring="DRIVER=SQL Server;SERVER=server;Initial Catalog=database;UID=username;PWD=password"

"db-ref" is the database reference.

"server" is the SQL Server [FQDN] or IP Address.

"database" is the [SQL Server Database].

"username" is the [SQL Server User Name].

"password" is the [SQL Server Password].

Using a SQL Server /w Windows Authentication:
CONFIG database db-ref connectstring="DRIVER=SQL Server;Initial Catalog=database;Persist Security Info=True;MultipleBC_TableResultSets=True; Database=database;SERVER=server" User=username Password=BR_PASSWORD

Notice that the connection string, placed within quotes, is separate from the '''User=''' and '''Password=''' parameters. If the additional parameters are specified, BR will augment the connection string with '''UID=''' and '''PWD=''' parameters. Do not confuse connection string valid parameters with BR augmentation parameters.

"db-ref" is the database reference.

"server" is the SQL Server [FQDN] or IP Address.

"database" is the [SQL Server Database].

"username" is the [SQL Server User Name].

BR_PASSWORD will use the users Active Directory password to connect to the SQL Server.

"SQL Server" is one of several choices for SQL Server, another choice would be SQL Server Native Client 11.0.

===ODBC-MANAGER===
Syntax:
CONFIG DATABASE <db-ref> ODBC-MANAGER

Using ODBC Manager as the parameter will allow the end user to select the desired data source.

The following is a sample program that will use the ODBC-MANAGER to identify the proper connection string.
* Note: This will not work in Client Server

00010 PRINT Newpage
00011 IF Env$("br_model")="CLIENT_SERVER" THEN PRINT "Warning, you cannot connect to ODBC-MANAGER in Client Server Mode"
00020 EXECUTE "Config Database Test_DB ODBC-MANAGER" ERROR CONNECT_ERROR
00030 PRINT "Connection String is:" !:
PRINT Env$("STATUS.DATABASE.[TEST_DB].CONNECTSTRING")
00099 STOP
00100 CONNECT_ERROR: !
00110 PRINT "Error Connecting - Err:";Err;" Line:";Line;" Syserr:";Syserr$

[[Category:All Parameters]]

DATABASE

2023-07-31T01:17:49Z

Gordon.dye: /* DSN */

In version 4.3 and higher [[CONFIG]] DATABASE may use one of 3 methods for connecting to SQL Sources:
*DSN
*CONNECTSTRING
*ODBC-MANAGER

===DSN===
Syntax:
CONFIG DATABASE <db-ref> DSN=<dsn-ref> [, USER= <department> | LOGIN_NAME | ? ] [, PASSWORD= <dept-password> | BR_PASSWORD | ? | PASSWORDD=<encrypted-password> ]
The ? indicates prompt

Example:
EXECUTE 'CONFIG DATABASE CLS_Data DSN="MyData" , PASSWORDD= <encrypted-password>'

===CONNECTSTRING (DSN Less)===
Syntax:
CONFIG DATABASE <db-ref> CONNECTSTRING="<Driver>={Microsoft Access Driver (*.mdb)} DBQ=C:\inetpub\wwwroot\BegASP\Chapter.14\Contact.mdb"

'''Sample Connection Strings:'''

Using a SQL Server /w SQL Login:
CONFIG database db-ref connectstring="DRIVER=SQL Server;SERVER=server;Initial Catalog=database;UID=username;PWD=password"

"db-ref" is the database reference.
"server" is the SQL Server [FQDN] or IP Address
"database" is the [SQL Server Database]
"username" is the [SQL Server User Name]
"password" is the [SQL Server Password]

Using a SQL Server /w Windows Authentication:
CONFIG database db-ref connectstring="DRIVER=SQL Server;Initial Catalog=database;Persist Security Info=True;MultipleBC_TableResultSets=True; Database=database;SERVER=server" Login_Name=username Password=BR_PASSWORD

Notice that the connection string, placed within quotes, is separate from the '''Login_Name=''' and '''Password=''' parameters. If the additional parameters are specified, BR will augment the connection string with '''UID=''' and '''PWD=''' parameters. Do not confuse connection string valid parameters with BR augmentation parameters.

"db-ref" is the database reference.

"server" is the SQL Server [FQDN] or IP Address

"database" is the [SQL Server Database]

"username" is the [SQL Server User Name]

BR_PASSWORD will use the users Active Directory password to connect to the SQL Server.

"SQL Server" is one of several choices for SQL Server, another choice would be SQL Server Native Client 11.0

===ODBC-MANAGER===
Syntax:
CONFIG DATABASE <db-ref> ODBC-MANAGER

Using ODBC Manager as the parameter will allow the end user to select the desired data source.

The following is a sample program that will use the ODBC-MANAGER to identify the proper connection string.
* Note: This will not work in Client Server

00010 PRINT Newpage
00011 IF Env$("br_model")="CLIENT_SERVER" THEN PRINT "Warning, you cannot connect to ODBC-MANAGER in Client Server Mode"
00020 EXECUTE "Config Database Test_DB ODBC-MANAGER" ERROR CONNECT_ERROR
00030 PRINT "Connection String is:" !:
PRINT Env$("STATUS.DATABASE.[TEST_DB].CONNECTSTRING")
00099 STOP
00100 CONNECT_ERROR: !
00110 PRINT "Error Connecting - Err:";Err;" Line:";Line;" Syserr:";Syserr$

[[Category:All Parameters]]