Fast Track 2

Your users aren't going to be interacting with the BR console, but the GUI console. The next two sections of the tutorial are: handling Human interaction, and handling Data.

Handling Data

Variables can be filled with numeric or non-numeric values. The names of non-numeric, or string variables, must end in a $. If string variables are longer than 18 characters, they must be specified by a DIM statement, which consists of DIM, an asterisk, and the number of characters. Mathematical operations cannot be performed on strings, unless the internal function VAL(string$) is used. An operator such as the += can be used as a shortcut for "add and assign", so X+=3 is the same as X=X+3.

DIM example$*50

When the user inputs information and you can save it as individual pieces or in a matrix, using the MAT keyword. MAT can contain numeric or string values but not both. The MAT keyword must always be followed by the name of the matrix. The MAT name makes it string or numeric, just like variables with the presence or lack of a $ sign.

DIM sets the size of a matrix.

DIM X$(4)
let X$(1)="A word"
let X$(2)="B word"
let X$(3)="C word"
let X$(4)="D word"

print mat X$(3:4)

would print out

C word
D word

You can also use MAT to resize arrays:

mat X$(7) 

makes it so that X$ now contains 7 elements, the new three of which are blank.

The UDIM function returns the size of an array.

print UDIM(mat X$)

would now print out 7.

To dimension a Matrix to be one bigger than it's current unknown size, use the code:

mat X$(udim(mat x$)+1)

or

mat X$(udim(X$)+1) ! these both mean the same thing, udim is one rare exception where the mat keyword is optional.

This takes the array of X$ and makes it 1 spot bigger.

Data is often READ or INPUT into a MATrix before being processed in one way or another.

Information can be written to a file, using the WRITE and REWRITE statements. But first, you have to OPEN the file. The first time you open an internal file is when you create it.

OPEN #3: “Name=customerlist,  NEW, recl=58”: INTERNAL, OUTPUT, RELATIVE ERROR errorhandling

See Open Internal for details about each parameter.

Files

The OPEN #3 example above creates a NEW file with a record length of 58 characters.

Files can be INTERNAL, EXTERNAL, or DISPLAY files. Display files can be read in any standard text editor, while the other two are BR specific formats. They can also not be opened OUTIN, can only be accessed sequentially, and cannot be used with the INDEX command. The main difference between Internal and External files is that Internal files are BR files that have a header line which provides details about the data file, including record length. External files are opened “as is.”

Files can be opened INPUT, OUTPUT, or OUTIN. INPUT will input information from the data file to the program. OUTPUT will output information from the program to the file. OUTIN will allow for both, which makes it useful for editing your data files.

Files can be opened RELATIVE, SEQUENTIAL, or KEYED. Relative access means the record will be identified and read according to its numeric order. Sequential, the default, means that the records will be read one at a time, in order, from start to finish. Keyed means that the record will be according to a specified KEY field.

Error handling will be described later. For now, know that you can include which line the program should jump to when a specified error occurs.

Writing to a data file

WRITE #3, USING “N 8, C 50”: cusnum, email$ 

Writes the customer number and email to file #3, which we just opened. (File numbers can be replaced with labels to make your programs clearer). The N 8 means that the cusnum variable can be up to 8 digits long, while the C 50 means that the email$ variable can be up to 50 characters. These form descriptions can be put into a FORM statement and referenced by a line label, as you'll see in the READ example coming up.

Closing a data file

Closing a file is the easiest step:

CLOSE #3:

Reading a data file, and then using that information to print

Later, if we want to print out the list of names and email addresses (or use them to send out statements!) we open the file again.

OPEN #EMAIL_FILE: “Name=customerlist, recl=58”, INTERNAL, INPUT ERROR errorhandling

Reading and making changes to that information using GRID and LIST

READ #EMAIL_FILE, USING “N 8, C 50”: cusnum, email$ 

This will read the first record in the file and store it under the variable names cusnum and email$. But this is a whole list and so we will have to repeat the READ command and store the information into MAT cusnum and MAT email$. Using a For Next statement.

Emailform: form N 8, C 50
While N=1 
READ #EMAIL_FILE, USING emailform: cusnum, email$ EOF lastrecord
Loop
lastrecord: ! Read is done.

CLOSE #EMAIL_FILE:

Functions

User defined functions can do anything you want them to do. They must start with the letters FN but contain custom code. Variables can be passed in and out of functions. If something calls a function that starts with FN, then you can find the definition of that function by listing for it.

01100  def fnPrintReport(NextFileKey$;___,PN,Index,ThisVersion)
.... function code
01500  end def

In this example, the user defined function is called fnPrintReport, and the above variables are passed into it. NextFileKey$ is required, but variables following the semi-colon are optional and will be set to null if not passed in.

LIBRARIES

To remove some of the repetitiveness of coding. BR allows you to place code in functions in certain programs, which become libraries, to be used from other programs. Fileio is an example of this. It provides functions for opening, reading, writing and rewriting data by calling library functions and passing variables through them. Complete FileIO documentation is available on the wiki and from SageAX. Or you can create your own functions and libraries.

ScreenIO is another library that allows you to create programs much faster and more efficiently. It is so sophisticated that it can be considered an expression engine, similar to VB.NET.

Helpful tutorials for both FileIO and ScreenIO are available at SageAX's website.

To create a library out of the example above, simply change the DEF line to this:

01100  def LIbrary fnPrintReport(NextFileKey$;___,PN,Index,ThisVersion)

To access it from another program, use a line like this (PrReport is the name of the program the library function is found):

05000 LIBRARY "PrReport": fnPrintReport
05010 LET fnPrintReport(CurFile$)

The LET statement will run the function, passing in the variable CurFile$ to be used in the function as NextFileKey$.

NEXT: User Interaction