3. SharkBase FILES AND VARIABLES
In Conversational (interactive) SharkBase and in SharkBase programming, you are dealing with various file and variable types. These are discussed in this section.
2.1 Files
SharkBase uses different types of files; the type of the file is shown by the extension of the file name (this is called the default extension; most editors allow the user to change the extensions with two exceptions: PRG and CPL).
Data files (also called the database or "dbf" files) contain the data of the database. The default extension is DBF, example: "invoices.dbf". Data files are created with the COPY, CREATE, and COPY STRUCTURE TO commands. (See also MODIFY.)
A data file contains a header describing the structure of the data file: the number of records, the number of fields in a record, and a description of each field (name, type, width, and for numerical fields, the number of decimals). The header is followed by the data records. The normal user doesn't have access to the header, only the data itself.
There are four types of data files used by SharkBase: Type 0, Type 1, Type 2, and Type 3. From the user’s point of view, it very seldom matters which type is used, and the type is “transparent.” However, types 0,1,& 2 are available mostly for compatibility with older applications. Only Types 0 and 3 allow more than 65,535 records in a data file. Type 3 files are the universal standard now, used by dBase, Clipper, FoxPro, and all spreadsheets like OpenOffice amd LibreOffice.
A present-day example for a SharkBase user will be extracting data from a typical PayPal sales analysis report which will be an "sdf" text file. The sdf is first extracted to a spreadsheet for cleanup, and then exported to a Type 3 dbf file. Once in dbf format, the data can then be quickly sorted out by SharkBase into reports, sales summaries, etc.
Type 0 data files (the default type) can have up to 500 fields per record in SharkBase. The size of the header is commensurate with the number of fields. There is no effective limit to the number of records in the file.
Type 1 data files can have up to 256 fields per record. The size of the header is commensurate with the number of fields. Type 1 data files can accommodate up to 65,535 records.
Type 2 data files are restricted to 32 fields per record. The size of the header is fixed, it does not depend on the number of fields actually used. Type 2 data files are identical with early dBASE II data files, and can accommodate up to 65,535 records.
Type 3 data files can have up to 500 fields per record. The size of the header is commensurate with the number of fields (and is much larger than the header of a Type 1 data file with the same number of fields. SharkBase permits more fields in a file than most of the listed products (see FIELDS=), so not all of them can import SharkBase data files with many fields. There is no effective limit to the number of records in a Type 3 file. The result is the Shark dbf file is the most flexible and useful of all the alternative dBase file types.
The command CREATE can create data files of Types 0, 1, 2 and 3, although the default is Type 3. The type can be changed in MODIFY, but the default is to leave type unchanged. All Shark commands can use data files of all four types transparently.
Index files are used to facilitate rapid access to the data in data files in a predetermined order for processing and reporting. The default extension is NDX. Index files are created with the INDEX command, and are compatible with dBase NDX files. At one time there was endless discussion about which index type (NDX or NTX) was more important, but with new computers, the difference is irrelevant since even every large NDX files are created in fractions of a second. See the INDEX FROM command in the Commands section of the Reference Manual for details on converting dBase, FoxPro, VP-Info and other index files to NDX files.
Program files contain the programs. There are two kinds: the source program (a text file with SharkBase commands as text) with extension PRG and the faster compiled program with extension CPL. These extensions are compulsory! (There is one exception, the CNF configuration file; see Section 1.5.)
Report form files contain the specifications of a report. The default extension is FRM. These files are used by the REPORT command.
Memory variable files contain the memory variables saved by the SAVE TO command. The default extension is MEM.
Sequential files (also called "text" files) contain "lines". They are a specific type of plain text file. The end of each line of text is marked by carriage return (ASCII code 13) and line feed (ASCII code 10). A line can contain at most 254 characters. The end of the file is usually marked by EOF (26). A set of functions — ROPEN(, WOPEN(, READ(, WRITE(, IN(, OUT(, SSEEK(, and CLOSE( — is provided to create, read, and write sequential files in Shark programs; see individual entries in the SharkBase Functions section of the Reference Guide. Most text editors create (or have an option to create) sequential text files. Such files can then be utilized by SharkBase programs. The WRITE command of SharkBase creates and edits sequential files. Since it is used primarily to work with program files, the default extension is PRG. There are text files with the default extension TXT (e.g Notepad) used by the "SET ALTERNATE TO <file>" command.
Random files can be manipulated with another set of functions — ROPEN(, WOPEN(, GET(, PUT(, SEEK(, and CLOSE(. "Random file" is just a term for any arbitrary data file, called random because it can have data read out or written in at any arbitrary point. A typical application of the use of data files is the conversion of a data file from one type to another.
File names are requested by <file> in the command descriptions. <file> is the file name, usually, without extension. If no extension is given, then the default extension is added by SharkBase. However, if the user types in an extension, this overrules the SharkBase default extension (exceptions; PRG, CPL, and CNF are compulsory).
The file name has to follow the rules set out by the MS-DOS operating system: there are at most 8 characters in a file name (the "8.3" file name rule). You cannot go wrong if the first character is a letter and the other characters are letters and numbers; spaces are never permitted.
DOS devices include such names as PRN, CGN, AUX, LPT1, COM2, etc. Any sequential or arbitrary file function, and most of the copy and spool commands, allow you to specify either an actual file or a device. SharkBase on vDOS defaults to an "8.3" file when saving the file. SharkBase output defaults to a plain text file saved to disc. vDOS offers an add-on utility for directing output to a printer.
Technically, input/output involving files is buffered, while input/output involving devices is not. In SharkBase on MS-DOS you may choose to treat any device as either buffered or unbuffered, merely by adding a colon to the end of the name to have DOS treat it as an unbuffered device, or without a colon to designate a buffered file.
In most cases it makes little difference how you treat a device; rules for when one technique is better than another is outside the scope of this manual.
Shark on vDOS/Windows is managed by Windows, sending all output to disc to selected folders/directories. When running Shark on vDOS/Windows, vDOS will determine the direction of your output.
2.2. Selecting Data Files
Both SharkBase and SharkBase Network Edition can use up to 10 dbf data files at a time. Each data file used is assigned a file number by which the data file can be referenced. File number may be assigned in an arbitrary manner, subject to the cautions contained in Appendix A.
Before activating a file, select a file number with the SELECT command. Example: to activate the first file as the data file CUST, and third file as the data file TRANSNO:
1>SELECT 1 1>USE cust 1>SELECT 3 3>USE transno
Note how the SharkBase prompt shows the file number selected.
There are three ways to indicate which file in use is referenced:
a. Choose the file number: The choice remains in effect until otherwise specified. This is done with the SELECT command.
1>SELECT 2
selects file 2. All commands refer to it, all field names are checked in it.
b. Choose a file number for one command only: This is done by following the first word of the command by # and the file number. For instance,
1>LIST#2 NAMES
This instruction LISTS file 2, regardless of what else is presently selected. (Note: there is no space before or after the # sign.) Even if the command requires two or more words (e.g., COPY STRUCTURE TO), the first-word rule applies: COPY#2 STRUCTURE TO temp.
This technique, called command redirection, can even be used to open the data files themselves, as follows:
1>USE#1 cust l>USE#2 inven l>USE#3 transno
c. Refer to one field in a file: This is done by field redirection, following the field with # and the file number. For instance,
DAVID#4
refers to the field DAVID in file 4. In this manual, the selected file” refers to the data file currently selected. In the last series of commands, at the start, CUST is the selected file. After the command:
1>SELECT 3
TRANS is the selected file. Note that a SELECT command only selects a new file number; there may be no file used under that file number.
2.3. Variables
A SharkBase variable is a storage area in which changing values can be stored. If the storage is in a data file, it is called a field; if the storage is temporary, in the memory only, the variable is called a memory variable.
SharkBase also has a special type of variable called a system variable, including the contents of the ten function keys (when permitted by Windows), date and time, file folders, default report title, and so on. System variables are discussed in Section 2.6. The name of a system variable starts with a colon.
There can be only 128 active memory variables. Since any one of these can be a matrix variable (see Section 2.5), only the available memory limits the number of memory variables.
A variable is identified by its name. A name is 1 to 10 characters long; the first character must be a letter; the other characters are letters (converted to upper case), digits, : (full colon), and _ (underline).
Here are some examples of valid variable names:
cost ccst2 m:cost first_name
But note some exceptions:
prof 2 invalid; space is not allowed in a name; 2cost invalid; the first character must not be a number; profitcenter valid but not recommended; more than 10 characters
If the variable name is too long, only the first 10 characters are used (so PROFITCENTER1 and PROFITCENTER2 are the same for SharkBase, and will be stored as PROFITCENT).
SharkBase uses a number of words in its vocabulary, the so called SharkBase keywords (see Appendix B). It is suggested that keywords not be used as variable names. In fact, the first four letters of a variable name should be different from the first four letters of a SharkBase keyword, since SharkBase identifies a keyword by its first four letters.
A variable has a type: either character, numeric, or logical:
1. A variable of character type is also called a string variable. A string variable contains a string (a text line); it has a width, the number of characters it contains.
2. A numeric variable contains a number; it has a width (the number of digits and, optionally, a decimal point), and the number of decimals.
3. A logical variable contains a logical value: T (true, also t, Y, y) or F (false, also f, N, n).
For a field, the type and the width (and for numeric fields, the decimals) are fixed by the structure of the data file. For a memory variable, all these may change any time a new value is stored to the variable.
Fields are defined with the CREATE command, when the data file is set up, or with the MODIFY STRUCTURE command when the structure of the data file is modified. The value of fields may be changed by a number of commands: REPLACE, EDIT, BROWSE, @ GET, and so on.
Fields can also be referenced with the file name: MENU[2] is the second field of the data file MENU; TEST[210] is field 210 of the data file TEST. Thus fields can be referenced as though they are elements of a matrix.
Memory variables are defined (and redefined) with the commands: =, STORE, ACCEPT, AVERAGE, COUNT, INPUT, MAXHVIUM, MINIMUM, SUM and WAIT, and the sequential file functions IN(, GET( and READ(. WRAP( redefines the value of a memory variable. READ, EDIT, BROWSE and APPEND redefine the value of a memory variable but do not change its characteristics.
Matrix variables are handled somewhat differently; see Section 2.5.
A memory variable can be declared GLOBAL. This means that when a program is chained to another, GLOBAL variables are passed to the new program (see commands GLOBAL and CHAIN).
2.4. Variable Look-Up Rules
When SharkBase finds an expression in a command, it has to work out its value. It follows a strict order as follows to determine what the item is:
1. Is it a function? 2. Is it a numeric constant? 3. Is it a string constant? 4. Is it a system variable? 5. Is it a matrix variable? 6. Is it a redirected field (e.g. name#3)? 7. Is it a field in the selected data file? 8. Is it a memory variable? 9. Is it a logical constant?
If a name is still not found, SharkBase gives up and issues a “Variable not found” error message. Note that a variable should not have the same name as a field, and neither variables nor fields should have the same name as one of the logical constants Y, N, T, or F. The potential for puzzling behavior is obvious!
2.5. Matrix Variables
A memory variable can be defined as a matrix with the DIM command. A matrix variable is counted as only one memory variable within the 128 limit on the number of memory variables.
Any one matrix variable can occupy up to 64K memory in high memory. The available high memory is shown by the STATUS command. See the command DIM on how to compute the memory requirement, and Appendix A on how SharkBase uses memory.
Here is an example on how to define a matrix:
1>DIM NUM a[2,5] 1>a[1,1]=34.78 1>a[1,2]=45.7 1>a[2,2]=1234.71 1>a[2,4]=1000 1>? a 1>34.78 45.70 0.00 0.00 0.00 1>0.00 1234.71 0.00 1000.00 0.00
The SET WIDTH TO command can be used to influence how many items from the matrix are displayed in a line.
Matrix variables can be assigned values only with the = and STORE commands. Instead of
ok=READ( a[ 5])
write
ok=READ(temp) a[5]=temp
There is no limitation on the use of matrix variables in expressions. A matrix variable may occur at any place where a function may occur. You may think of a matrix variable as a special type of function that can store values.
The REPEAT loop is a convenient way to manipulate matrix variables.
2.6. System Variables
System variables carry information necessary for the running of SharkBase. The command LIST SYSTEM lists the system variables (with the exception of :TERMINAL). This, for example is the default system setup:
1>LIST SYSTEM Name Type Width Contents :Fl C 0 :F2 C 0 :F3 C 0 :F4 C 0 :F5 C 0 :F6 C 0 :F7 C 0 :F8 C 0 :F9 C 0 :F10 C 0 :TIME C 8 16:45:20 :DATE C 21 20150730 :VERSION C 4 110 :SERIAL C 10 1109306400 :COMPANY C 14 D+G Book Store :PICTURE C 10 9999999.99 :TITLE C 1 :UNDOC C 1 :KEY N 8 13 :AVAIL N 8 0 :FIELD N 8 0 :ERROR N 8 0 :MESSAGE N 8 :RETRY N 8 25 :USER N 8 1 :DIR C 6 C:\TMP :NEAR N 8 13 :COLOR N 8 48 ** Total ** 28 variables... 216 bytes
This sytem setup can be replaced with one of your choice by editing and saving the new setup as SHARK.CNF or SHARKNET.CNF, depending on your Shark version:
SET NETWORK off SET APRI Off SET DATE TO 'YYYYMMDD' SET INTENSITY ON; shows menu light-bar SET DIVZERO ON; div by zero produces "zero" *SET LINE ON; with SETSTEP ON useful for debugging *SET STEP ON SET EXECUTE OFF *SET END OFF SET MENU OFF SET ECHO Off SET ERROR OFF CLS :USER=99 :DATE=DATE(8) :UNDOC=PIC(DATE(8),"XXXX.XX.XX") :VERSION=DATE(4) SET COLOR TO 30; default screen color :SERIAL="COLOR 7 10 23 26 30 31 47 48 116 121" ; stores COLOR choices in a string FILES *.TXT,C:\DAT\ *.BAK,c:\BAK\ *.MSG,c:\MSG\ *.ERR,c:\ERR\ *.LOC,C:\LOC\ *.MEM,C:\MEM\ *.SCR,C:\SCR\ *.PRG,c:\PRGa\ *.FRM,C:\FRMa\ *.DTA,C:\DTAa\ *.CPL,C:\CPLa\ *.DBF,C:\DBFa\ *.NDX,C:\NDXa\ ENDFILES :F1=" " :F2=" " :F3=" " :F4=" " :F5=" " :F6=" " :F7=" " :F8=" " :F9=" " :F10=" " CHAIN START
Shark reads the new version at startup, updating the system setup with your CNF file, rearranging preferences like calendar dates, file locations, work-stations, debugging options, and adding a starting file name as you like, in this case the last line ("CHAIN START") will start your Shark session with the "START" program.
Function keys. :F1 to :F10 are the system variables activated by pressing the keys <F1> to <F10>. They can be assigned values with the commands = and STORE. Example:
:F1='street'.
NOTE: The function keys might not be replaceable in your version of Windows when running under vDOS.
or with the combination of Alt and function key. For instance, Alt-F10 assigns the contents of the command line or editing window (from its beginning to the cursor) to <F10>. See Section 1.2.
:DATE and :TIME. SharkBase stores the date and time internally. When SharkBase is started, it reads the system date and time. If you have a calendar card, the system date and time is the current date and time; otherwise, the date is January 1, 1980 (or later) and the time is 00:00:00 at the time the computer was started. (You can reset the system date and time with the operating system DATE and TIME commands.)
You can set SharkBase’s date and time:
l>:DATE='04/O5/2015' l>:TIME='08:12:56'
(mm/dd/yyyy and hh:mm:ss format).
The function TIME( returns the system time and sets :TIME to the system time. The function DATE( with one parameter (the format) returns the date from :DATE in a specific format and rewrites :DATE to this format. (See the Reference Guide.)
For instance:
1>stamp=TIME()
stores current system time to the memory variable STAMP, and resets :TIME. The command
1>REPLACE stamp WITH TIME()
does the same for the field STAMP.
A special feature is used to update the system date from the computer's internal calendar. The DATE(0) function does the trick on any computer with a BIOS chip current enough to update the system date dynamically without rebooting; some early PCs did not.
:PICTURE. The :PICTURE system variable is a format for numbers (see Formatting numbers under the @ command). This formats the display of all numeric memory variables and numeric expressions. This format can be overridden by a format clause in TEXT or an @ command, or with the PIC( function.
The system comes with :PICTURE as ’9999999.99’. If you want higher precision, say three decimals:
l>:PICTURE='999999.999'
If you do not want fractions, but want even millions:
1>:PICTURE='9999999'
The :PICTURE variable can contain format clauses with up to 12 9s, with as many as 6 on the right side of the decimal point.
It should be emphasized that the :PICTURE does not influence how SharkBase stores or computes numbers; it only tells the language how to display them.
Other system variables:
:VERSION contains the current version number of SharkBase without a decimal point; version 5.25 appears as 525.
:SERIAL may contain the serial number. Once SharkBase is loaded, you may use this as a variable that survives a CLEAR command.
:COMPANY contains the company name. This is used by the REPORT command. It can be changed to the name of the company you are reporting on.
:TITLE is the default title of a report. See the REPORT command.
:KEY is a numeric variable. It contains the number generated by the last keystroke used to exit a process or execute a command. See the function INKEY( for the definition of this number. :KEY is used in SharkBase programming to find out which key was pressed to abort or interrupt a procedure.
:AVAIL contains the number of the next available volume in the current library file. See SET LIBRARY command.
:FIELD contains the number of the Get Table entry currently being processed. See ON FIELD command.
:ERROR holds the current value of SharkBase’s internal error variable. Shows why execution of the last command failed.
:MESSAGE contains the message from the MSG file associated with the error number contained in :ERROR
:RETRY controls what happens during network operations under SharkBase Network Edition; has no meaning under other versions.
:USER is a number between 1 and 999 assigned to each user on a network under SharkBase.
:DIR is the user’s current drive letter and directory.
:NEAR contains the number of the record containing a key equal to or greater than the last FIND’s find string. See FIND command.
:COLOR holds the current value of the color attribute written into the screen memory for every byte of screen display; set with SET COLOR TO or :COLOR= command.
End of Section 3