Home Shark Introduction Shark Reference Guide Contact/Purchase Menu ☰

LIST OF ALL SHARK COMMANDS:


Command & Field Redirection
* (comment)
= (equal)
?
@ (at)
ACCEPT
APPEND
APRI
APPEND BLANK
APPEND FROM
APPEND TO
ARRAY or MATRIX
AVERAGE
BINLOAD
BINSPACE=
BINUNLOAD
BOX
BREAK
BROWSE
BROWSE FIELDS
BROWSE OFF
CALL
CANCEL
CASE
CHAIN
CLEAR
CLOSE
CLS
COLOR
COMMENT (*)
COMPILE
CONTINUE
COPY
COPY FILE
COPY STRUCTURE
COUNT
CREATE
CURSOR
DEBUG
DELAY
DELETE
DELETE FILE
DIM (Matrix or Array)
DIR
DIRF
DISPLAY
DO
DO CASE
DO WHILE
EDIT
EJECT
EDIT
ELSE
END commands
ERASE
FIELD
FIELDS=
FILES
FILES ... ENDFILES
FILES LIST
FILES=
FIND
FLUSH
GLOBAL
GO
HELP
IF
INDEX
INDEX ON
INDEX FROM
INPUT
KEY
LAST
LIMIT
LIST
LIST FILES
LIST MEMORY
LIST STRUCTURE
List SYSTEM variables
LOCATE
LOCK INDEXES
LOCK
LOOP
MATRIX or ARRAY
MAX
MIN
MODIFY
NEAREST
NOEFFECTS
NOTE
NOUPDATE
ON ERROR
ON ESCAPE
ON FIELD
ON KEY
OTHERWISE
OVERWRITE TO
PACK
PERFORM
POST
PROCEDURE
PRINT: See "SET PRINT"
PSTRING
QUIT
READ
RECALL
REINDEX
RELEASE
REMARK
RENAME
RENAME FIELD
REPEAT
REPLACE
REPORT GENERATOR
RESTORE
RESTORE GETS
RESTORE SCREEN
RETURN
RING
ROLL
RUN
SAVE
SAVE GETS
SAVE SCREEN
SCOPE
SCREEN
SCROLL
SEEK
SELECT
SET (environment controls)
SET ALTERNATE
SET COLOR
SET DATE
SET DEFAULT
SET DIR
SET FILTER
SET FORMAT
SET INDEX
SET LENGTH
SET LIBRARY
SET LINK
SET MARGIN
SET MENU [ON][OFF]
SET NETWORK [ON][OFF]
SET PRINT [ON][OFF]
SET RELATION [ON][OFF]
SET VIDEO
SET WIDTH
SETS (miscellaneous)
SKIP
SORT
SOUND
SPOOL
STATUS
STORE
STUFF
SUM
TABLES
TEXT
TOTAL
UNLOCK INDEXES
UNLOCK
UPDATE
USE
VARIABLES
WAIT
WINDOW
WRITE (WRITE command and the WRITE editor)
ZAP

COMMENT (*)

Place comments (or notes) in programs.

  
 *  <string>                             

Option:

  
 <string>   is any text line added after the asterisk (*)
 

The command * (or NOTE) is used for placing comments in a program. Shark ignores any line that starts with * (or NOTE). Since the compilation removes all the comment lines, the number of comments has no effect on the speed of the compiled program.

Notes can also be added with semicolon(;) at the END of any Shark command line. Be careful with the semicolon since placing a semicolon(;) at the BEGINNING of a line can disrupt any following Shark commands!

Example:

In a program: the three comment types are: * , ; , and NOTE as shown in the following examples:

* open employee data file:
USE employee INDEX employee  ;opening EMPLOYEE data file ordered by name
NOTE these are examples of how to include comments in a program

= (equals)

Assign value to a memory variable, or to a field when a record is referenced as a vector of fields.

 <memvar>=<exp>
 <file><num exp>=<exp>

Assigning values to memory variables. The first form of this command assigns a value to a memory variable; if the variable does not exist, it will be created. This command is equivalent to the STORE command (see STORE).

Treating a data file as a vector. The second form assigns a value to a field of a data file. In this form, [ and ] do not indicate an option, [ and ] have to be typed in. For instance, EMPLOYEE[3] is the third field, ADDR, of the EMPLOYEE data file. This is the only way to assign a value to a field with the = command. Normally, field values are assigned with the REPLACE command.

Special care must be taken when using this second form when the data file is opened with a macro (see USE). Opening a file with a macro allows a standard program to work with a wide variety of files, provided the compiler is told the data file structure.

Suppose a data file is opened with the following commands:

USE inven COMPILE
ACCEPT 'Enter name of data file to use: ' to fil_nam
USE &fil_nam

In this case, the compiled program assumes INVEN.DBF is in use, even though some other file with the same structure is actually opened. Therefore, if fil_nam='INVEN88', the proper way to reference the 3rd field of the open data file is inven[3], not inven88[3].

Examples:

1>cost=23.89
1>qty=45
1>? cost*qty
  1075.05
1>employee[1]='Steiner'
1>n=6
1>order[n+1]='Short-sleeve golf shirts'

Note that the equals sign, or the REPLACE command, (=) is the only Shark command verb that does not appear at the start of a command line. All of the following are identical in effect:

1>employee[1]='Steiner' (i.e. replace EMPLOYEE[1] with 'Steiner')
1>REPLACE employee[1] WITH 'Steiner'
1>REPLACE name WITH 'Steiner'

?

Display expression or expression list.

 ? <exp list>
 ?? <exp list>

Option:

 <exp list>   the expression or expressions to be displayed

The ? command evaluates the expression or expressions in the list (remember the commas to separate the expressions in the list!) and displays the results on a new line. In particular, this command is often used to display the contents of memory variables and fields.

The displayed items are separated by blanks if SET RAW OFF (see the SET command; on is the default). When SET RAW ON, they appear side by side.

? with no expression displays a blank line; it is used for spacing on the screen and printer.

While the ? command moves the cursor to the beginning of the next line before the items are displayed, the ?? command displays the items at the current cursor position. The ?? command is used in programs to build lines of text on the screen or on the printer from several pieces.

For displaying matrixes, see Section 2.5.

Examples:

1. Displaying fields:

1>USE employee
1>GO 5
1>? fname
Poyner
1>? fname,tel:no
Poyner          403-1193

2. Using the ? command as a calculator:

1>b=7
1>? 25/5+b,b*2,b*b
    12.00     14.00     49.00

3. A composite print line in a program segment (CUSTN and DEBIT are fields in the selected file):

amount=0
mcust=custn
? 'The amount of the invoice is: '
DO WHILE custn=mcust.AND..NOT.EOF
   amount=amount+debit
   SKIP
ENDDO
?? amount

Note how the ?? at the start of the eighth command line continues print output from the third line without a newline.

@

Display data and data input request at specific line and column position on screen or printer, or erase the screen line starting at the specified coordinates.

 @ <line,col> [SAY <exp> ][USING <format>] [GET <var>] [PICTURE
      <format>]

Example:

	EXPRESSION="   "
	@ 5,10 say EXPRESSION get VARIABLE PICTURE '999'
	READ

 line   the line number for the display, a numeric expression;
        the fractional part (if any) will be discarded

 col    the column number for the display, numeric expression;
        the fractional part (if any) will be discarded

Options:

 none    erase the screen line starting at the specified
         row and column position; when printing, move print head
         to specified position

 SAY <exp> [USING <format>]

 SAY     displays the expression, <exp>; if there is a USING clause,
         <exp> is displayed using the format specification <format>

 GET <var> [PICTURE <format>]
 GET     asks for an input into the variable <var>; the present
         contents of the <var> is displayed; if there is a
         PICTURE clause, <var> is displayed using <format>.
         The input request is activated by the READ command

Example - To manage printouts:

YESNO='N'
@ 23,18 SAY "Do you want to Print a copy?" get YESNO
READ
IF YESNO ='Y'
SET PRINT ON
LIST 
SET PRINT OFF
ENDIF

The @ command is used in Shark programs, first, to display formatted data at specific locations on the screen or printer, and second, to prompt the user to type in data (in conjunction with the READ command). Example:


EXPRESSION="   "
@ 5,10 say EXPRESSION get VARIABLE PICTURE '999'
READ

If the SET FORMAT option is TO PRINT (see the SET FORMAT command), then the (formatted) data is sent to the printer and there can be no GET clause; otherwise the SET FORMAT TO SCREEN is in effect, and the data is sent to (and can be obtained from) the screen.

The keywords of the @ command: SAY, USING, GET, PICTURE cannot be in macros.

This command is often used for making input screens and reports in Shark. See the command TEXT that contains many elements of the @ command, and is usually used in preference to @ for full-screen input and output, and printed output.

If GET <var> is used, the variable, <var> must exist; it is not created by this command. The present value of <var> is shown on the screen; the new value typed in by the user becomes the contents of <var>; if <var> is a field, the field in the selected file is changed (i.e. a REPLACE is performed).

If no option is used in screen output, for instance @ 10,0, the line is cleared on the screen starting at the indicated column. When using a DOS printer, the print head is moved to the new position.

If there is no <format> clause, the variable is displayed as follows: fields are displayed with the width specified in the data file structure; string memory variables are displayed as stored; numeric variables are displayed as specified by the :PICTURE system variable (see Section 2.6).

The GET clauses are activated by the READ command. There can be no more than 64 GET clauses for a READ command. The GET clauses with their pictures are stored in a Get Table, which remains in effect after a READ until another GET clause is encountered or a CLEAR GETS command is encountered.

NOTES for users of DOS-type printers:

Line numbers go from 0 to 24, column numbers from 0 to 79. For the printer, the line number counter begins at 0 (line 1); it is reset to 0 by the EJECT command (see the commands: EJECT, SET EJECT, SET LENGTH TO). If there are several @ commands for the printer, each @ command must display past the display of the previous @ command (that is, if the first @ command displays at line1, col1, and the next at line2, col2, then either line1<line2, or line1=line2 and col1<col2). If the new print position is less than the current print position, the printer head is not moved by the @ command.

NOTES for users of Windows-type printers:

Printed output mimics the screen display, and is easily adjusted by "trial-and-error".

ACCEPT

Input request for strings.

ACCEPT ['<string>'] TO <str var>

Option: '<string>'  the prompt message  

This command is used in Shark programs to request character information to be placed into a memory variable. The text in <string> will be displayed as a prompt message. Note that <string> has to be delimited by ' or by ", and may not be either a macro or a string expression. ACCEPT cannot be used to input data into a field or element of a matrix.

If the <memvar> does not exist, it will be created.

The optional character string is used as a prompt. A character expression cannot be used, but a macro is permitted, provided the macro expression includes quotation marks.

To input numeric or logical data, use the INPUT command. Example In a program:

ACCEPT 'Your name: ' TO name
Your name: David Simco

The following illustrates use of a variable instead of a string as the prompt:

1>prompt='"This is a prompt: "'
1>ACCEPT &prompt TO hello
This is a prompt:  George
1>LIST MEMORY
Name          Type    Width    Contents
PROMPT          C      20      "This is a prompt: "
HELLO           C       6      George
** Total ** 2  variables... 26  bytes

APPEND

Append record to data file.

 APPEND [FIELDS <field list> / TEXT <textfile> / OFF ]

Option:

FIELDS <field list>   the fields to be edited during APPEND

Option:

OFF  rather than generate an APPEND input screen, uses an exiting screen and its Get Table

The APPEND command without either the OFF or TEXT option allows the user to add records to the selected file. Once the command is given, the screen shows the new record in full-screen editing mode. For instance, if the selected file has 201 records, the screen will show record 202 with all fields filled with blanks; once record 202 is filled in, a blank record 203 is shown.

To exit from APPEND, use <End> (or Ctrl-W) once you have filled in the fields of the last record desired. If all the fields of the last record are blank, it will not be appended. To switch from APPEND to EDIT mode, press <PgUp>.

Note that APPEND is actually a special mode of EDIT; the only difference is that EDIT begins by displaying the current record, while APPEND adds a new blank record to the data file and displays that. All the editing fields are the same as in EDIT. See the EDIT command for the complete list of editing keys.

APPEND updates all index files in use.

Example:

1>USE employee
1>APPEND

Shark goes into screen editing mode and displays record 7 with all fields blank (the box showing editing keys is displayed when SET MENU is ON):

#1 EMPLOYEE.DBF                                    APPEND Record       7
                                                                     Page 1

REC:  prev <PgUp>  next   <PgDn>  delete  ^U         PAGE:  prev ^K  next ^L 
FILE: top  ^<Home> bottom ^<End>       DELETE: char <Del> to end of field ^Y 
APPEND MODE: begin ^<PgDn> exit <PgUp>     EXIT: with save <End>  no save ^Q


NAME...........
FNAME..........
ADDR...........
CITY...........
STATE..........
ZIP............
TEL_NO.........
MARRIED........
SALARY.........
YEAR_EMP.......
DEPT...........
ADD_1..........

Shark offers two options that allow users to format their APPEND and EDIT screens to their specific requirements.

APPEND OFF suppresses the standard APPEND/EDIT screen and uses an existing screen and its associated Get Table to accept the input. It is available only in a program.

Example in a program:


1>USE employee
1>CLS
1>TEXT add_empl
1>APPEND OFF

APPEND TEXT can be used in both conversational mode and programs. The following combines all the steps in the above example:

Example:

1>USE employee
1>APPEND TEXT add_empl

The input screen can be constructed with either @ GET or TEXT command. See @ and TEXT commands.

APPEND BLANK

Append a blank record to data file.

APPEND BLANK          

Option:

                                                                                                
BLANK  [append blank record, no full-screen editing]    

APPEND BLANK adds a blank record to the selected file, and sets the current record number to this record. The new record is not shown. The fields of such a record are usually filled by the user with the REPLACE, @ GET, or EDIT commands (or variants such as READ, =, TEXT, BROWSE).

APPEND BLANK updates all index files in use. When network is on, the file header is updated and the file is flushed to disk.

APPEND FROM

Append data to the selected file from another file.

APPEND FROM <file> [FOR <cond>] [SDF/SDF DELIMITED] [WITH <char>]

<file>         the name of the source file

Options:

FOR <cond>     select by condition (not with sequential source
                  files)

SDF            sequential source file
SDF DELIMITED  sequential source file with delimited fields
SDF DELIMITED WITH <char> sequential source file with fields
                  delimited with a specific character <char>

This command appends records from the source file <file> to the selected file. Fields are copied from the source file to the selected file into fields with the same name. Deleted records are not appended.

If a field in the source file has no matching field in the selected file, then the field is ignored. If a field in the selected file has no matching field in the source file, then the field is set to blank.

For character fields, if the field width gets smaller, then the field is truncated on the right; if the field width gets larger, then the field is padded with blanks on the right.

For number fields, if a number will not fit in the new field, digits are lost on the left side of the number. Be careful when moving numbers with different field widths. If the source field has more decimals than the target field, decimals on the right will be dropped. If the target field has too few positions to the left of the decimal point, the value will be lost and the field filled with a zero followed by asterisks.

The FOR clause is used to append a subset of the file specified. The condition <cond> is made up of memory variables and the fields of the source file; permitted only when the source is a data file.

If the structure of two data files is identical in all respects, the records are appended very quickly; otherwise the APPEND is done one field at a time. If a field name occurs only in the source file, its values will not be copied into the target data file. (To change the name of a field, use the

RENAME FIELD command)

APPEND FROM updates all index files in use.

With any of the SDF options, Shark reads the sequential file, and each line is turned into a new record of the data file appended to the end. Each line must end with a carriage return (character 13) or a carriage return-line feed pair (characters 13 and 10). The characters of the line are placed in the new record one after another from the left. See the related command: COPY TO ... SDF.

APPEND FROM ... SDF assumes that fields are not trimmed or delimited.

With the SDF DELIMITED option, the line of the sequential file is regarded as a number of trimmed fields, separated by commas. Strings can, in addition, be delimited by quotation marks. These fields are placed in the fields of the data file from the left. The remaining fields of the data file (if any) are left blank; the remainder of the line (after all the fields are filled), if any, is ignored.

With the SDF DELIMITED WITH <char> option, the line of the sequential file is regarded as a number of fields, separated by commas with all character and logical values surrounded by <char>. Otherwise, this option is identical to SDF DELIMITED.

The functions to read and write sequential files give much better control over sequential files.

Important programming note: The APPEND FROM command automatically opens the FROM file in its internal work area; if the FROM file is already open in another work area, the compiler will assume it is closed when the APPEND FROM command is passed during execution, even if that command is in an IF, CASE or other structure module that is not executed!

Therefore, if there is any reference to the FROM file later in the program, open the file in the proper work area again immediately after the APPEND FROM command. If it is not actually needed after the APPEND FROM is executed (e.g., the program exits after the APPEND FROM), open it with the COMPILE keyword.

Example: USE#4 invoices COMPILE

Examples:

Example 1. Appending from a file with the same structure:

1>USE employee
1>COPY STRUCTURE TO empl1
1>USE empl1
1>APPEND FROM employee FOR name < 'Q'
      3 APPEND(S)
1>LIST name
      1  Marek
      2  Balzer
      3  Poyner
1>ZAP
1>APPEND FROM employee FOR tel_no < '5'
      1 APPEND(S)

Example 2. Appending from a file with a different structure.

Append from EMPLOYEE.DBF:

The selected file is:

Datafile name :      EMPL2.DBF
Number of records:       0
Database selected is  #1
Field   Name       Type Width   Dec
  1     NAME         C     15
  2     NAME1        C     10
  3     ADDR         C      5
  4     CITY         C     25
  5     STATE        C      2
  6     ZIP          C      5
  7     TEL_NO       C      8
  8     MARRIED      L      1
  9     SALARY       N      2      0
 10     YEAR_EMP     N      6      2
 11     DEPT         C     15
** Record Length **        95

EMPL2 has a field NAME1 that does not occur in EMPLOYEE; the field FNAME in EMPLOYEE does not occur in EMPL2. The ADDR field in EMPLOYEE has width 20, in EMPL2 it has width 5. The CITY field in EMPLOYEE has width 20, in EMPL2 it has width 25. The SALARY field in EMPLOYEE has width 9, in EMPL2 it has width 2. The YEAR_EMP field in EMPLOYEE has width 4, in EMPL2 it has width 6; but only 3 characters are available for the number to the left of the decimal point.

1>USE empl2
1>APPEND FROM employee
      6 APPEND(S)
1>EDIT 1


#1 EMPL2.DBF                                         EDIT Record       1
                                                                     Page 1

REC:  prev <PgUp>  next   <PgDn>  delete  ^U         PAGE:  prev ^K  next ^L
FILE: top  ^<Home> bottom ^<End>       DELETE: char <Del> to end of field ^Y
APPEND MODE: begin ^<PgDn> exit <PgUp>     EXIT: with save <End>  no save ^Q


NAME...........  Marek
NAME1..........
ADDR...........  231 R
CITY...........  Broomsdale
STATE..........  MD
ZIP............  02110
TEL_NO.........  566-7012
MARRIED........  y
SALARY.........  0*
YEAR_EMP.......  0*****
DEPT...........  Maintenance

Note that ADDR was cut down to 5 characters; CITY was padded by 5 blanks; SALARY and YEAR_EMP indicate that there was not enough room for the numbers.

Example 3. Appending with the SDF option:

Use the EMPLOYEE file, and append from a sequential file: DATA.TXT. Give the commands:

1>USE employee
1>APPEND FROM DATA SDF

Let the first line of DATA.TXT be: Smith Robert 412 River Street

then the first three fields will be correctly placed. Note that the APPEND with SDF does not check for data correctness (numbers into numeric fields), for field width, etc. This option can be used if some other program already formatted the sequential file in absolute conformity with the structure of the data file.

Example 4. APPEND with the SDF DELIMITED option is easier to use:

Continuing the previous example,

Smith,Robert,412 River Street [or]
'Smith','Robert','412 River Street'

would do. It is important to have the fields delimited with quotation marks if any field contains a comma. Fields for which no data is supplied should be represented by commas as "place holders". For instance,

,,'412 River Street'

Example 5. APPEND with the SDF DELIMITED WITH <char> option works the same way:

Continuing the previous example, the command:

APPEND FROM <source> SDF DELIMITED WITH |

working on the following line

|Smith|,|Robert|,|412 River Street|

would append the record correctly. The use of a specified character other than single quote reduces or eliminates the concern about having commas, apostrophes and quotation marks in field contents. Fields for which no data is supplied should be represented by the specified character as "place holders". For instance,

||,||,412 River Street|

APPEND TO

Append current record to another file.

APPEND TO <num const>

<num const>     append record to file in select area <num const>

This command appends the current record from the selected file to the file numbered <num const>. The same rules apply as in APPEND FROM.

You can also append to the same file by giving its file number.

Examples:

1. Interactive use. There is a Backorder File; you are looking through it with EDIT or BROWSE to find which orders should be filled. Store "^Q;APPEND TO 4;BROWSE;^X;" into a function key, and whenever an order to ship is found, you press the function key. File 4 contains orders to be shipped.

2. There is a Name-and-Address file, and a label printing program that prints a whole file, the Label file. The Name-and-Address file is searched by the above method, and APPEND TO is used to put the addresses to be printed in the Label file.

3. A program segment. File 2 is a backorder file; each record contains 25 fields including Q1 to Q8, the quantities for the eight sizes. This program segment asks how much of each size should be shipped; the end result is that the items to be shipped are appended to the end of File 2, while the original record is changed to reflect the shipped quantities.

SELECT 2
STORE # TO gback
APPEND TO 5
@ y,35 GET q1
@ y,39 GET q2
@ y,43 GET q3
@ y,47 GET q4
@ y,51 GET q5
@ y,55 GET q6
@ y,59 GET q7
@ y,63 GET q8
READ
REPLACE quant WITH q1+q2+q3+q4+q5+q6+q7+q8
SELECT 5
REPLACE q1 WITH q1-q1#2,q2 WITH q2-q2#2,q3 WITH q3-q3#2
REPLACE q4 WITH q4-q4#2,q5 WITH q5-q5#2,q6 WITH q6-q6#2
REPLACE q7 WITH q7-q7#2,q8 WITH q8-q8#2
REPLACE quant WITH q1+q2+q3+q4+q5+q6+q7+q8
REPLACE type WITH 'O'
APPEND TO 2
SELECT 2
GOTO gback

AVERAGE

Average numeric expressions for selected records.

AVERAGE <num exp list> [TO <memvar list> <scope>] [FOR <cond>]

<num exp list>    the numeric expressions to average

Options:  <memvar list>     store the results in these memory variables
<scope>           select by scope (default scope: ALL)
FOR <cond>        select by condition

The command AVERAGE adds up numeric expressions for selected records of the selected data file and divides the result with the number of records summed. Up to 10 expressions can be averaged with one command. Optionally, the results can be stored in numeric memory variables; the expression list and the numeric memory variable list should have the same number of entries. <memvar list> cannot contain numeric mat

Records flagged as DELETED are not averaged.

Memory variables in <memvar list> need not exist; if any variable in the <memvar list> does not exist, this command creates it.

Example:

The average earning of the employees (in the data file EMPLOYEE), and the average year employment began: 1>USE employee 1>AVERAGE salary, year_emp 6 AVERAGE(S) 32502.16 1980.50

BINLOAD

Load a binary (assembly-language) program into memory.

BINLOAD <programname>

 <programname>  a binary file to be executed under Shark; default extension BIN

Assembly-language programs may be copied from disk into a special area of memory called BINSPACE, which must be set aside with the BINSPACE= command in your SHARK.SET or SHARKNET.SET file.

When no longer needed, the program can be removed from the BINSPACE with the BINUNLOAD command, allowing room for another binary program to take its place. A maximum of eight binary files, with default extension BIN, may be loaded into memory at one time.

Once loaded into the BINSPACE, the program may be executed with the CALL command (see the CALL and BINUNLOAD commands).

Examples:

1>BINLOAD test

BINSPACE=

Reserve space in memory to BINLOAD binary files to be run with the CALL command.

BINSPACE=  (SHARK.SET file only)

<blocks>    the number of 1K blocks of RAM to be reserved
                 for loading BIN files with the BINLOAD command

Assembly-language programs may be copied from disk into a special area of memory called BINSPACE, which must be set aside with the BINSPACE= command in your SHARK.SET or SHARKNET.SET file.

The number of 1K blocks, to a maximum of 32, must be specified.

The BINSPACE is allocated above Shark's 64K data space and high memory, and reduces the amount of DOS memory available to execute commands with the RUN command.

Once loaded into the BINSPACE with BINLOAD, the program may be executed with the CALL command (see the CALL, BINLOAD, and BINUNLOAD commands).

Examples:

1>BINSPACE=16

BINUNLOAD

Remove a binary (assembly-language) program from memory.

BINUNLOAD <programname>

<programname>  a binary file to removed from memory by Shark;
                    default extension BIN

Assembly-language programs, which are loaded into a special area of memory called BINSPACE by the BINLOAD command, may be removed from memory by the BINUNLOAD command when no longer needed.

This allows room for another binary program to take its place. A maximum of eight binary files, with default extension BIN, may be loaded into memory at one time.

Care should be taken not to create "holes in memory" by loading and unloading BIN files indiscriminately. For best performance, users are urged to load frequently called binary files first and not unload them; then transient or occasional binary programs can be loaded, called and immediately unloaded with the BINUNLOAD command.

(See BINLOAD and CALL commands.)

Examples:

1>BINUNLOAD test

BOX

Draw a box on the screen.

BOX <line1>,<col1>,<line2>,<col2> [DOUBLE]

<line1>,<col1>   the position of the upper-left corner of the box
<line2>,<col2>   the position of the lower-right corner of the box

Option:

DOUBLE   use double line graphics, the default is single-line

The command BOX draws a box on the screen using the character graphics of the IBM non-graphics screen. If line1=line2, a horizontal line is drawn. If <col1>=<col2>, a vertical line is drawn.

<line1>, <line2>, <col1>, <col2> can all be numbers or numeric expressions; any fractional part will be disregarded.

This command is useful for making fancy menus, boxing messages, and for partitioning the screen into different viewing areas.

Note that commas are required between the numeric expressions used for the corner specifications, but a comma is NOT permitted before the DOUBLE.

The WINDOW command can also draw a box, but in addition limits relative screen output to the boundary of the window and can optionally set window and box colors. See the WINDOW command.

Examples:

1>ERASE
1>BOX 2,10,12,40
1>ERASE
1>BOX 3,0,8,20 DOUBLE
1>ERASE
1>BOX 10,0,10,70

BREAK

Exit to the bottom of a DO WHILE or REPEAT loop.

 BREAK

The BREAK command is used only in programs, in a DO WHILE or a REPEAT loop to exit at the bottom of the loop. If there are nested loops, the exit is at the bottom of the innermost loop.

Contrast the command BREAK with the command LOOP which executes the condition at the top of the DO WHILE loop (see the LOOP command).

Caution: BREAK can be used only within a DO WHILE or REPEAT loop; used anywhere else will give an error with unpredictable results.

Example:

DO WHILE T
<program segment>
IF custn<>mcust
BREAK
ENDIF
<program segment2>
ENDDO

This program carries out <program segment> and <program segment2> until CUSTN becomes different from MCUST; then it jumps over <program segment2> and leaves the loop.

BROWSE

The BROWSE command displays the records (from the current record onward) horizontally, one record per line; it displays as many fields as will fit on a line. A column represents a field.

All fields are available to edit using the BROWSE command. If they don't all fit on your screen, they're visible by simply scrolling the screen left (^K) or right (^L). The scrolling commands are displayed at the top of your screen when you precede the BROWSE command with SET MENU ON.

If you want to see only a few fields, you can use BROWSE FIELDS which will display only the specified fields.

Options (all versions):

 FIELDS <field list> specify the fields to be displayed
 APPEND add a blank record and start BROWSE in that record
 OFF    rather than generate a BROWSE input screen, uses an
        editing screen and its Get Table
 TEXT   <textfile> erases the screen, displays the text file, and
        then does BROWSE OFF

If the selected file is indexed, the records are displayed in the indexed order.

When the APPEND keyword is used, a blank record is appended to the data file and BROWSE begins in that record. The user may alternate between normal BROWSE and APPEND modes with the Ctrl-<PgDn> and <PgUp> editing keys.

All the full-screen editing keys can be used. Note that they have the same meaning as in EDIT, but sometimes they look different. For instance, the next record command (<PgDn> or Ctrl-C) gives a new screen in EDIT; in BROWSE, it simply moves the cursor down one line.

Editing keys:

<left arrow>  or Ctrl-S       moves the cursor back one character

<right arrow> or Ctrl-D       moves the cursor forward one character

Ctrl-<left arrow>             moves to the beginning of the field

Ctrl-<right arrow>            moves to the end of the field

<Ins> or Ctrl-V               puts you in insert mode: what you type gets inserted
                                   (normally, you are in overtype mode: what you type
                                   overtypes the existing text); pressing <Ins> or
                                   Ctrl-V again, puts you back into overtype mode

<Backspace>                   deletes the character to the left of the cursor

<Del> or Ctrl-G               deletes the character on the cursor

Ctrl-Y                             deletes the rest of the field

<up arrow> or Ctrl-E          moves the cursor to the previous field

<dn arrow> or Ctrl-X          moves the cursor to the next field

Ctrl-<PgDn>                   enters APPEND mode; adds a blank record and places the
                                   cursor in that new record.  Deactivated by SET SAVE
                                   OFF and SET APPEND OFF; in network mode, deactivated
                                   when data file opened in READ mode

Ctrl-Q                             quits and does not update the current record

<End> or Ctrl-W              quits and updates the current record

<PgUp> or Ctrl-R             moves to the previous record; when in APPEND mode, exist
                                   to normal BROWSE mode

<PgDn> or Ctrl-C             moves to the next record

Ctrl-L  (i.e. ^L)             redraws the BROWSE screen with the next screenful of
                                   fields, referred to as the next "page"; if the file
                                   has no more fields, this key is ignored

Ctrl-K (i.e. ^K)              redraws the BROWSE screen with the previous screenful of
                                   fields, referred to as the prior "page"; if the
                                   screen is already at the first field, this key is
                                   ignored

Alt-E                              skips one screenful of record data toward the beginning of
                                   the file and redisplays the BROWSE screen

Alt-X                              skips one screenful of record data toward the end of the file
                                   and displays the BROWSE screen

Alt-W                              when cursor is in a memo field, saves the current screen
                                   and opens current memo in read-write mode in the
                                   WRITE editor; on exit from WRITE, the screen is
                                   restored

Alt-R                              when cursor is in a memo field, saves the current screen
                                   and opens current memo in read-only mode in the WRITE
                                   editor; on exit from WRITE, the screen is restored
                                   BROWSE should be used to edit columns of data in a data file; that is,
                                   to edit a few fields of a number of records.  Use the command EDIT to edit
                                   many fields of a single records at the same time.

The option FIELDS <field list> selects the fields to be displayed on the screen.

SET MENU ON causes a small display at the top of the BROWSE screen, giving the use of major editing keys.

Examples:

1>USE customer
1>BROWSE

Displays the following:

#1 CUSTOMER.DBF                 SharkBase BROWSE
                                                                     Page 1


REC:  Prev/PgUp Next PgDn   SCROLL: Left/^K Right/^L  SCREEN:  Up/@E  Down/@X
FILE: Top/^Home Bottom ^End   MEMO EDIT: @W     DELETE: To EOL/^Y  Record/^U
APPEND MODE: Begin/^PgDn Exit/PgUp   EXIT: With save/End  No save/^Q

        CUSTNU FIRSTNAME       LASTNAME             ADDRESS
      1 BROS50 Stan            Brown                786 Alexander Rd.
      2 BURS50 Sid             Bursten              876 Main St.
      3 GRAG50 George          Gratzer              876 Arlington Avenue
      4 MELB50 Bernie          Melman               9876 Ocean View Parkway

To edit the home and work telephone numbers of the customers, issue the command:

1>USE customer
1>BROWSE FIELDS name,hphone,wphone

The display:

#1 CUSTOMER.DBF                 SharkBase BROWSE
                                                                     Page 1

REC:  Prev/PgUp Next PgDn   SCROLL: Left/^K Right/^L  SCREEN:  Up/@E Down/@X
FILE: Top/^Home Bottom ^End   MEMO EDIT: @W     DELETE: To EOL/^Y Record/^U
APPEND MODE: Begin/^PgDn Exit/PgUp           EXIT: With save/End  No save/^Q

        LASTNAME             HPHONE     WPHONE
      1 Brown                9238423472 3984747238
      2 Bursten              7658956    6575777
      3 Gratzer              7866457    7657655
      4 Melman               8765678    6765777

BROWSE FIELDS

This is a simpler variation of the BROWSE command that is different enough to be listed as a separate command. Although one can BROWSE fields directly as in "BROWSE NAME, ADDRESS, ETC", the result will be different in look & feel from using the BROWSE OFF command. It can be used in both programs or conversational mode:

Example in conversational mode:

 BROWSE [FIELDS <field list>/[OFF]/[TEXT] <textfile> [APPEND]

BROWSE OFF

SharkBase offers another option that allows the user to format a BROWSE screens to one's specific requirements.

BROWSE OFF suppresses the standard BROWSE screen and uses a much more descriptive formatted display. It is available only in a program.

Example in a program:

*test.prg
USE#1 PRODUCT
SELE 1
CLS

TEXT
 Use ↑ or ↓ to scan items - Esc to Quit:

 CUST  KGS  NET COST  CHRGE CUST 
            ($Ca)     ($US)
 @CUST @KGS @COST     @US_INVOICE
ENDTEXT
BROWSE OFF
CLOSE ALL

CALL

Execute a binary (assembly-language) program

 CALL <programname> <argument>

 <programname> a binary file to be executed under Shark;
                  default extension BIN

Option:

<argument>    a character memory variable used to transfer data
                  to and from a BIN program; maximum 254 characters

Assembly-language programs, which have been copied from disk into a special area of memory called BINSPACE, can be executed internally by Shark.

Running a binary file requires three steps:

1. Allocate memory in the SHARK.SET or SHARKNET.SET file using the BINSPACE=n where is the number of 1K blocks to allocate to the BINSPACE in memory. The limit for <n> is 32. Example: BINSPACE=32 allocates 32K.

2. BINLOAD the program. A program need only be loaded once (unless it is removed with the BINUNLOAD command). Additional requests to BINLOAD the program will reload it in the same memory space. Up to eight binary programs may be loaded at once. Example: BINLOAD test. (BIN program may be removed from memory with the BINUNLOAD command.)

3. CALL the binary program, with an optional argument of up to 254 bytes in a memory variable. The binary program may modify or replace the contents of this variable, but may not create or lengthen the contents; when execution is completed, the variable will have a new value.

See BINLOAD and BINUNLOAD commands.

Example:

The binary program, listed below, merely overwrites the first three characters of a passed string with the string "SHARK".

dummy='1234567890'
CALL test dummy
? dummy

The current value of dummy would then be printed: "SHARK67890".

Rules for BIN programs:

1. BIN programs are created in assembly language and assembled into an OBJ file with Microsoft's MASM program or equivalent, linked into a EXE file with LINK or equivalent, and converted into a BIN file with the DOS utility EXE2BIN.

2. The following is an example of an assembly-language module that accepts an input string in a memory-variable passed to the module on the CALL command line, modifies it, and passes it back in the same memory variable.

;TESTBIN.ASM -- A sample program to illustrate the  Shark BINLOAD and CALL facilities
;
;By Bernie Melman
;
;This routine replaces the first five characters in a passed string with the characters SHARK
;
;  Assemble with Microsoft Macro Assembler (MASM) version 5.0
;  LINK to produce an EXE file (ignore the "No stack" warning)
;  EXE2BIN to generate BIN file
;
_prog   segment byte
        assume cs:_prog
dtest   proc    far
        mov [bx+0], byte ptr 'S'
        mov [bx+1], byte ptr 'H'
        mov [bx+2], byte ptr 'A'
        mov [bx+3], byte ptr 'R'
        mov [bx+4], byte ptr 'K'
        mov ax,0            ;try changing bp to see if Shark
                            ;   can recover regs ok
        mov bp,ax           ;do it
        ret
dtest   endp
_prog   ends
        end

3. No argument is required, but if one is used, it must contain a string which the program can evaluate in location BX. Shark places a NUL (zero byte) after the string as a terminator; if the program processes characters until a zero is encountered in a byte, the entire string has been processed. Any part of the string following the NUL is ignored by Shark.

4. The maximum length of a Shark string is 254 bytes; therefore, no more than 254 characters can be communicated to or from a binary program.

5. The BIN program cannot change the memory allocation of the argument variable. Therefore, it cannot successfully enlarge the argument string. It can shorten the result by terminating the result with a NUL (zero byte).

6. Sufficient space to load binary files must be provided with the BINSPACE= command in the SHARK.SET or SHARKNET.SET file; and no more than eight binary files may be loaded at any one time. BIN files can be removed from memory with the BINUNLOAD command.

CANCEL

Leave Shark program.

CANCEL

The command CANCEL aborts the Shark program and enters the interactive mode; the Shark prompt appears. See also QUIT.

Example: A Shark program segment:

CASE ans='8'
   QUIT
CASE ans='9'
   CANCEL

If the user chooses Option 9, the result will display the interactive Shark prompt. Option 8 exits to the operating system.

CASE

The switch in the DO CASE program structure.

CASE <cond>

<cond> if the condition is satisfied, the program segment which follows should be executed

CASE is the keyword in the DO CASE program structure. Shark evaluates the condition; if the condition is true, the following program segment is executed. The program segment is terminated by the next CASE, by OTHERWISE, or by ENDCASE. After the execution of the program segment, the program execution continues with the program line after the ENDCASE command. If the condition is false, Shark looks for the next CASE command. If no condition is true, Shark executes the program segment following the OTHERWISE command (if any).

Note that when more than one <cond> is true in a DO CASE structure, only the program segment for the first is executed.

See the command DO CASE

CHAIN

Leave the current Shark program and start running a new Shark program.

CHAIN <program>

<program> = the name of the Shark program to be run

The command CHAIN is used for executing an Shark program from within another Shark program or in the interactive mode from the Shark prompt. The program name <program> should not have an extension. If there is a compiled program by this name (normal extension CPL; runtime extension RPL), it will be run. If there is none, Shark will run the uncompiled program (extension PRG).

CHAIN does a CLEAR first, except that all global memory variables are preserved and passed to the <program>; to use them, the <program> must have a GLOBAL command declaring the variables. (See the commands CLEAR and GLOBAL.)

The CHAIN command does not return to the calling program; the program in memory is replaced by the program it chains to.

CHAIN is the most efficient way for one program to call another. The DO command calls a subroutine from the disk. DO can often be replaced by PERFORM or by CHAIN. (See the commands DO and PERFORM).

When you chain from one program to another, Shark executes a CLEAR command before the start of the program, closing all the data files, index files, sequential files, and releasing all (but the global) variables. When you DO one program from another, the subroutine you do inherits the existing environment -- memory variables, data files, index files, etc. -- and returns to the DOing program when completed or when a RETURN command is executed.

CHAIN allows the program name to be a macro.

Example:

TEXT
                [1] CUSTOMERS
                [2] INVENTORY 
                [3] ORDERS 

ENDTEXT
DO menu; calls a menu program which returns a menu choice as "ans"
DO CASE
CASE ans='1'
   CHAIN prog1
CASE ans='2'
   CHAIN prog2
CASE ans='3'
   CHAIN prog3
ENDCASE

This program segment chains to three different programs, depending on the value of ANS.

CLEAR

Close all data files and index files, and clear memory variables. Optionally clear current Get Table or keyboard buffer.

 CLEAR [GETS/KEYBOARD]

Options:

 GETS           clear the Get Table from memory
 KEYBOARD       delete all characters from the keyboard buffer 
                   buffer

The CLEAR command with no options closes all open data files and index files, and releases all memory variables, including the matrix variables. (Sequential files, DOS files, system variables, and in particular, function keys, are not effected).

Example:

1>a=2
1>name='David Barberr'
1>avco='clear'
1>LIST MEMORY

Name          Type    Width    Contents
A               N       8      2
NAME            C      13      David Barberr
AVCO            C       5      clear
** Total **  3  Variables used  26  Bytes used
1>CLEAR
1>LIST MEMORY

Name          Type    Width    Contents
** Total **  0  Variables used  0  Bytes used

CLEAR GETS removes the current Get Table from memory. (See READ and ON FIELD commands.)

CLEAR KEYBOARD eliminates any characters held in the keyboard buffer. Normally, characters typed at the keyboard are stored in a special buffer until Shark is ready to process them, but occasionally the programmer will want to be sure nothing is in the buffer before executing certain commands. For example, CLEAR KEYBOARD before executing the MENU( function to ensure that a key pressed earlier in the program, or even in a previous program, does not inadvertently trigger a menu selection.

Caution to dBASE programmers: The CLEAR command in dBASE III and later versions erases the screen, but its function on Shark relates to clearing memory and is quite different. To clear the screen, use the CLS command (or the ERASE command)

CLOSE

Close the selected file.

CLOSE [ALL]

Option:

ALL            close all data files in use

The CLOSE command closes the selected data file, updates all information to the disk, and releases the data record buffer space (see Appendix A.1) used by this file. Any index files attached to the data file are also closed, and any limits, relations and filters associated with the data file are cleared.

With the option ALL, all data files in use are closed.

Examples:

1>CLOSE
1>CLOSE#3
1>CLOSE ALL

CLS (or ERASE)

Erase screen:

CLS <line1>,<line2>

Option:

 <line1>,<line2>   erase from line1 to line2

This command erases the screen, and is a synonym for ERASE.

If, optionally, two numeric expressions, line1 and line2, are given, it erases line1 and line2, and all lines between, if any. These expressions should have values between 0 and 24.

CLS is the same as the following three commands:

ERASE
CLS 0,24
ERASE 0,24

Examples of CLS:

1>CLS
1>CLS 2,4

To erase line 12 only:

1>CLS 12,12

To erase a portion of a line:

@22,42 say "                                     "

COLOR

Set the color attributes of a box on the screen.

COLOR <attrib>,<line1>,<col1>,<line2>,<col2>[,<fillchar>]

 <attrib> numeric expression between 0 and 255, the attribute
 <line1>,<col1> the position of the upper-left corner of the box
 <line2>,<col2> the position of the lower-right corner of the box

Option:

<fillchar> the ASCII number of the character used to fill the
                 colored area;

Every character position enclosed in the area described by the row and column values is changed to the fill character

For color monitors, both the background and the character are color, identified separately. These attribute bytes are set for a rectangular area by this command.

The area is given by four numeric expressions -- line1, col1, line2, col2 -- as in the BOX and WINDOW commands. The values must be separated by commas.

Compute ATTRIB by adding up (up to) four numbers (background+ foreground+blink+brightness) from the following tables:

Color Examples:

COLOR 7 (default)    grey on black (7+0+0=7)
COLOR 15    white on black (15+0=15)
COLOR 23    grey on blue (7+16=23)
COLOR 30    yellow on blue (14+16)
COLOR 31    white on blue (15+16=31)
COLOR 36     red on green (4+32=36)
 
SET COLOR TO 18    Sets DEFAULT to green on blue (2+16=18)
SET COLOR TO 31    Sets DEFAULT to white on blue (15+16=31)
SET COLOR TO 208    Sets DEFAULT to black on pink (0+208=208)
COLOR 112    black on white (0+112=112)

NOTE: The correct syntax within a program is:

COLOR <attrib>,<line1>,<col1>,<line2>,<col2>[,<fillchar>]

When filling an area with a fill character, as is often done in designing sign-on screens for example, the pattern characters 176 to 178 and the solid reverse character 219 are especially useful.

See also SET COLOR TO <num exp> and :COLOR=<num exp>, which set the attribute bytes of the characters displayed. SET COLOR TO 0 turns the command off: the attribute bytes remain unchanged at the displaced locations. If a part of the screen already has attributes set by the COLOR command and SET COLOR TO 0, the newly displayed characters will keep the attributes set by the COLOR command.

Examples:

1. This snippet

1>COLOR 18,2,0,12,79

sets background blue and foreground green in lines 2 to 12, as in the above table.

2.The various settings can be saved as memvars and recalled:

1>back=80
1>foregrnd=1
1>bright=8
1>line=2
1>col=0
1>x=18
1>y=50
1>COLOR back+foregrnd+bright,line,col,line+x,col+y

3. The following Shark program illustrates the use of the COLOR command:

DIM NUM matrix[10]
REPEAT 10 TIMES VARYING i
   matrix[i]=MOD(i,7)*16+7
ENDREPEAT
ERASE
REPEAT 10 TIMES VARYING i
   COLOR matrix[i], 12-i, i*5, 12+i, 10+i*5
   DELAY .5
ENDREPEAT
ERASE
COLOR 23, 0, 0, 24, 79
REPEAT 10 TIMES VARYING i
   BOX 1+i, 7+i*3, 23-i, 73-i*3
   DELAY .15
ENDREPEAT
REPEAT 10 TIMES VARYING i
   COLOR matrix[i], 1+i, 7+i*3, 23-i, 73-i*3
   DELAY .5
ENDREPEAT

4. All output to an area of the screen may be made invisible by making the background and the foreground color the same. For example,

SET COLOR TO 0
COLOR 0,10,0,13,79

turns rows 10 to 13 to black on black. Editing fields for entering passwords may be so protected.

5. A set of overlapping frames can be created with pattern characters used as fill:

COLOR 7,10,10,16,70,176    ;a shadow pattern
COLOR 7,09,09,15,69,219    ;a solid pattern
COLOR 7,10,10,14,69,32     ;fill with blanks to create area for text

For more information on setting colors system-wide for all programs at the same time, see the SET COLOR section below.

COMPILE

Compile a Shark program.

COMPILE <file> 

 <file>  the name of the program file

The COMPILE command may be given in interactive mode, or in a program:

1>COMPILE prog

where PROG is a file with PRG extension, the source program to be compiled. <file> cannot be a macro, and should not have any extension specified.

If your main program calls a series of sub-programs (subroutines), the COMPILE instruction will compile the entire set into one completed executable CPL program. If "main.prg" calls "sub1.prg", "sub2.prg", "sub3.prg", for example, calling "COMPILE MAIN" will verify and assemble and save all the "sub" programs into a final "MAIN.CPL". Then, to run the series of programs, all you need to do is enter "DO MAIN" at any time afterward.

Similarly, if you wish to compile many previously compiled separate programs in one step, create a program (call it, say, PROJECT.PRG) as follows:

COMPILE prog1
COMPILE prog2
COMPILE prog3

This will compile all the "progs" (PROG1.prg, PROG2.prg, PROG3.prg) as separate programs which can be called individually at any time any one of them is needed.

1>DO PROJECT

will compile PROG1.prg, PROG2.prg, PROG3.prg. The "DO" source program (PROJECT.PRG) should not use any memory variables, since a CLEAR is executed before every COMPILE command. You can also specify "SET ECHO ON" to have all program lines displayed as they are compiled.

The COMPILE command has another very useful purpose! Because of its speed, it can be used as a pseudo "MAKE" tool since it will test and verify every part of a batch of PRG files being compiled. Older DBF programs such as dBase and Clipper must be tested by running and debugging each PRG manually which is an extremely slow and tedious process!

CONTINUE

Continue to LOCATE from the current record.

 CONTINUE

CONTINUE will carry on locating from the current record using the condition of the last LOCATE command. (See the LOCATE command.)

Note that the standard strings stored in function key F8 combines a CONTINUE and an EDIT command. Once a LOCATE has been executed (function key F8), each additional matching record can be edited by pressing F8.

Example:

1>LOCATE FOR name<'S'
1>EDIT
1>CONTINUE

COPY

Copy selected records of the selected file into a new file.

 
 COPY <scope> TO <file> [FIELDS <field list>] [FOR <cond>] [SDF/]
       SDF DELIMITED [WITH <char>]

<file> is the name of the file the records are copied to.

Options:

 <scope>                     select records by scope           
                                (default scope: ALL)           
 FIELDS <field list>         copy only selected fields         
 FOR <cond>                  select records by condition       
 SDF                         copy into sequential file         
 SDF DELIMITED               separate fields by commas         
 SDF DELIMITED [WITH <char> separate fields by specified character

The command COPY is used for moving records from the selected file to a new file, <file>; if a file by the name <file> already exists, it will be overwritten.

If the SDF option is not used, the result will be a data file with the default extension DBF and the same structure as the source file, unless the FIELDS keyword is used with a fields list.

When the SDF option is used, the result is a text file, with the default extension TXT. When the DELIMITED keyword is not used, each record (or its selected fields) becomes one line in a sequential file; the fields are all merged.

With the SDF DELIMITED option, the fields are separated by commas, and strings are enclosed in single quotes ('). A different string delimiter can be specified with the WITH clause: example WITH |. The specified delimiter character is not enclosed in quotes.

For a discussion of the SDF option, see the command APPEND FROM.

Examples:

1>USE employee
1>COPY TO empl1
      6 COPY(S)
1>USE empl1
1>DELETE 5
      1 DELETE(S)
1>COPY TO empl3
      5 COPY(S)                  note: deleted records are not copied
1>RECALL ALL
1>COPY TO empl4 FOR salary <25000 .AND. year_emp>1980
      1 COPY(S)
1>COPY TO empl4 FOR salary <25000 SDF DELIMITED WITH |
      1 COPY(S)

The result of the last command is a sequential file EMPL4.TXT with one line as follows:

|Marek|,|Mark|,|231R|,|Broomsdale|,|MD|,|02110|,|566-7012|,|y|,
|11500|,|1984|,|Maintenance|
1>COPY TO empl5 FOR salary <25000 FIELDS name,fname SDF DELIMITED WITH |
      1 COPY(S)

The result of the last command is a sequential file EMPL5.TXT with one line as follows:

|Marek|,|Mark|

COPY FILE

Copy disk files.

COPY FILE  [TO] <dest>

<source> = the name of the file to be copied <dest> = the name of the file after the copy

The COPY FILE command copies a file from the disk to another name and/or location. As in DOS, a file cannot be copied to itself.

If no extension is given, the extension DBF is assumed. Wildcards are not permitted.

Important: Do not use COPY FILE on open files, either as source or destination.

On a network with SET NETWORK ON in SharkBase Network Edition, attempting to overwrite a file while another user is accessing it will cause a LOCK error.

Examples:

 
1>COPY FILE cust a:cust            ;data file to floppy
1>COPY FILE cust cust2             ;data file to new name, also DBF
1>COPY FILE cust TO cust.dbk       ;file to data backup DBK file
1>COPY FILE edit.prg TO a:edit.prg ;program file to floppy

COPY STRUCTURE

Create a new file with the structure of the selected file.

COPY STRUCTURE TO <file> [FIELDS <field list>]

Note: <file> = the name of the new file

Option:

FIELDS <field list> copy only these fields

The command COPY STRUCTURE creates a new data file with the same fields as the selected file, but with no records. The default extension is DBF.

If the FIELDS option is used, the new structure will contain only the fields listed.

Example:

1>USE employee
1>COPY STRUCTURE TO emp1
1>COPY STRUCTURE TO emp2 FIELDS name,fname,salary,married
1>USE empl2
1>LIST STRUCTURE
Data file:           EMPL2.DBF
Number of records:       0
File number:             1
Field   Name       Type Width   Dec
  1     NAME         C     15
  2     FNAME        C     10
  3     SALARY       N      9      2
  4     MARRIED      L      1
** Record Length **        36

COUNT

Count selected records.

COUNT <scope> [TO <memvar>] [FOR <cond>]

Options:

<scope>      select by scope (default scope: ALL)
 TO <memvar>  store result in memory variable
 FOR <cond>   select by condition

This command counts the number of records that meet the selection criteria. Selection is by scope and/or by condition. The result may be stored in a numeric memory variable; if the variable does not exist, this command creates it.

Note: <memvar> cannot be a numeric matrix variable.

The result of the command COUNT is displayed if SET TALK ON, as in the examples below.

Examples:

1>USE employee
1>COUNT
      6 COUNT(S)
1>GO TOP
1>COUNT NEXT 3 FOR name <'O'
      2 COUNT(S)
1>GO TOP
1>COUNT FOR salary < 50000 TO raise
1>? raise
     5.00

CREATE

Create a new data file.

CREATE <file>

Note:lt;file>= the data file to create

The command CREATE is used to make a new data file, <file>; <file> cannot be a macro. (Do not use COMP for the first four letters of a data or index file; Shark is unable to open such a file.)

File creation is a special form of full-screen editing. Each field is represented by four editing fields.

Editing keys:
<Left> or Ctrl-S        moves the cursor back one character
<Right> or Ctrl-D       moves the cursor forward one character
Ctrl-<Left>             moves to the beginning of the editing field
Ctrl-<Right>            moves to the end of the editing field
<Ins> or Ctrl-V         puts you in insert mode: what you type gets
                        inserted  (normally, you are in overtype mode:
                        what you type overtypes the existing text);
                        pressing <Ins> or Ctrl-V again, puts you back
                        into overtype mode
<BACKSPACE>             deletes the character to the left of the cursor
<Del> or Ctrl-G         deletes the character on the cursor
Ctrl-Y                  deletes the rest of the editing field
<Up> or Ctrl-E          moves the cursor to the previous editing field
<Dn> or Ctrl-X          moves the cursor to the next editing field
Ctrl-Q                  quits and does not create the file
<End> or Ctrl-W         quits and creates the file
Ctrl-K                  moves back to the top of the previous page
Ctrl-L                  moves to the top of the next page
Ctrl-N                  inserts a line for a new field
Ctrl-T                  deletes the line describing a field

Shark supports four separate type of data files as follows:

Type 0 - The default type; can have up to 256 fields in VP-Info and up to 500 fields in Shark. Allows up to 4 billion records in Shark. In essence, this is an unlimited number of records. The Type 0 file is not compatible with dBASE or early VP-Info versions, whereas the Type 3 variant (see below) is.

Type 1 - Compatible with VP-Info Type 1 files. Type 1 files can have up to 256 fields in VP-Info, and up to 500 fields in Shark.

Type 2 - Compatible with dBASE II data files, and are limited to 32 fields.

Type 3 - Compatible with dBASE III, dBASE III+ and dBASE IV data files.

Type 3 files can have up to 256 fields in VP-Info and up to 500 fields in Shark (NOTE: dBASE III and dBASE III+ cannot read a data file with more than 128 fields, and dBASE IV cannot read a data file with more than 255 fields). Unlike Type 0 files, Type 3 files are also compatible with all other dBase file types, and also can have up to 4 billion records. Type 3 files are easily the most capable of all existing dBase file types.

Shark includes the earlier Types 1 & 2 file types mostly for compatibility when importing data from older dBase/Clipper files. Data can be read in from older files, and saved in the newer Type 3 file format.

When all the fields are specified using the full-screen input display of the CREATE command, the user is asked to specify which type of file to create; the default is Type 3.

If the data file already exists, you will be given the opportunity to delete it when saving to the new file type. On a network with SET NETWORK ON in Shark Network Edition, attempting to delete a data file while another user is accessing a file with the same name will cause a LOCK error. Wait until the other user exits the file, then continue the save operation.

Example:

1>CREATE custfile

shows the following screen after all the fields have been entered:

Sunday, August 12, 2019
                              Shark                      CUSTFILE.DBF
Name         Type    Width   Dec        Name         Type    Width   Dec
CUSTNUM       C        6      0         BIRTHDAY      C        6      0
FIRSTNAME     C       15      0         SS_NUM        C        9      0
LASTNAME      C       20      0         EMPL_NUM      C        6      0
ADDRESS       C       25      0
CITY          C       15      0
STATE         C        2      0
ZIP           C        9      0
HPHONE        C       10      0
WPHONE        C       10      0
SPOUSEFNAM    C       15      0
SPOUSENAME    C       20      0
DEPENDENTS    N        2      0

UP/DOWN           COLUMN MOVE  ROW            SAVE STRUCTURE    C..Strings
previous. <PgUp>  left... ^K   insert... ^N   update... <End>   N..Numbers
next..... <PgDn>  right.. ^L   delete... ^T   nochange. ^Q      L..Yes/No

There are up to 12 fields described in each column, with four editing windows per field. All the standard full-screen editing keys are available in CREATE, including Ctrl-K and Ctrl-L to move from column to column.

As in BROWSE, <Pg Up> and <Pg Dn> are used to move from line to line, while <Up> and <Dn> are used to move between editing windows on the same line.

Error checking is done by Shark as you enter the specifications for the new fields when you leave a line. Here are some of the messages you may see:

         <The first character of a field name must be a letter.
         Invalid character in the Name field.
         Name fields must be unique.
         Types:  C-character  N-numeric  L-logical  D-date  F-float  M-memo.
         Field Length must be greater than 0.
         Length of character field can not exceed 254.
         Length of numeric field can not exceed 20.
         Decimals cannot exceed 6.
         Decimals too large for length.>

Caution: Be sure you have set FIELDS= in the SHARK.SET or SHARKNET.SET file to a number large enough to accommodate all the fields in all the data files you will ever have open at one time, plus the largest number of fields in any of these files. Default is 320 fields. See FIELDS=.

CURSOR

Move the cursor to a given screen position.

 CURSOR <row>,<col>

CURSOR moves the current cursor position to a given point on the screen. Combined with the ?? command, it gives the user all the absolute positioning control of the @ SAY command without its restrictions.

CURSOR is usually employed when the "MENU(" function is used, to place the selection bar correctly.

DEBUG

Print expression or expression list for debugging purposes.

 DEBUG <exp list>

 <exp list>   the expressions to be displayed

This command displays the expressions exactly as does the ? command. However, if SET DEBUG OFF, the expressions are not displayed. This may save the programmer the trouble of having to place the DEBUG commands in the program when debugging, and having to take them out for the regular running of the program.

See SET DEBUG and Appendix A for more in debugging.

Examples (in a program):

DEBUG number DEBUG 'current amount: ', amount, ' current balance: ', balance,INKEY()

Note that the INKEY( function causes a pause until any key is pressed.

DELAY

Suspend execution for a specified number of seconds.

 DELAY <num exp>

<num exp> the number of seconds execution is to be delayed

This command suspends program execution for a specified number of seconds. In some cases, Shark is slow to proceed while clearing its internal memory, and to proceed immediately will cause an error. In this case, you can insert:

DELAY 3

into the application code, and the application will wait 3 seconds before continuing.

The delay can be any length from .06 seconds upward. For programmers, this command can replace complex loops which often have the deficiency of varying in length depending on what type of computer the program is run on.

Examples:

1>DELAY .5
1>number=3
1>DELAY number

DELETE

Delete selected records from the selected data file.

 DELETE <scope> [FOR <cond>]

Options:

 <scope>        select by scope (default scope: current record)
 FOR <cond>     select by condition

The DELETE command is used to set the DELETED flag for records in the selected data file.

These records can be recovered by the RECALL command or with Ctrl-U in the BROWSE and EDIT commands, provided SET DELETE is OFF.

Deleted records are not "seen" by certain Shark commands irrespective of SET DELETE status, including: COPY, POST, UPDATE, SUM, AVERAGE, COUNT.

To remove all the records with the deleted flag set, use the PACK command. (See the commands: SET DELETE, RECALL, PACK.)

Examples:

1>USE employee
1>COPY TO empl1
      6 COPY(S)
1>USE#3 empl1
1>DELETE RECORD 2
      1 DELETE(S)
1>DELETE#3 RECORD 5
      1 DELETE(S)
1>SKIP
1>DELETE NEXT 3 FOR salary <25000
      1 DELETE(S)
1>PACK#3
      5 TOTAL PACKED
1>PACK
      4 TOTAL PACKED

DELETE FILE

Remove files from disk.

 DELETE FILE <file>

Note: <file> = the name of the file to be deleted

The DELETE FILE command deletes a file from the disk. This command should be used with care because, once deleted, the file cannot be recovered. If no extension is given, the extension DBF is assumed. Wildcards are not permitted.

On a network with SET NETWORK ON in Shark Network Edition, attempting to delete a file while another user is accessing it will cause a LOCK error.

Examples:

1>DIR c*.dbf
CCUST.DBF        522 10-13-88  5:42p   COMMS.DBF       6546  1-06-90  5:11p
COMMS2.DBF      6342  1-07-90  1:00p   CUSTJUNK.DBF    7062  9-17-89  3:57p
CUSTOMER.DBF     734 11-29-89 10:43p   CUST2.DBF        734  3-19-90  7:03p

21940 bytes in 6 files.
5246976 bytes remaining.
1>DELETE FILE cust2
1>DIR c*.dbf
CCUST.DBF        522 10-13-88  5:42p   COMMS.DBF       6546  1-06-90  5:11p
COMMS2.DBF      6342  1-07-90  1:00p   CUSTJUNK.DBF    7062  9-17-89  3:57p
CUSTOMER.DBF     734 11-29-89 10:43p

21206 bytes in 5 files.
5251072 bytes remaining.
734 characters were copied.

DIM (ARRAY or MATRIX)

Use DIM to dimension, or define, an array as a matrix or table. Many variables can be stored under one variable name <memvar> in the form of a matrix of cells. The number of rows [x1] and columns [x2] are specified, and the width <width> of the space in each cell is specified. The <width> of the entries of CHAR arrays defaults to 10 if not specified by the user.

Additional <pages> of tables can be specified by a third input [x3]. SharkBase is limited to 128 variables in a single program, and arrays are useful for holding large amounts of data under a single variable name.

Matrixes are economical since they're not stored in program memory. Examples would be tables of shipping rates:

 DIM CHAR <width> <memvar>[x1,x2,x3],<memvar2>[y1,y2,y3],...
 DIM NUM <memvar>[x1,x2,x3],<memvar2>[y1,y2,y3],...
 DIM LOG <memvar>[x1,x2,x3],<memvar2>[y1,y2,y3],...

 <memvar>, <memvar2>  the names of the memory variables that
                         are defined as an array

Option:

 <width>   the width of the character variables

Arrays of up to 3 dimensions can be defined for each of the three data types (CHARACTER, NUMERIC, LOGICAL). The width of the entries of CHAR arrays is fixed; it is 10 if not specified by the user.

The three dimensions are:

1. Length
2. Width
3. Page number

Note that in the syntax description of DIM, [x1,x2,x3] does not indicate three 'options'. The 'dimensions' are enclosed in square brackets thus, [ ], and must be present in a DIM command. x1, x2, x3 are integer numbers greater than zero, not variables, up to three in number; at least one (length) must be specified.

Examples:

One dimensional arrays (also called vectors):

DIM CHAR a[11]
(a vector array eleven rows long of CHAR elements, each defaulting to 10
characters in size)

DIM CHAR 20 a[12]
(a vector array of twelve rows of CHAR elements, each 20 characters in size)
DIM CHAR a[12],b[12]
DIM NUM a[21]
DIM LOG a[20]

To fetch customer details from a dbf record:

USE CUSTOMER READ

or when using severzl data files at one time:

USE#1 CUSTOMER READ
SELECT 1

Set up a one-dimension array named "CUSTDAT" with 9 rows of 50 characters:

DIM CHAR 50 CUSTDAT[9]

Store data in each row of the array:

CUSTDAT[1]=CUSTCODE
CUSTDAT[2]=NAME
CUSTDAT[3]=POBOX
CUSTDAT[4]=CITY
CUSTDAT[5]=REGION
CUSTDAT[6]=POSTCODE
CUSTDAT[7]=STREETADDR
CUSTDAT[8]=STREETCITY
CUSTDAT[9]=COUNTRY

Display data:

N=1
DO WHILE N<10
? "CUSTDAT["+STR(N,2,0)+"]="+CUSTDAT[N]
N=N+1
ENDDO

TABLES:

Two dimensional matrixes (also called tables):

DIM CHAR 25 first[10,20]

(a table array ten rows long, 20 CHAR variables wide, each defaulting to 10 characters in size)

DIM NUM second[5,20]

(The above creates a table array five rows long, 20 NUM variables wide, each defaulting to 8 digits in size)

Three dimensional arrays:

DIM CHAR 10 a[8,10,12]

(The above is a paged table array of 12 pages of 8 rows of 10 CHAR elements)

DIM NUM b[5,5,50]

A mixed definition:

DIM CHAR 12 a[50],b[2,2,11]

Note that the width of both A and B is 12.

Arrays can be used just like all other memory variables except that only = and STORE can assign values to them. Commands and functions that create memory variables (such as the command COUNT) or store values in existing memory variables (such as the command READ or the function READ() cannot directly use arrays. Arrays cannot be used in a TEXT structure or TEXT file.

Arrays are stored in high memory (see Appendix A: Shark Compiler). The size of an array is at most 64K. Use the STATUS command to find out how much high memory is available. Numeric variables take 8 bytes and logical variables take 2 bytes of memory for each entry.

Notes: The numbering is from 1. Arrays can be redimensioned in a program. No part of a DIM command can be a macro.

Examples:

                                      Memory use (in bytes)
1>DIM CHAR 25 name[40]                      1,000
1>DIM CHAR fill[10,7]                         700
1>DIM NUM b[2,3],total[10,20,5]                48 and 8000
1>DIM LOG abc[5000]                        10,000

Applied Example:

1>DIM CHAR 12 PRODUCTS[2,3]
1>PRODUCT[1,1]='CHICKEN'
1>PRODUCT[1,2]='DUCK'
1>PRODUCT[1,3]='GOOSE'
1>PRODUCT[2,1]='BEEF'
1>PRODUCT[2,2]='GOAT'
1>PRODUCT[2,3]='PORK'

The contents of the array can be listed by querying the name of the array:

1>? PRODUCT

CHICKEN DUCK    GOOSE  <-- ROW '1'
BEEF    GOAT    PORK   <-- ROW '2'

or you can query individual elements:

1>? PRODUCT[2,1]
BEEF

When using STATUS (or STAT) to inspect the contents of memory, your MATRIX information will appear as in this example. "Width" shows the WIDTH of each row in characters, and DIMENSION shows how many rows of data are in this particular matrix:

 
Matrix Name   Type    Width    Dimension
CUSTDATA        C      40      [43]

DIR

Directory listing.

 DIR <file specification>

 Options:

 <pathname>        DOS directory name, with optional drive letter and colon
 <file specification> a file name, with optional DOS windcards; extension is required if present

This command is similar to the DIR command of the DOS operating system: it displays the list of files on the current disk, together with file size and date and time created or last modified. Total size of all matching files is also given along with the bytes remaining on the disk.

If a file name is given in full, the directory will show only that one file.

A partial listing of the directory can be specified by giving a with wild card characters.

The wild card character ? may be replaced by any single character; the wild card character * allows any string.

Examples:

1>DIR
SEN_NAME.NDX    1024 10-24-89  1:07a   SEN_NUM.NDX     1024 10-24-89  1:07a
SEN_REIN.PRG     757  8-31-89 11:30p   SEN_SYST.DBF      53  9-06-89  9:02a
SEN_ZIP.NDX     1024 10-24-89  1:07a   SUBDUE.ARC    342658 11-29-89  8:25p
SUBDUE.PRG      2027 11-29-89  7:21p   SUBDUE2.PRG     1168 11-29-89  2:29a

349735 bytes in 8 files.
5251072 bytes remaining.
1>dir \*.
LIB           DIR   8-04-89  2:42p   MAX           DIR   8-04-89  1:27p
RELTEST       DIR   8-06-89 10:27a   SILVERAD      DIR   8-07-89  2:32p
SUPER         DIR   8-27-89  8:30p   TMP           DIR   8-04-89  1:28p
V14           DIR   8-23-89  9:22p   VAWORK        DIR   8-04-89 12:09p
MANUAL        DIR  10-30-89 10:53a   GEN           DIR  11-08-89 12:00a

0 bytes in 10 files.
5251072 bytes remaining.
1>DIR c*.dbf
1>DIR C:\TEMP\*.DBF 
CCUST.DBF        522 10-13- 99  5:42p   COMMS.DBF       6546  1-06-122  5:11p
COMMS2.DBF      6342  1-07-112  1:00p   CUSTJUNK.DBF    7062  9-17-123  3:57p
CUSTOMER.DBF     734 11-29-112 10:43p
21206 bytes in 5 files.
5251072 bytes remaining.

Note on post-Y2K file dates in a Shark file listing: The first epoch (the 20th century to the end of 1999) is numbered as "O" followed by the year, e.g. "099". The zero is dropped, leaving a file date as above of "10-13-99" (Oct 13,1999). The second epoch (the 21st century) is numbered as "1" followed by the year, displaying a file date as above of "11-29-112" (Nov 29,2012). Dates in programs can be easily formatted into your favorite notation using the DATE() function. Example:

1>DIR C:\TEMP\CUSTOMER.DBF  
CUSTOMER.DBF     734 11-29-112 10:43p
1>? DATE(6)
29-NOV-2012
1>? DATE(4)
Friday, November 29, 2012

DIRF

Directory listing, following redirection commands of the current FILES structure.

DIRF <file specification>

Options:

<file specification>  a file name, with optional DOS wildcards; an extension is required if present
                             

Shark provides for a FILES structure which lets you specify default drive letters and/or directories for the various files used by the programs. Usually file types are grouped into individual directories according to "skeletons" constructed with wildcards. For example:

FILES
*.dbf,\data\
*.cpl,\cpl\
*.ndx,\indexes\
ENDFILES


The DIRF command is similar to the DIR command, except that the file specification is compared to the existing FILES structure and, if a match is made, the redirection in the structure is applied to the file specification, so that the directory displayed is of the redirected directory, not the current directory.

It displays a list of all matching files in that directory, together with file size and date and time created or last modified. Total size of all matching files is also given along with the bytes remaining on the current disk. Example:

1>DIRF C:\TEMP\*.DBF 
CCUST.DBF        522 10-13- 99  5:42p   COMMS.DBF       6546  1-06-122  5:11p
COMMS2.DBF      6342  1-07-112  1:00p   CUSTJUNK.DBF    7062  9-17-123  3:57p
CUSTOMER.DBF     734 11-29-112 10:43p

Note on post-Y2K file dates in a Shark file listing: The first epoch (the 20th century to the end of 1999) is numbered as "O" followed by the year, e.g. "099". The zero is dropped, leaving a file date as above of "10-13-99" (Oct 13,1999). The second epoch (the 21st century) is numbered as "1" followed by the year, displaying a file date as above of "11-29-112" (Nov 29,2012). Dates in programs can be easily formatted into your favorite notation using the DATE() function. Example:

1>DIRF C:\TEMP\CUSTOMER.DBF  
CUSTOMER.DBF     734 11-29-112 10:43p
1>? DATE(6)
29-NOV-2012
1>? DATE(4)
Friday, November 29, 2012

If a file name is given in full, the directory will show only that one file. The wild card character ? may be replaced by any single character; the wild card character * allows any string.

DISPLAY

Display information, memory variables, system variables, file structure.

DISPLAY <scope> [FOR <cond> <exp list>] [OFF]
DISPLAY FILES [LIKE <skeleton>] [ON <drive letter>]
DISPLAY MEMORY
DISPLAY STRUCTURE
DISPLAY SYSTEM

Options (for displaying data file records):

<scope>            select by scope (default: the current record)
FOR <cond>         select by condition
OFF                     do not display the record number

Options (for listing directories):

LIKE <skeleton>         the file specification, with optional wildcards
ON <drive letter>       a drive designation, with optional colon

These commands are exactly the same as the LIST commands except for the following differences: the default scope of the DISPLAY command is the current record rather than the whole file; the listing is stopped at the bottom of the screen or current window (about every 20 lines when displaying data file contents).

See the commands: LIST, LIST FILES, LIST MEMORY, LIST STRUCTURE, and LIST SYSTEM.

DO

In a program, execute a subroutine and, on completion, return to the next command in the calling program; in Conversational Shark, equivalent to CHAIN.

 DO <file>

 <file>   the name of the program called

In Conversational Shark, DO is the same as CHAIN: it begins the execution of the compiled program with the name <file> with extension CPL; otherwise, the uncompiled Shark program <file> will be compiled "on the fly" and executed, and the compiled file immediately deleted from the disk.

Note that an uncompiled program with a GLOBAL statement cannot be compiled on the fly if it needs to import variable values, since the COMPILE step includes a CLEAR command.

In a program, the command DO <file> causes the program <file> to be compiled as a subroutine of the current program. No matter how many subroutines are called, all will be compiled into the same CPL file as the calling program. The subroutines become overlays; they are called into memory when needed.

When the called program executes a RETURN command, the execution resumes in the current program with the line following the DO command.

The called program can itself DO other subroutines. There can be subroutines up to 10 levels.

When a subroutine is compiled, all information about data files and memory variables is coded in the compiled form: the environment is compiled with the subroutine. Contrast this with the CHAIN command that starts with a clean slate.

Any time a subroutine is invoked with a DO, the called program becomes an overlay. If a subroutine is called 5 times, it is compiled 5 times. This, of course, would make for very bulky programs.

The solution of this problem is very simple. If the subroutine TEST is not sensitive to the environment (it does not use any fields or memory variables, or all data files and memory variable names are the same throughout the calling program), DO it as follows:

...
PERFORM STEST
...
PERFORM STEST
...
*
PROCEDURE STEST
   DO TEST
ENDPROCEDURE

This way, TEST becomes a single overlay; it is invoked with PERFORM STEST.

Note: If the same subroutine is called from two places in the same program, but the two places have different environments, the subroutine cannot be called from a single procedure, and has to be compiled twice.

For example, assume that TEST carries out some computation on some fields of the data file HISTORY1 and some memory variables, and then carries out the same computations on some fields of the data file HISTORY2 and some memory variables; HISTORY1 is file 2, while HISTORY2 is file 3.

Create two procedures:

PROCEDURE TEST1
   SELECT 2
   DO TEST
ENDPROCEDURE
*
PROCEDURE TEST2
   SELECT 3
   DO TEST
ENDPROCEDURE

Now if you need to invoke TEST with the first environment (HISTORY1), then PERFORM TEST1; otherwise, PERFORM TEST2.

All procedures called by a subroutine must be contained in the PRG file of the subroutine. A procedure of the calling program cannot have the same name as a procedure of the subroutine. It is good programming practice not to have the same name for procedures and subroutines.

Procedures are internally compiled, while subroutines become overlays. Therefore, procedures are faster in execution. However, there is a limit of 32 procedures in total for one CPL file.

The name of the PRG file used with the DO command cannot be a macro.

Example in Conversational Shark:

DO INVOICE

This will execute INVOICE.CPL if present; otherwise it will compile and execute INVOICE.PRG, and then delete the CPL file.

DO CASE

Switch the program flow to a number of cases.

 DO CASE

The command DO CASE provides for the processing of a number of options without the use of nested IF commands. It is used in conjunction with the CASE, OTHERWISE, and ENDCASE commands.

The DO CASE program structure is as follows:

DO CASE
CASE <cond1>
   <program segment1>
CASE <cond2>
   <program segment2>
...
CASE <condn>
   <program segmentn>
OTHERWISE
   <program segment>
ENDCASE

where <cond1>, <cond2>, <cond3>,..., <condn> are conditions, <program segment1>, <program segment2>,..., <program segmentN> and <program segment> are program segments, that is, any number of Shark program lines.

Execution is as follows:

After the DO CASE is encountered, Shark looks for the first CASE command and evaluates the condition; if the condition is true, the following program segment is executed, terminated by the next CASE, by OTHERWISE, or by ENDCASE. After the execution of the program segment, the program execution continues with the program line after the ENDCASE command.

If the condition is false, Shark looks for the next CASE command. If no condition is true, Shark executes the program segment following the OTHERWISE command (if any).

The OTHERWISE command is optional. Note that if more than one condition holds, only the segment after the first true condition is executed.

DO case commands can be nested up to 10 levels.

Example:

ans2='P'
@ 22,10 SAY 'E-edit  A-add  O-order  L-look  Q-quit ' GET ans2
READ
@ 22,10
DO CASE
CASE UPPER(ans2)='Q'
   picked=f
   ok=f
   LOOP
CASE UPPER(ans2)='E'
   @ y,3 GET style
   @ y,10 GET color
   @ y,14 GET descript
   @ y,35 GET q1
   @ y,39 GET q2
   @ y,43 GET q3
   @ y,47 GET q4
   @ y,51 GET q5
   @ y,55 GET q6
   @ y,59 GET q7
   @ y,63 GET q8
   READ
   IF q1+q2+q3+q4+q5+q6+q7+q8=0
      DELETE
   ENDIF
   mpick=t
CASE UPPER(ans2)='O'
   REPLACE type WITH 'O'
...
OTHERWISE
   IF type='P'
      REPLACE type WITH 'O'
   ENDIF
   picked=f
ENDCASE

When editing with the internal Shark programming editor, Alt-F reformats the file with all structures properly indented, making it easy to see unbalanced structures. This is a useful tool for programmers since an unbalanced "if-endif" element can totally disrupt a surrounding "do case" construct.

DO WHILE

The standard program loop command.

  
 DO WHILE <cond>

 <cond>      the condition controlling the loop                
 

The command DO WHILE starts the program loop. The structure of the loop is as follows:

DO WHILE <cond>
   <program segment>
ENDDO

Execution is as follows:

After the DO WHILE is encountered, <cond> is evaluated. If <cond> is true, the Shark program segment (terminated by the ENDDO) is executed; then <cond> is evaluated again. If <cond> is false, execution continues with the command following ENDDO.

There can be a DO WHILE command within a DO WHILE command; this is called nesting. Many levels of nesting are permitted; however, too many levels of nesting will give a compile-time error message:

STACK OVERFLOW

There are two commands that facilitate moving to the top and the bottom of the loop: LOOP moves the execution to the top of the loop, and BREAK exits the loop.

There is one more looping command in Shark: REPEAT.

When editing with the internal Shark programming editor, Alt-F reformats the file with all structures properly indented, making it easy to see unbalanced structures.

EDIT

Edit records in a data file.

 EDIT <recnum> [FIELDS <field list>] [/ OFF] [/ TEXT <textfile>]

Options

 <recnum>				begin EDIT on record number <recnum>
 FIELDS <field list>			the fields to be edited
 OFF                			rather than generate an EDIT input screen,
					uses an existing screen and its Get Table
 TEXT <textfile>			erases the screen, displays the text file,
					and then does EDIT using the text file
					layout and embedded format pictures

The EDIT command without either the OFF or TEXT option allows the user to view and modify records in the selected file. Once the command is given, the screen shows the current record (or the record optionally specified with <recnum>) in full-screen editing mode.

If the FIELDS keyword and a fields list is specified, only those fields will be available during EDIT:

1>USE employee
1>EDIT FIELDS name, fname, tel_no

otherwise, Shark builds an input screen using all fields in the current data file.

To exit from EDIT, use <End> (or Ctrl-W) once you have filled in the fields of the last record desired. To switch from EDIT to APPEND mode, press Ctrl-<PgDn>, while <PgUp> switches back from APPEND into EDIT mode.

Note that APPEND is actually a special mode of EDIT; the only difference is that EDIT begins by displaying the current record, while APPEND adds a new blank record to the data file and displays that record. All the editing fields are the same for both EDIT and APPEND.

EDIT updates all index files in use.

The command SET MENU ON displays the most important editing keys at the top of the screen, except if OFF or TEXT keyword is used, or if the current window is less than 80 characters wide or 10 rows deep.

Editing keys:

<Left> or Ctrl-S        moves the cursor back one character
<Right> or Ctrl-D       moves the cursor forward one character
Ctrl-<Left>             moves to the beginning of the field
Ctrl-<Right>            moves to the end of the field
<Ins> or Ctrl-V         puts you in insert mode: what you type gets inserted
			(normally, you are in overtype mode: what you type
			overtypes the existing text); pressing <Ins> or
			Ctrl-V again, puts you back into overtype mode
                  	deletes the character to the left of the cursor
<Del> or Ctrl-G         deletes the character on the cursor
Ctrl-Y                  deletes the rest of the field
<up arrow> or Ctrl-E    moves the cursor to the previous field
<dn arrow> or Ctrl-X    moves the cursor to the next field
Ctrl-Q                  quits and does not update the current record
<End> or Ctrl-W         quits and updates the current record
<PgUp> or Ctrl-R        edits the previous record; if in APPEND mode, exits to EDIT mode
<PgDn> or Ctrl-C        edits the next record
Ctrl-<Pg Dn>            Enters APPEND mode; adds a blank record and places the
                        cursor in that new record
Ctrl-K                  moves back to the top of the previous page (not with
                        OFF or TEXT keywords)
Ctrl-L                  moves to the top of the next page (not with OFF or TEXT keywords)

See also:

EDIT TEXT
EDIT OFF

EXAMPLES

1>USE employee
1>GO 2
1>EDIT
1>EDIT 2

You then see:

#1 EMPLOYEE.DBF                                      EDIT Record       2
                                                                     Page 1

REC:  prev <PgUp>  next   <PgDn>  delete  ^U        PAGE:  prev ^K  next ^L
FILE: top  ^<Home> bottom ^<End>      DELETE: char <Del> to end of field ^Y
APPEND MODE: begin ^<PgDn> exit <PgUp>    EXIT: with save <End>  no save ^Q


NAME...........  Steiner
FNAME..........  Tom
ADDR...........  114 North Pitt St.
CITY...........  Lakewood
STATE..........  MD
ZIP............  02111
TEL_NO.........  596-0017
MARRIED........  y
SALARY.........   35780.00
YEAR_EMP.......  1984
DEPT...........  Engineering

To edit only a few fields:

1>USE employee
1>SET MENU ON
1>EDIT FIELDS name, fname, tel_no
     This displays:

#1 EMPLOYEE.DBF                                      EDIT Record       7
                                                                     Page 1

REC:  prev <PgUp>  next   <PgDn>  delete  ^U        PAGE:  prev ^K  next ^L
FILE: top  ^<Home> bottom ^<End>      DELETE: char <Del> to end of field ^Y
APPEND MODE: begin ^<PgDn> exit <PgUp>    EXIT: with save <End>  no save ^Q

NAME...........  Marek
FNAME..........  Joe
TEL_NO.........  566-7012

EDIT TEXT

The following examples show EDIT using the TEXT and OFF keywords combined with an external text file (output from both is identical; OFF allows the added flexibility of using an internal TEXT structure and/or an ON FIELD structure):

1>USE employee
1>EDIT TEXT employee
1>USE employee
1>TEXT Employee
1>EDIT OFF

These both display:

                                                     EDIT Record      23


      NAME...........  ARTHUR                NEUMANN

      ADD_1..........  4274 MATHERS BLVD. E.           UPSON DOWNS
      ZIP............  59768

      PHONE..........  243-5548 (614)
      WPHONE.........  643-5657 (614)

      EXPERIENCE.....
          ACCT STUDENT, WORKED FOR CPA SCARECROW & MOSCOWITZ, BOSTON
      COMMENTS
          KNOWS INCOME-TAX LAW, WITH SPECIALTIES IN DEPRECIATION AND
          TAX SHELTERS; SUGGEST ASSIGN TO CENTRAL OFFICE

See TEXT for a full discussion of the TEXT command. The TEXT used for the above input screen:

.. zip,!9! 9!9
.. phone,999-9999 (999)
.. wphone,999-9999 (999)
.. training,99/99
      NAME...........  %FNAME  %NAME
      ADD_1..........  %ADD_1  %AREA
      ZIP............  @ZIP
      PHONE..........  @PHONE
      WPHONE.........  @WPHONE
      EXPERIENCE.....
          @EXPERIENCE
      COMMENTS
          @COMMENT1
          @COMMENT2

EDIT OFF

The following demonstration program illustrates use of EDIT OFF.

*  EDIToff.prg   demonstration program for the EDIT OFF command
*  Note the technique used to "wrap" the file...when skipping
*  past EOF, program "wraps to top of file, and vice versa,
*  using SOUND command to beep (silent if NOEFFECTS in SHARK.SET).


USE customer
ON escape              ;what to do when <Esc> is pressed
   WINDOW              ;cancel small window
   CURSOR 23,0         ;put cursor in bottom left corner of screen
   CANCEL              ;exit program
ENDON
WINDOW
ERASE
* 
TEXT

     REC:  prev <PgUp>  next <PgDn>                      DELETE RECORD <Ctrl>U
     FILE: top <Ctrl><Home> bottom <Ctrl><End>  DELETE: char <Del> to end of field <Ctrl>Y
     APPEND MODE: begin <Ctrl><PgDn> exit <PgUp> EXIT: with save <End> no save <Ctrl>Q


ENDTEXT
WINDOW 8,10,17,69 double
TEXT
.. custnum,!!!-!-99
.. hphone,999-9999 (999)
.. wphone,999-9999 (999)
.. state,!!
Enter customer data:
    Number...... @custnum
    Name........ %firstname %lastname
    Address..... @address
    City, State. %city %state
    Zip Code.... @zip
    Phones (H/W) %hphone   %wphone
ENDTEXT
DO WHILE t
   EDIT off            ;edit using Get Table created with TEXT above
   DO CASE
   CASE :key=335       ;exit loop when <End> key pressed
      BREAK
   CASE eof            ;skipped past end of file; start again at top
      ring
      GOTO top
   CASE #<1            ;backed up past beginning of file; start again at bottom
      ring
      GOTO bottom
      IF eof           ;if no undeleted records left in file, get out
         BREAK
      ENDIF
   ENDCASE
ENDDO
WINDOW                 ;cancel small window
CURSOR 23,0            ;put cursor in bottom left corner of screen

EJECT

This command is used on a MS-DOS system when the printer is controlled directly by the program. A Windows-based DOS emulator like vDOS or DOSbox will direct print output first to a file (not to a printer), and Windows then processes the file, handing it to the printer or saving the output as a text file.

Thus, in MS-DOS, to start a new page on the printer.

 EJECT

This also resets the line and column counters to 0 for the @ commands.

EJECT will attempt to advance the printer whether printing is on or off. If your printer is on but off-line, your program may appear to hang; either put the printer on-line, or turn off the printer to release Shark to continue processing.

When spooling directly to a printer within an MS-DOS system (see SPOOL), the form-feed is placed into the spool file, and has no effect on the printer until the file is spooled or copied to the DOS printer.

(See the commands @, SET FORMAT TO PRINT, SET PRINT ON, SET EJECT ON/OFF, SET LENGTH TO, and the functions ROW( and COL(.

Examples:

1>EJECT

In a program, EJECT and SPOOL may be used together to reset the line counter to zero before printing begins:

SPOOL junk
EJECT
SPOOL

ELSE

The optional part of an IF program structure.

 ELSE

This command introduces the optional part of the program structure IF/ENDIF. See the command IF.

Example:

IF count>5
   ok=t
ELSE
   IF count<2
      ok=f
   ENDIF
   ? 'ok'
ENDIF

END commands

Terminate a command structure.

 
 ENDCASE
 ENDDO
 ENDIF
 ENDFILES
 ENDON
 ENDPROCEDURE
 ENDREPEAT
 ENDTEXT
 

All Shark structures are terminated with a matching END command as shown above. When editing with the internal Shark programming editor (see WRITE command), Alt-F reformats the file with all structures properly indented, making it easy to see unbalanced structures.

See DO CASE, DO WHILE, IF, FILES, ON ERROR, ON ESCAPE, ON FIELD, PROCEDURE, REPEAT, and TEXT.

ERASE (or CLS)

Erase screen.

 ERASE [line1,line2]

Option:

 line1, line2   erase from line1 to line2

This command erases the screen, and is a synonym for CLS.

If, optionally, two numeric expressions, line1 and line2, are given, it erases line1 and line2, and all lines between, if any. These expressions should have values between 0 and 24.

ERASE is the same as the following three commands:

CLS
ERASE 0,24
CLS 0,24

Examples:

1>ERASE
1>ERASE 2,4
1>ERASE 2,2

FIELD

Initiates a program segment module in an ON FIELD structure

 
 FIELD <fieldname>/<fieldnum>

 fieldname       name of a field in a Get Table                
 fieldnum        number of a field in a Get Table              

Each field in a Get Table may have a program segment in a program's ON FIELD structure which will be executed when the cursor leaves that field, or optionally when READ or the current record is exited.

All fields in a Get Table are numbered from 1 to 64 in the order in which they are placed on the screen. When they are painted by @ GET commands, the order is the same as the order of the @ GET commands in the program; if painted by TEXT, the order is left-to-right on each line, and then top-to-bottom.

When editing with the internal Shark programming editor (see WRITE command), Alt-F reformats the file with all structures properly indented, making it easy to see unbalanced structures.

(See command ON FIELD.)

Examples:

FIELD 3
FIELD cust
FIELD name#3

FIELDS=

Set the maximum number of fields available at any one time.

 
 FIELDS= <num>                                
 

This setting is used in the SHARK.SET file only

                                              
 <num> = maximum number of fields allowed in all data files    
                   open at any one time (including Shark's        
                   internal work file); range 128 to 1000         
   

This command sets the maximum number of fields that can be open at any one time in all open files, taking the place of SET FIELDS TO in earlier versions of the language (now ignored if encountered by the Shark compiler).

Reserving memory space for a single field requires 16 bytes. Therefore, increasing the number of fields requested reduces the memory space available for your program.

The limits for FIELDS= are 128 and 1000, with a default of 320.

Caution: be sure you have set FIELDS to a number large enough to accommodate all the fields in all the data files you will ever have open at one time, plus the largest number of fields in any of these files.

Example:

FIELDS=500

FILES

Lets you specify drive letters, directories, and/or default file modes for various files used by Shark.

    
 FILES
 FILES  [,] [,<mode>]         
 

specification = any file name or "skeleton" (using the * and ? wildcards

Options:

                                               
 file direction   any legal DOS path, consisting of drive letter and colon and/or directory path            
 

Option: (Network Edition only):

                                           
 mode             any one of the optional file-opening modes used   
                  in network operation -- LOCK or L, WRITE or W,  
                  READ or R, or SHARE or S. If no mode is set,    
                  or if Network Edition is not in use, the   
                  default mode is LOCK      
 

There is always a FILES Table in memory, set up by the active FILES ... ENDFILES structure. (This table is empty if there is no active FILES ... ENDFILES structure.) The FILES command allows on-the-fly additions and changes to the FILES Table from either Conversational Shark or programs.

Examples of Form 1 (Only in programs):

FILES

Initiates a FILES ... ENDFILES structure. (See FILES ... ENDFILES.)

(Only in Conversational Shark)

1>FILES

Empties the current FILES Table in memory. (Caution: Do not confuse this interactive command with the FILES command as used in programs, which always initiates a FILES ... ENDFILES structure.)

Examples of Form 2 (In either programs or Conversational Shark): FILES *.dbf,c:\data

Given this command, either in a program or in Conversational Shark, Shark searches the FILES Table in memory for a matching file specification. If the file specification *.DBF is found, the new path will replace the existing path; otherwise, this specification and redirection is added to the top of the FILES Table.

FILES *.frm    

If no <file> direction is specified, file redirection is turned off for files matching this entry.

Macros are allowed with the FILES command itself, either in programs or in Conversational Shark. Macros are not permitted in the FILES ... ENDFILES structure.

THE FOLLOWING REFERS TO NETWORK EDITIONS ONLY:

There is a special form of the FILES command which has significance only in network editions with SET NETWORK ON.

This form adds a <mode> which sets the default file mode for all matching files. For example,

FILES *.ndx,ndx,READ

sets a file mode of READ for all files with an NDX extension, all of which are found in the NDX subdirectory of the current directory.

If only <specification> and <mode> are given, the file mode is given to all files matching that specification wherever they are on the disk. (Note: two commas are required:

FILES *.dbf,,WRITE.)

FILES ... ENDFILES

Lets you specify drive letters, directories, and/or default file modes for various files used by Shark.

 
 FILES                                        
  [, ][,<mode>]               
 ENDFILES
                                              
 specification    any file name or "skeleton" (using the * and ?    
                    wildcards); must not be indented           

Options:

file direction any legal DOS path, consisting of drive letter and colon and/or directory path

Option: (Network Edition only):

mode           any one of the optional file-opening modes used
               in network operation -- LOCK or L, WRITE or W,
               READ or R, or SHARE or S. If no mode is set,
               or if Network Edition is not in use, the
               default mode is LOCK

(Programs and CNF file only) There is always a FILES Table in memory, set up by the active FILES ... ENDFILES structure. (This table is empty if there is no active FILES ... ENDFILES structure.)

A FILES ... ENDFILES structure may be created in a program at any time, and may have any number of specification lines between the FILES and ENDFILES lines. All existing entries are immediately cleared and a new FILES Table constructed.

Examples:

*.dbf,c:\data

Causes Shark to add C:\DATA\ to the front of all file names Given this command, either in an Shark program or in Conversational Shark, Shark searches the FILES Table in memory for a matching file specification. If the file specification *.DBF is found, the new path will replace the existing path; otherwise, this specification and redirection is added to the top of the FILES Table. FILES *.frm

If no <file direction> is specified, file redirection is turned off for files matching this entry.

A FILES ... ENDFILES structure is cleared by an empty structure as follows:

FILES
ENDFILES

No macros are permitted in the FILES ... ENDFILES structure, although macros are allowed with the FILES command itself, either in programs or in Conversational Shark.

Caution: There is no way to add a comment inside a FILES ... ENDFILES structure, and no line should be indented. The contents of FILES ... ENDFILES structures are not affected by the reformatting facility Alt-F of the WRITE command.

THE FOLLOWING REFERS TO NETWORK EDITIONS ONLY:

There is a special form of FILES...ENDFILES entry which has significance only in network editions with SET NETWORK ON.

This form adds a <mode> which sets the default file mode for all matching files.

For example,

*.ndx,ndx,READ

sets a file mode of READ for all files with an NDX extension, all of which are found in the NDX subdirectory of the current directory.

If only <specification> and <mode> are given, the file mode is given to all files matching that specification wherever they are on the disk. (Note: two commas are required: *.dbf,,WRITE.)

FILES=

Set the maximum number of files which can be open at one time (requires DOS 3.3 and above)

 FILES= <num const>

SHARK.SET file only

 <num const>   maximum number of files that can be open at any one time; range 21 to 65

Shark has a default maximum of 20 files, unless the operating system allows more than 20 open files (DOS 3.3 and above) and that a FILES= statement is present in the CONFIG.SYS file specifying at least <n> files.

As a practical matter, should be in the range 25 to 60; the default and minimum is 20. Loading more files reduces the maximum size of programs and reduces speed of such memory-intensive commands as INDEX.

This command may be placed only in the SHARK.SET file, which is executed by Shark only when first loaded.

Example:

1>FILES=50

FILES LIST

Display the current contents of the FILES ... ENDFILES structure

 FILES LIST

The current FILES ... ENDFILES structure may be displayed with this command. See FILES and FILES ... ENDFILES.

Example:

1>FILES LIST
File Spec       Drive and/or Path
*.CPL           CPL2\
*.NDX           NDX2\
*.DBF           DBF\
*.DBK           DBK\

FIND

Find a record by its index in the selected data file.

 FIND <string>

FIND is one of a family of commands that finds a record in an indexed data file by matching a given string with key values in the index file:

FIND positions the file on the first record in the index matching the FIND string (no-find positions the file at the top of file)

LAST positions the file on the last record in the index matching the FIND string (no-find positions the file at the top of file)

NEAREST positions the file on the first record in the index equal to or greater than the FIND string

SEEK is identical to FIND, except that it searches for the match to the value of a character expression instead of a string constant (no-find positions the file at the top of file)

All forms allow a search to be made on a character expression when the expression is preceded by the macro symbol "&". When the variable var='TAYLOR', all of the following command lines are equivalent:

FIND TAYLOR

FIND &var

SEEK var

In Conversational Shark, just type FIND and the key.

Examples:

1>FIND TAYLOR
1>FIND TOM

If <string> evaluates the same for two records, the second record will never be found with FIND.

If SET DELETE ON, deleted records will not be found. (See the command SET.)

Numbers must always be treated as strings, even if the key expression is a numeric field. If NUM is a numeric field of width 2, FIND 1 will not find 1, but FIND &STR(1,2) or FIND &' 1' will work.

For the users' convenience, Conversational Shark converts all command lines to upper case before execution. So, to find the inventory numbers that start with AB, type either of the following two commands:

1>FIND AB
1>FIND ab

It follows that

1>FIND Taylor

is understood by Shark as FIND TAYLOR. If you have to find Taylor, use one of the following forms:

1>FIND &'Taylor'
1>SEEK 'Taylor'
or if name='Taylor' use one of the following forms:
1>FIND &name
1>SEEK name

If FIND is successful, the value of the current record pointer (as shown by the # and RECNO( functions) is set to the current record number, and the system variable :NEAR is set to the same number.

If the record is not found, the current record pointer will be set to 0 and the value of :NEAR will be set to the number of the first record in the index with a key greater than the FIND string; if the index contains no key greater than the FIND string, :NEAR is set to the bottom of file, and EOF is set to T (true).

The command for "if not found" is:

IF #=0  or
IF RECNO()=0

In Conversational Shark or in programs with SET TALK ON, Shark sends the message "NO FIND" when a search is unsuccessful.

Notes:

FIND only works on the active index of the selected data file. If that index was created with a selection condition, some records may be excluded from the index. (See INDEX.)

* With SET EXACT ON (see the SET command) only exact matches are found. The FIND string must be the same length as the index key, and match exactly; if SET EXACT OFF, the find string may be shorter.

* An index may be made insensitive to capitalization by using the uppercase functions !( or UPPER( in index creation. This makes use of the FIND command much easier in Conversational Shark. (See INDEX command.)

* The macro symbol (&) has a wider definition when used with FIND, LAST, NEAREST and SEEK than with other Shark command. With this group of commands only, it alerts Shark that the string expression following is to be evaluated and used as the FIND string. (Macros in all other commands are limited to fields and variables; dimensioned variables, functions and concatenation are not allowed.)

FLUSH

Update the selected data file on the disk.

 FLUSH

The current record of the selected data file is updated on the disk. This may prevent accidental loss of data due to power failure.

This command updates only the selected data file; it does not update other data files in use, nor does it safeguard index files, text files, or DOS files. After a power failure it may be necessary to reindex the selected file.

Example:

1>FLUSH

GLOBAL

Declare global variables.

 GLOBAL <memvar list>

<memvar list> the list of memory variables to be declared global

When a program is chained to another program, all the variables that were defined as global by the GLOBAL command will be passed to the new program.

The GLOBAL command should be the first command of any program. It should definitely precede any command that involves a memory variable.

There can be only one GLOBAL command in a program. No part of the GLOBAL command can be a macro. A matrix variable cannot occur in a GLOBAL command.

This is how the command works. In PROG1, you find at the beginning

GLOBAL a,b,c,d

This places in the memory variable table (in the internal Shark data space, see Appendix A) the variable names: A, B, C, D, in that order. The variables at this stage have no type or data. When in PROG1, A is encountered, that will attach type and a pointer to a value to A.

Now PROG1 is chained to PROG2. For PROG2 to receive the values associated in PROG1 with A, B, C, and D, start with the command:

GLOBAL a,b,c,d

Note, however, that the variable names do not have to match (although type must).

GLOBAL x,y,c,d

will create the variable X with the contents of A, Y with the contents of B, C and D retain their names and types.

If you start PROG2 with

GLOBAL a,b,c

then A, B, and C are inherited. If you specify in PROG2 more global variables, for instance:

GLOBAL a,b,c,d,e

then A, B, C, and D inherit their values and types from PROG1; E becomes the fifth entry in the memory variable table, with no type or value.

Example:

PROG1 is chained to PROG2 with the command:

CHAIN PROG2

PROG1 wants to pass to PROG2 the values of the following variables: TRANSACT, PROCESS, CUSTRANGE, TYPE. To accomplish this, start both PROG1 and PROG2 with the command:

GLOBAL transact,process,custrange,type

Note that when the execution of PROG2 starts, only these four memory variables exist.

Now suppose that PROG2 is chained to PROG3, and wants to pass to PROG3 the variables TRANSACT, PROCESS, CUSTRANGE, TYPE, and TRDATE.

Then the first command of PROG1 should be:

GLOBAL transact,process,custrange,type 

the first command of PROG2 should be:

GLOBAL transact,process,custrange,type,trdate 

the first command of PROG3 should be:

GLOBAL transact,process,custrange,type,trdate

Now if PROG3 chains to PROG1, the variables TRANSACT, PROCESS, CUSTRANGE, TYPE are still passed on, but not TRDATE.

GO

Set current record pointer to new value.

  
 <num const>                                  
 GO <num exp>                                 
 GOTO <num exp>                               
 GO RECORD <num exp>                          
 GOTO RECORD <num exp>                        
 GO TOP                                       
 GOTO TOP                                     
 GO BOTTOM                                    
 GOTO BOTTOM                                  
 

<num exp>/<num const> the number to be assigned to # The commands GO and GOTO are identical. They assign a new value to #, the current record pointer (see Section 3.4). The data file is repositioned to the record with the new record number.

The forms:

GO <num exp>
GOTO <num exp>
GO RECORD <num exp>
GOTO RECORD <num exp>

evaluate the numeric expression <num exp>, throw away any fractional part, and assign the value to the current record pointer, #. So, any one of the following commands:

1>2
1>GO 2
1>GOTO 2
1>GO (2+2)/2

accomplishes the same: the record pointer (#) is set to 2. Note that

1>(2+2)/2

is not allowed. If the selected file is indexed, the index is adjusted accordingly. GO TOP, GOTO TOP and GO BOTTOM, GOTO BOTTOM are used to position the current record pointer to the top and bottom of the current data file. If there is no index in use, the TOP is Record 1, and BOTTOM is the last record. If an index is in use, then the TOP and BOTTOM are the first and last records according to the index.

Examples:

1>USE employee
1>GOTO 2
1>DISPLAY name
      2  Steiner
1>5
1>DISPLAY name
      5  Poyner
1>GOTO 1
1>DISPLAY name
      1  Marek
1>GO BOTTOM
1>DISPLAY name
      6  Wilson
1>GO TOP
1>DISPLAY name
      1  Marek

GOTO

Set current record pointer to new value.

 
 <num const>                                  
 GO <num exp>                                 
 GOTO <num exp>                               
 GO RECORD <num exp>                          
 GOTO RECORD <num exp>                        
 GO TOP                                       
 GOTO TOP                                     
 GO BOTTOM                                    
 GOTO BOTTOM                                  
  

<num exp>/<num const> the number to be assigned to #

The commands GO and GOTO are identical. They assign a new value to #, the current record pointer (see Section 3.4). The data file is repositioned to the record with the new record number.

The forms:

GO <num exp>
GOTO <num exp>
GO RECORD <num exp>
GOTO RECORD <num exp>

evaluate the numeric expression <num exp>, throw away any fractional part, and assign the value to the current record pointer, #. So, any one of the following commands:

1>2
1>GO 2
1>GOTO 2
1>GO (2+2)/2

accomplishes the same: the record pointer (#) is set to 2. Note that

1>(2+2)/2

is not allowed.

If the selected file is indexed, the index is adjusted accordingly.

GO TOP, GOTO TOP and GO BOTTOM, GOTO BOTTOM are used to position the current record pointer to the top and bottom of the current data file. If there is no index in use, the TOP is Record 1, and BOTTOM is the last record. If an index is in use, then the TOP and BOTTOM are the first and last records according to the index.

Examples:

1>USE employee
1>GOTO 2
1>DISPLAY name
      2  Steiner
1>5
1>DISPLAY name
      5  Poyner
1>GOTO 1
1>DISPLAY name
      1  Marek
1>GO BOTTOM
1>DISPLAY name
      6  Wilson
1>GO TOP
1>DISPLAY name
      1  Marek

HELP

Request for information on Shark commands and related topics.

  
 HELP <string>                              

Option:

                                             
 <string>   the topic for which help is wanted
 

The HELP command provides information on the syntax (format rules) and use of the commands of Shark, and some related topics; it is available only in Conversational Shark.

The command

  
1>HELP

displays all the topics for which HELP is available. Type HELP and the topic description.

The text is contained in the file SHARK.HLP or SHARKNET.HLP, which must be in the same directory as your version's MSG file, either in the current directory or on the DOS path. If the file is not found, Shark will so advise the user.

Examples:

   
1>HELP

displays the HELP menu screen.

   
1>HELP REPLACE

displays help on the REPLACE command

IF

Conditional execution of Shark program segment.

  
 IF <cond>

 <cond>     the condition to be evaluated; if true, segment is executed

The IF command allows conditional execution of a program segment. The general form of this command is:

IF <cond>

<program segment>

ELSE

<ELSE program segment>

ENDIF

This works as follows: When the IF command is found, the condition <cond> is evaluated. If <cond> is true, the <program segment> (a number of program lines) is executed. The end of the <program segment> is at the ELSE or at the ENDIF (whichever comes first).

If <cond> is false, Shark looks for ELSE. If ELSE is found, the <ELSE program segment> is executed. The execution continues with the program line following the ENDIF.

Note that ELSE is optional.

There can be an IF command within an IF command; this is called nesting. Many level of nesting is permitted; however, too many levels of nesting will give a compile-time error message: Stack overflow.

Care should be taken to nest the IF commands properly in a DO WHILE, DO CASE, or REPEAT program structure. When editing with the internal Shark programming editor (see WRITE command), Alt-F reformats the file with all structures properly indented, making it easy to see unbalanced structures.

IF may not take a macro. Since a line with a macro is not compiled until runtime, Shark will be unable to handle nesting properly if a macro is used, resulting in the error message "ENDIF implies IF" or "ELSE implies IF". For an alternative, see example 4 below.

Examples:


IF count>5
   STORE T TO ok
ELSE
   IF count<2
      STORE F TO ok
   ENDIF
   ? 'ok'
ENDIF

Indenting the program lines helps to show the level of nesting of the structures. In WRITE, Alt-F indents the lines and capitalizes the command verbs.

Rewrite:

do while count<5
if name='DAVID'
name=name+fname
enddo
endif
as follows:
DO WHILE count<5
   IF name='DAVID'
      name=name+fname
   ENDIF
ENDDO

Consider the following simple program:

IF num=1
   name='DAVID'
ELSE
   IF num=2
      name='GEORGE'
   ELSE
      IF num=3
         name='TOM'
      ELSE
         name='UNKNOWN'
      ENDIF
   ENDIF
ENDIF

This series of nested IF commands (often called "cascading IFs") is equivalent to the following DO CASE structure:

DO CASE
CASE num=1
   name='DAVID'
CASE num=2
   name='GEORGE'
CASE num=3
   name='TOM'
OTHERWISE
   name='UNKNOWN'
ENDCASE

The DO CASE form is much easier to understand.

If <cond> must be a macro, use the following technique instead:

cond2=' '  ;make sure cond2 exists
cond2=&condition  ;assign macro to pre-existing variable
IF cond2 ; now IF does not have a macro
   ...

INDEX

INDEX ON

Create an index file.

  
 INDEX ON <str exp> TO <file> [FOR <cond>]
                                              
 <str exp>  the expression providing the key  
 <file>     the name of the index file        
 

Option:

                                               
 FOR <cond> a selection; only records for which <cond> is true are   
               included in the index.         
 

The INDEX ON command creates an index file. Index files are used

1. To organize records into an apparent order according to some key for listing, reporting, browsing, editing, etc.

2. To locate records quickly using the FIND, NEAREST, LAST, SEEK, POST and UPDATE commands. Each key must have a separate index file.

3. To make the file act as though it has only records matching a given selection condition and an apparent order according to some key.

The expression <str exp> must evaluate to a string of length at most 60; otherwise, an error message is sent. In addition, the condition itself must be no more than 100 characters long.

(Do not use COMP for the first four letters of an index file; Shark is unable to open such a file.)

Once an index file exists, the data file can be opened for use with the index file; see the USE <data file> INDEX <index file> command. The commands: APPEND, BROWSE, CHANGE, EDIT, REPLACE, READ automatically update the index files in use. There can be many index files in use, all are updated by these commands, but only one index file works with FIND.

If SET TALK ON, INDEX will output progress reports showing the completion of each 100 records, and the total number of records indexed. Large files create temporary files which are then merged to create the ultimate index.

Index expressions should be of type string, but a numeric field (not a numeric expression) can also be used. If you wish to index on a numeric expression, use the key STR(<num exp>) or PIC(<num exp>, <format)) to convert the values to strings. See the functions STR( and PIC(.

It is often helpful to use the upper-case functions, !( or UPPER(, for string expression that mix upper-case letters and lower-case letters, such as names, addresses, and so on. This way, the data is arranged in alphabetical order instead of the ASCII code order which is often confusing. See the functions CHR( and RANK(.

On a network with SET NETWORK ON in Shark Network Edition, attempting to create an index while another user is accessing a file with the same name will cause a LOCK error.

To index on part of a field:

inde on $(CUST,1,3) TO CUSTOMER

To index on two fields:

1>USE employee
1>INDEX ON name+age TO senior
      6 RECORDS IN TOTAL INDEXED

To freshen an index, see the REINDEX command, as in this example:

1>USE employee
1>FIND B
27. File is not indexed.

1>INDEX ON name TO employee
      6 RECORDS IN TOTAL INDEXED
1>LIST name
      2  Balzer
      1  Marek
      5  Poyner
      4  Rayme
      3  Steiner
      6  Wilson
1>FIND R
1>DISP name
      4  Rayme

Note that once the data file is indexed, you can use FIND:

FIND R
1>? name
4 Rayme

For example, a data file has a numeric field AMOUNT containing numbers from 1 to 5,000; to index the file in decreasing order use the key:

STR(10000-amount,6)

Or, a mailing list has 50,000 records, including about 250 from Utah. An efficient way to select and print a listing of all those in Utah is:

USE maillist
INDEX ON zip TO utah FOR state='UT'

INDEX FROM

Create an index file, using the index key of an existing SharkBase, VP-Info, dBASE, or Clipper index file.

 INDEX FROM  [TO <file>] [FOR <cond>]
                                              
 <filename>  the name of an existing SharkBase, VP-Info, dBASE, Clipper or FoxPro index file  

Options:

<file>      the name of the SharkBase index file to be created
               with the same key expression as ; default  
               is same as original  
 FOR <cond>  a selection; only records for which <cond> is true are 
               included in the index 

The INDEX FROM command creates an index file using the index expression of an existing index, even if the existing index is corrupt and even if it's from any version of VP-Info, dBASE (II, III, or IV), FoxPro or Clipper. If the same name is given with the TO clause, the original file is overwritten.

Note: All SharkBase and Clipper indexes use the extension NTX, while all VP-Info, dBase and FoxPro indexes use the extension NDX for their mutually incompatible indexes. If the FROM file in this command is specified as an NDX, the TO file may have the same name with an NTX extension.

When making an index from one created in Clipper, dBASE or FoxPro, be aware that some expressions from these languages may not be valid in SharkBase; if an invalid expression is encountered, an error message is sent. In addition, the <cond> used with the optional FOR clause must be no more than 100 characters long.

Among the programs shipped with SharkBase is CONV_INV.PRG, which users with existing applications may use to automate the conversion of indexes. Whenever SharkBase cannot understand the index expression in the existing index file, the program prompts for an alternate index expression using SharkBase functions and operations. When the FROM file is a Clipper NTX which requires a different expression for its use under SharkBase, both expressions are retained so Clipper will handle it properly as well.

For users with existing applications which must be retained in dBASE or FoxPro, you may use the FILES ... ENDFILES structure to point to data and index files in your dBASE or Clipper directory.

(Note: You may not use COMP for the first four letters of a data or index file; SharkBase is unable to open such a file with the USE command.)

Once an NTX index file exists, the data file can be opened for use with it; see the USE <data file> INDEX <index file> command. The commands: APPEND, BROWSE, CHANGE, EDIT, REPLACE, READ automatically update the index files in use. There can be many index files in use, all are updated by these commands, but FIND and its variants works with only one index file at a time.

If SET TALK ON and in Conversational SharkBase, INDEX FROM will output reports showing progress and the total number of records indexed. Large files create temporary files which are then merged to create the ultimate index.

On a network with SET NETWORK ON in SharkBase Network Edition, attempting to create an index while another user is accessing a file with the same name will cause a LOCK error.

Index files are discussed more fully in the Index TO command below. See also the REINDEX command.

Examples:

1.

1>USE employee
1>INDEX FROM emplnum TO emplnum
      6 RECORDS IN TOTAL INDEXED
1>INDEX FROM emplnum
      6 RECORDS IN TOTAL INDEXED
1>INDEX FROM emplnum TO empmarry FOR married
      4 RECORDS IN TOTAL INDEXED

2. An application written in dBASE keeps its data and index files in C:\DATA. The following FILES ... ENDFILES structure is in the CNF files executed when SharkBase was started:

FILES
*.dbf,c:\data
*.ndx,c:\data
*.ndt,c:\shark\ntx
*.frm,c:\shark\prg
ENDFILES

This allows the DBASENDX.PRG program in the Reference Guide to work properly, assuming that C:\DATA has no more than a screenful of data files, and all index files share the first four letters with the data file on which they are created (an excellent practice).

INPUT

Input request for data of any type.

  
 INPUT ['<string>'] TO <memvar>               

Option:

                                              
 '<string>'     prompt message                
 

The command INPUT is used to enter string, numeric, or logical data into a memory variable, <memvar>. It works the same way as the command ACCEPT (see ACCEPT), except that string input needs quotation marks.

The type of the <memvar> is determined as follows:

If the data typed in is in quotation marks, it is a string; <memvar> is of character type.

If the data is a number, <memvar> is of numeric type.

If the data is Y, y, N, n, T, t, F, or f, <memvar> is of logical type.

The optional character string is used as a prompt. A character expression cannot be used, but a macro is permitted, provided the macro expression includes quotation marks.

ACCEPT is the preferred way to enter strings, since ACCEPT does not require quotation marks as delimiters.

<memvar> cannot be a matrix variable.

Examples:

1>INPUT 'Your name: ' TO name
Your name: 'Cathy'
1>INPUT 'Your age: ' TO age
Your age: 32
1>INPUT 'Are you telling the truth? ' TO truth
Are you telling the truth? n
1>LIST MEMO

Name          Type    Width    Contents
NAME            C       5      Cathy
AGE             N       8      32
TRUTH           L       2      .F.
** Total **  3  variables, 15  bytes

The following illustrates use of a variable instead of a string as the prompt:

1>prompt='"This is a prompt: "'
1>INPUT &prompt TO hello
This is a prompt:  4
1>LIST MEMORY
Name          Type    Width    Contents
PROMPT          C      20      "This is a prompt: "
HELLO           N       8      4
** Total ** 2  variables... 28  bytes

KEY

Initiates a program segment (a KEY procedure) in an ON KEY structure

  
 KEY <number> <caption>                     
 KEY <func_key> <caption>                   
                                              
 <number>         character number as returned by INKEY( function   
 <func_key>       function key name, in range F1 to F10        

Option:

                                            
 caption          string to be printed on line 24 of screen    
                    (space permitting)        
 

This command has two forms, allowing you to specify the key to be affected either by its number (any character number greater than 255) or by its name if it is a function key in the range of F1 to F10 inclusive. (F11 and F12 are not supported by SharkBase.)

In either case, all commands that follow until another KEY command or the ENDON command constitute a procedure that will be executed whenever the specified key is pressed by the user.

Captions are automatically displayed on line 24 of the screen, and saved whenever a KEY procedure is executed. When the procedure is complete, line 24 is redisplayed. If keys are specified by a function key name (F1 through F10), the key name is automatically shown (along with caption). The spacing between captions is controlled by the number of trailing blanks in the caption on the KEY command line.

A KEY command with no procedure in an ON KEY structure merely turns off the named key. This can be extremely useful in deactivating such keys as


Ctrl-<Pg Dn>.

Note: KEY commands in the ON KEY structures cannot be accessed while SharkBase waits for a keystroke in the MENU( function or the WAIT command.

Examples:

ON KEY
KEY F1 Help
   SCREEN 1,2
   WINDOW
   CLS
   TEXT help
   WAIT
   SCREEN 2,1
KEY F2 Browse
   SAVE gets to test
   SCREEN 1,2
   WINDOW
   CLS
   TEXT browse
   BROWSE off
   SCREEN 2,1
   RESTORE gets from test
KEY 328
*  deactivate up arrow key
KEY 374
*  deactivate Ctrl-<Pg Dn> key
KEY F10 Turn Off Keys
   ON KEY
   ENDON
ENDON

LAST

Find the last record matching a given FIND string by its index in the selected data file.

LAST <string>                               
                                              
 <string>   the characters to match in the current master index 

LAST is one of a family of commands that finds a record in an indexed data file by matching a given string with key values in the index file:

LAST positions the file on the last record in the index matching the FIND string (no-find positions the file at the top of file)

FIND positions the file on the first record in the index matching the FIND string (no-find positions the file at the top of file)

NEAREST positions the file on the first record in the index equal to or greater than the FIND string

SEEK is identical to FIND, except that it searches for the match to the value of a character expression instead of a string constant (no-find positions the file at the top of file)

All forms allow a search to be made on a character expression when the expression if preceded by the macro symbol "&". When the variable var='TAYLOR', both of the following command lines are equivalent:

LAST TAYLOR
LAST &var 

In Conversational Shark, just type LAST and the key.

Examples:

1>LAST TAYLOR
1>LAST TOM

If SET DELETE ON, deleted records will not be found. (See the command SET.)

Numbers must always be treated as strings, even if the key expression is a numeric field. If NUM is a numeric field of width 2, LAST 1 will not find 1, but LAST &STR(1,2) or LAST &' 1' will be successful.

For the users' convenience, Conversational Shark converts all command lines to upper case before execution. So, to find the inventory numbers that start with AB, type either of the following two commands:

1>LAST AB
1>LAST ab

It follows that

1>LAST Taylor

is understood by Shark as LAST TAYLOR. If you have to find Taylor, either use the string directly with the macro symbol:

1>LAST &'Taylor'

or if name='Taylor' use the following:

1>LAST &name 

When LAST is successful, the value of the current record pointer (as shown by the # and RECNO( functions) is set to the current record number, and the system variable :NEAR is set to the same number.

If the record is not found, the current record pointer will be set to 0 and the value of :NEAR will be set to the number of the first record in the index with a key greater than the FIND string; if the index contains no key greater than the FIND string, :NEAR is set to the bottom of file, and EOF is set to T (true).

For a fuller discussion, see the FIND command.

LIMIT

NOTE: In Shark, SCOPE and LIMIT are identical. However, the LIMIT command doesn't exist in VP-Info, only a simpler SCOPE command.

Limit the records available within the current master index to those matching all or part of the current record's index key.

 
LIMIT <num exp>
LIMIT <key exp>
LIMIT

Options:

<num exp>    the number of characters in the key expression of
                 the current master index
 <key exp>    the string expression to match in the current master index

When the current file has an index, Shark can be made to treat the file as though it includes only those records matching the current record's key expression, or some leftmost part of it. When a LIMIT is in effect, no Shark command can access a record outside that limit.

You can most quickly implement this command by using the <num exp> option. The effect is to have Shark set the LIMIT to the leftmost <num exp> characters of the key expression of the master index.

If <num exp> exceeds the length of the key, the effect is identical to setting the LIMIT to the entire index expression. (Maximum index-key length is 60 characters.)

When LIMIT is used with no option, or when <num exp> is zero, the limit is deactivated.

Using LIMIT with <key exp> requires precision in its use to avoid problems that may become extremely serious. Note that the <key exp> expression must be the same as the master index key in use at the moment, or some LEFT( portion of it. Do not attempt to use an expression that does not meet this requirement.

Cautions:

1. FIND should not be used on a file with an active limit. If you choose to do so, be certain that the FIND will be successful. An unsuccessful FIND places the record pointer on record 0 which is by definition not in the index. This causes an error, suspends operation of a program, and turns off the LIMIT.

2. Do not use REPLACE ALL on a field included in an active limit expression, since upon completion, no records will be included in the limit; the result is the same as above.

3. Do not use APPEND, APPEND BLANK or BROWSE APPEND, or enter "append mode" in EDIT, while a limit is active unless you are sure to make all new records equal to the current LIMIT key before leaving the new records. Doing so causes the record pointer to move outside the LIMIT; the result is the same as above.

4. LIMIT should be used with extreme care, and left in effect for the minimum number of commands possible. For instance, if used with BROWSE, LIMIT should be invoked immediately before the BROWSE command and canceled immediately afterward.

5. LIMIT is automatically canceled when the index or the file with which it is active is closed, or the master index is changed with SET INDEX TO n.

6. LIMIT cannot be used with a string constant instead of a <key exp>. The <key exp> can be implemented with a macro.

LIST

List expressions from selected records.

  
 LIST <scope> [FOR <cond> <exp list>] [OFF]                

Options:

                                              
 <scope>        select by scope (default scope: ALL)           
 FOR <cond>     select by condition           
 <exp list>     items to list                 
 OFF            do not print the record numbers                
 

This command lists the whole selected data file (including the records flagged as DELETED, unless the command SET DELETE ON is given). If the data file is indexed, the listing is by the indexed order.

The records to be listed can be selected by scope and/or by a condition. To list only selected fields of the records, use an expression list.

Examples:

 
1>USE employee
1>LIST
      1  Marek           Joe        231 River Drive      Broomsdale
      2  Balzer          Joan       2407 E 38th Street   Broomsdale
      3  Steiner         Tom        114 North Pitt St.   Lakewood
      4  Rayme           Pamela     42368 Wedgewood Dr.  Broomsdale
      5  Poyner          Roger      2757 Regency Road    Florington
      6  Wilson          Robert     16255 Ventura Street Broomsdale
1>GO TOP
1>LIST NEXT 3 fname,name
      1  Joe        Marek
      2  Joan       Balzer
      3  Tom        Steiner

LIST FILES

List files from the directory.

 
 LIST FILES [LIKE <file format>] [ON <drive letter>]

Options:

 
 LIKE <file format>   limit to those files matching the file format
                         specification (default .DBF)
 ON <drive letter>    show only files on named disk (colon optional)

This command lists the data files, with the default extension DBF, from the current or other specified disk drive. LIST FILES is provided only for compatibility with earlier xBase languages; DIR should be used instead.

If the LIKE clause is used, the type of file required can be specified; the wild cards * and ? (see the DIR command) can be used just as in the operating system command DIR.

If the ON <drive letter> clause is used, only the files from the drive specified are listed.

See the Shark command DIR

Examples:

 
1>LIST FILES
CCUST.DBF       1024 10-24-89  1:07a   COMMS.DBF       1024 10-24-89  1:07a
COMMS.DBF        757  8-31-89 11:30p   CUSTJUNK.DBF     653  9-06-89  9:02a
CUSTOMER.DBF    1024 10-24-89  1:07a   RUST2.DBF     342058 11-29-89  8:25p
SUBDUE.DBF      2027 11-29-89  7:21p   SUBDUE2.DBF     1168 11-29-89  2:29a
WAY_BUSI.DBF  506022 10-24-89  2:24a   WAY_PHON.DBF   45525 10-24-89  1:29a
WAY_DBFS.DBF    1291 10-24-89  3:15a   WAY_RES.DBF   406175 10-24-89  1:05a

1024349 bytes in 12 files.
5251072 bytes remaining.
1>LIST FILES ON A
THREE.DBF        189  6-12-88  9:21a   TRANSACT.DBF       2  5-02-88  2:48p
VAITEST.DBF      552  7-28-88 12:32p

795603 bytes in 41 files.
51072 bytes remaining.
1>LIST FILE LIKE c*.*
CCUST.DBF        522 10-13-88  5:42p   COMMS.DBF       6546  1-06-90  5:11p
COMMS2.DBF      6342  1-07-90  1:00p   CUSTJUNK.DBF    7062  9-17-89  3:57p
CUSTOMER.DBF     734 11-29-89 10:43p

21206 bytes in 5 files.
5251072 bytes remaining.

LIST MEMORY

List the memory variables.

 
 LIST MEMORY

The command LIST MEMORY displays a listing of all non-matrix memory variables and their contents, and a separate listing of the matrix variables and their dimensions.

Examples:

 
1>LIST MEMO
Name          Type    Width    Contents
** Total **  0  Variables used  0  Bytes used
1>name='David'
1>number=12.78
1>LIST MEMO

Name          Type    Width    Contents
NAME            C       5      David
NUMBER          N       8      12.78
** Total **  2  Variables used  13  Bytes used
1>DIM NUM a[12]
1>DIM CHAR table[2,12]
1>LIST MEMO

Name          Type    Width    Contents
NAME            C       5      David
NUMBER          N       8      12.78

Matrix Name   Type    Width    Dimensions
A               N       8      [12]
TABLE           C      10      [2,12]
** Total **  4  Variables used  33  Bytes used

Note that matrix variables are stored in high memory (see Appendix A). The number of "bytes used" message does not take this into account. To see the usage of high memory, use the STATUS command. See also DIM.

LIST STRUCTURE

List the structure of the selected file

LIST STRUCTURE

The command LIST STRUCTURE displays the structure of the selected data file.

Examples:

1>USE employee
1>LIST STRU
Data file:           EMPLOYEE.DBF
Number of records:       6
File number:             1
Field   Name       Type Width   Dec
  1     NAME         C     15
  2     FNAME        C     10
  3     ADDR         C     20
  4     CITY         C     20
  5     STATE        C      2
  6     ZIP          C      5
  7     TEL_NO       C      8
  8     MARRIED      L      1
  9     SALARY       N      9      2
 10     YEAR_EMP     N      4
 11     DEPT         C     15
** Record Length **       110

1>USE#5 order
1>LIST#5 STRU
Data file:           ORDER.DBF
Number of records:       3
File number:            #5
Field   Name       Type Width   Dec
  1     ORDER:NO     C      6
  2     CUST:NO      C      6
  3     INVEN:NO     C      6
  4     STYLE:NO     C      4
  5     COLOR        C      2
  6     CATEGORY     C      2
  7     DESCR        C     30
  8     SLSMAN:NO    C      3
  9     PRICE        N      9      2
 10     QTY          N      9      2
 11     COST         N      9      2
 12     AMOUNT       N      9      2
** Record Length **        96

LIST SYSTEM

List the function key definitions and system variables.

LIST SYSTEM 

The command LIST SYSTEM displays the current contents of the 10 function keys and system variables (see Sections 1.2 and 2.6).

Example:

1>LIST SYST
Name          Type    Width    Contents
:F1             C       5      HELP
:F2             C      10      LIST STRU;
:F3             C       6      WRITE
:F4             C      10      LIST MEMO;
:F5             C       7      BROWSE;
:F6             C       5      STAT;
:F7             C      12      ^wCONT;EDIT;
:F8             C      11      LOCATE FOR
:F9             C       5      FIND
:F10            C       5      EDIT;
:TIME           C       8      22:53:43
:DATE           C      24      Thursday, March 19, 1991
:VERSION        C       4      520
:SERIAL         C      10      5208796982
:COMPANY        C      34      Sub Rosa Publishing Inc.
:PICTURE        C      10      9999999.99
:TITLE          C       1
:UNDOC          C       1      2003.03.14  <-- you can store application data in system
:KEY            N       8      13
:AVAIL          N       8      0
:FIELD          N       8      0
:ERROR          N       8      0
:MESSAGE        C       1
:RETRY          N       8      25
:USER           N       8      1
:DIR            C      11      C:\SHARK
:NEAR           N       8      0
:COLOR          N       8      48
** Total ** 28  variables... 244  bytes

To set the system variables to suit your needs, use your CNF file as appropriate, see Section 1,"Command and Function Reference".

LOCATE

Search for a record that satisfies the condition.

LOCATE <scope> FOR <cond>                  

Option:  <scope>   search only within the limit (default limit: ALL) 

The command LOCATE searches for records by a condition. This command works quicker if there is no index file. If a match is found with SET TALK ON, Record n informs the user of the record number (n).

The LOCATE command line cannot be more than 128 characters. The keyword FOR cannot be in a macro.

The CONTINUE command continues the search after the current record using the condition of the last LOCATE.

Normally, the selected file should not be indexed. The command LOCATE executes several times slower in an indexed file. If an index file is in use, the search will take place in the indexed order.

The preferred way to locate a record in an indexed file is with the FIND command.

With the default scope ALL, LOCATE starts at the top of file and scans either until the first record matching the condition is found, or the end of file is reached; an unsuccessful LOCATE sets the EOF flag to T (true).

You can use an alternate scope, NEXT or WHILE, to have LOCATE begin with the record after the current record. Unlike all other uses of limit in Shark (or SCOPE in VP-Info), however, LOCATE does not require anything other than the keyword to make the limit act in this way.

Example:

LOCATE NEXT FOR cust>'M'  ;looks for a matching record anywhere in the file, starting with the next record. 
LOCATE WHILE FOR cust>'M' ;works exactly the same.

Examples:

1>USE employee
1>LIST name, salary
      1  Marek
      2  Balzer
      3  Steiner
      4  Rayme
      5  Poyner
      6  Wilson
1>GO TOP
1>LOCATE FOR salary > 20000
Record 1
1>? name, salary
Marek            25800.00
1>CONT
Record 3
1>? name, salary
Steiner          35780.00
1>CONT
Record 4
1>? name, salary
Rayme            79110.00
1>CONT
Record 6
1>? name, salary
Wilson           33870.00
1>CONT
1>? EOF
T

LOCK

Lock the current record.

 LOCK                                         

In Shark Network Edition, this command locks the current record to all other users so that you can safely make changes to a record key while the file is open in SHARE mode.

 
If SET NETWORK OFF, LOCK is ignored.

In the single-user edition, LOCK has no effect, but is accepted for program compatibility across versions.

See the command on how to get into the multi-user mode. See also UNLOCK.

Example:

mcust=cust
FIND &mcust
LOCK

LOCK INDEXES

Lock the current record.

LOCK INDEXES                                 
 

In Shark Network Edition this command locks all indexes attached to the current data file so that you can safely make changes to a record's key while the file is open in SHARE mode.

Like the LOCK command (which locks records in a data file), and SET LOCK ON (which automatically locks each record as it is used), LOCK INDEX should be used only when files are opened in SHARE mode on a network.

LOCK INDEXES allows only one person to change the index files, though any number of others can access the indexes if they open the data file in either SHARE or READ mode. UNLOCK INDEXES will unlock the all the index file.

See the SET NETWORK command on how to get into the multi-user mode. See also UNLOCK INDEXES.

In the single-user edition, LOCK INDEXES has no effect, but is accepted for program compatibility across versions.

Example:

mcust=cust
FIND &mcust
LOCK INDEXES

LOOP

Jump to the top of the DO WHILE loop.

 LOOP                                         

When the LOOP command is found in a DO WHILE <cond> loop, program execution jumps to the top of loop (evaluates the condition). See also DO WHILE and BREAK.

Example:

USE cust
USE#2 trans INDEX trans1
DO WHILE T
   ACCEPT 'Enter the customer number ' TO mcust
   IF TRIM(mcust)=' '
      BREAK
   ENDIF
   FIND#2 &mcust
   IF RECNO(2)=0
      LOOP
   ENDIF
   SELECT 2
   DO WHILE custn=mcust .AND. .NOT. EOF
      ? date,descript,amount
      SKIP
   ENDDO
   SELECT 1
ENDDO

MAX

Scan selected records for the highest values of one or more numeric expressions.

MAX <scope> <num exp list> [TO <memvar list>] [FOR <cond> ] <num exp list>    
the numeric expressions to sum   

Options:

<scope>  select by scope (default scope: ALL)
<memvar list>     store the results in these memory variables 
FOR <cond>        select by condition        

The command MAX evaluates numeric expressions for selected records of the selected data file, determining the highest value encountered for each expression. Up to 10 expressions can be scanned with one command.

Optionally, the results can be stored in numeric memory variables; the expression list and the numeric memory variable list must have the same number of entries. <memvar list> cannot contain numeric matrix variables.

Records flagged as DELETED are not scanned. See also MIN, SUM, COUNT and AVERAGE.

Example:

The highest hourly wages, the highest annual earnings, and the highest number of hours worked in the year:

1>USE employee
1>MAX hourly,ydt_earned,ytd_hours
      6 RECORDS CHECKED
     32.57,  51579.65,   2632.65
1>SET TALK OFF
1>MAX hourly,ydt_earned,ytd_hours TO maxrate,maxearned,maxhours
1>?  maxrate,maxearned,maxhours
     32.57   51579.65    2632.65

MEMORY=

Request a specific memory configuration.

MEMORY=<blocks> (SHARK.SET file only)                 
                                             
<blocks> number of 1K blocks of memory to reserve for high memory  

The command MEMORY= in the SHARK.SET file allocates a specific amount of high memory for use of Shark rather than the default of 128K.

The number of blocks can be as little as 32, although Shark can be expected to be sluggish in performance at that level, and there will be little space available for matrixes and background screens.

High memory is used for a wide variety of tasks in Shark, including storage of index blocks, print spooling, background screen storage, matrixes, table storage, program swap area, etc. Requesting 32 to 127 blocks decreases the space available for these tasks, but increases the space available for storing binary files to be executed with the CALL command (see BINSPACE= command) and for running programs in DOS (see RUN command).

If large amounts of memory are required for matrixes, you may need to request more than 128 blocks. Requesting more memory than available will not cause an error; Shark always takes all the memory there is or the amount requested, whichever is less.

See Appendix A for more about organization of memory.

Example:

MEMORY=96

MIN

Scan selected records for the lowest values of one or more numeric expressions.

MIN <scope> <num exp list> [TO <memvar list>][FOR <cond> ]
                                             
<num exp list>     the numeric expressions to sum             

Options:<scope>    select by scope (default scope: ALL)        
<memvar list>      store the results in these memory variables 
FOR <cond>         select by condition        
 

The command MIN evaluates numeric expressions for selected records of the selected data file, determining the lowest value encountered for each expression. Up to 10 expressions can be scanned with one command.

Optionally, the results can be stored in numeric memory variables; the expression list and the numeric memory variable list must have the same number of entries. <memvar list> cannot contain numeric matrix variables.

Records flagged as DELETED are not scanned. See also MAX, SUM, COUNT and AVERAGE.

Example:

Compute the lowest hourly wages, the lowest annual earnings, and the lowest number of hours worked in the year:

1>USE employee
1>MIN hourly,ydt_earned,ytd_hours
      6 RECORDS CHECKED
      5.57,   1579.65,    232.65
1>SET TALK OFF
1>MIN hourly,ydt_earned,ytd_hours TO maxrate,maxearned,maxhours
1>?  maxrate,maxearned,maxhours
      5.57,   1579.65,    232.65
 

MODIFY

Modify the structure of a data file.

MODIFY [STRUCTURE] 

The command MODIFY (or MODIFY STRUCTURE) modifies the structure of the selected file. The display is the same as in CREATE, the keys retain their meaning. Each field is represented by four editing fields.

All records in the file will be automatically appended. If any types or names are changed, the contents of the affected fields will be lost.

Restrictions:

Do not use MODIFY in a program

Do not use MODIFY merely to change the name of a field. Fields may be renamed instantaneously with the RENAME FIELD command.

Editing keys:

<Left> or Ctrl-S       Moves the cursor back one character
<Right> or Ctrl-D      Moves the cursor forward one character
<Ctrl-Left>            Moves to the beginning of the editing field
<Ctrl-Right>           Moves to the end of the editing field
<Ins> or Ctrl-V        Puts you in insert mode: what you type gets inserted
                            (normally, you are in overtype mode: what you type
                            overtypes the existing text); pressing <Ins> or
                            Ctrl-V again, puts you back into overtype mode
<BACKSPACE>            Deletes the character to the left of the cursor
<Del> or Ctrl-G        Deletes the character on the cursor
Ctrl-Y                 Deletes the rest of the editing field
<Up> or Ctrl-E         Moves the cursor to the previous editing field
<Dn> or Ctrl-X         Moves the cursor to the next editing field
Ctrl-Q                 Quits and does not modify the file
<End> or Ctrl-W        Quits and modifies the file
Ctrl-K                 Moves back to the top of the previous page
Ctrl-L                 Moves to the top of the next page
Ctrl-N                 Inserts a new line
Ctrl-T                 Deletes the line

To be safe, make a back up copy of the file to be modified before the MODIFY command is given. After the MODIFY, the new fields will be blank, the deleted fields disappear. All deleted records will also be lost.

If or Ctrl-Q is pressed at any time in MODIFY before the appending of records is completed, MODIFY will be aborted and the data file closed.No changes already made will be saved.

Changing the characteristics of a field (say the width) effects the field the same way as in APPEND FROM.

On a network with SET NETWORK ON in Shark Network Edition, attempting to MODIFY a file while another user is accessing it will cause a LOCK error. Always open a file in LOCK mode before modifying it.

Example:

Change the FNAME field in EMPLOYEE.DBF from 10 characters to 15 characters.

1>USE employee
1>COPY employee to temp                    making a backup copy
1>MODIFY

Thursday, March 22, 1990
                                 Shark Modify               EMPLOYEE.DBF
Name         Type    Width   Dec        Name         Type    Width   Dec

NAME          C       15      0
FNAME         C       10      0
ADDR          C       20      0
CITY          C       20      0
STATE         C        2      0
ZIP           C        6      0
TEL_NO        C       10      0
MARRIED       L        1      0
SALARY        N        9      2
YEAR_EMP      N        4      0
DEPT          C       15      0


UP/DOWN           COLUMN MOVE  ROW            SAVE STRUCTURE    C..Strings
 previous. <PgUp>  left... ^K   insert... ^N   update... <End>   N..Numbers 
 next..... <PgDn>  right.. ^L   delete... ^T   nochange. ^Q      L..Yes/No  

     Now change 10 to 15:

Thursday, March 22, 1990
                                 Shark Modify               EMPLOYEE.DBF
Name         Type    Width   Dec        Name         Type    Width   Dec

NAME           C       15      0
FNAME          C       15      0
ADDR           C       20      0
CITY           C       20      0
STATE          C        2      0
ZIP            C        6      0
TEL_NO         C       10      0
MARRIED        L        1      0
SALARY         N        9      2
YEAR_EMP       N        4      0
DEPT              C       15      0


UP/DOWN           COLUMN MOVE  ROW            SAVE STRUCTURE    C..Strings 
 previous. <PgUp>  left... ^K   insert... ^N   update... <End>   N..Numbers 
 next..... <PgDn>  right.. ^L   delete... ^T   nochange. ^Q      L..Yes/No  

NEAREST

Find the first record whose index key is equal to or greater than a given FIND string by its index in the selected data file.

  
NEAREST <string>                             
                                              
<string>   the characters to match in the current master index
 

NEAREST is one of a family of commands that finds a record in an indexed data file by matching a given string with key values in the index file: NEAREST positions the file on the first record in the index equal to or greater than the FIND string. If no key in the index is equal to or greater than the FIND string, the current record pointer and :NEAR are set to the bottom of file, and EOF is set to T (true)

FIND positions the file on the first record in the index matching the LAST string (no-find positions the file at the top of file)

LAST positions the file on the last record in the index matching the FIND string (no-find positions the file at the top of file) SEEK is identical to FIND, except that it searches for the match to the value of a character expression instead of a string constant (no-find positions the file at the top of file)

All forms allow a search to be made on a character expression when the expression if preceded by the macro symbol "&". When the variable var='TAYLOR', both of the following command lines are equivalent:

NEAREST TAYLOR
NEAREST &var

In Conversational Shark, just type NEAREST and the key.

Examples:

1>NEAREST TAYLOR
1>NEAREST TOM

If SET DELETE ON, deleted records will not be found. (See the command SET.) Numbers must always be treated as strings, even if the key expression is a numeric field. If NUM is a numeric field of width 2, NEAREST 1 will not find 1, but NEAREST &STR(1,2) or NEAREST &' 1' will be successful.

For the users' convenience, Conversational Shark converts all command lines to upper case before execution. So, to find the inventory numbers that start with AB, type either of the following two commands:

1>NEAREST AB
1>NEAREST ab

It follows that

1>NEAREST Taylor

is understood by Shark as NEAREST TAYLOR. If you have to find Taylor, either use the string directly with the macro symbol:

1>NEAREST &'Taylor'

or if name='Taylor' use the following:

1>NEAREST &name 

By definition, NEAREST is always successful (unless the file is empty). If an exact match is found, both the current record pointer (as shown by the # and RECNO( functions) and the system variable :NEAR are set to the first matching record.

If an exact match is not found, the current record pointer and the value of :NEAR will be set to the number of the first record in the index with a key greater than the FIND string; if the index contains no key greater than the FIND string, the current record pointer and :NEAR are set to the bottom of file, and EOF is set to T (true).

To position the record pointer to the record equal to or immediately less than the FIND string, do the following:

NEAREST &findstring
IF keyexpr<findstring
   SKIP -1
ENDIF

NOEFFECTS

Suppress special effects.

 NOEFFECTS

(Use in SHARK.SET file only)

This command in the SHARK.SET file suppresses the special screen and sound effects used for the sign-on screen, as well as for the SCREEN, SOUND, and RING commands.

Examples:

 NOEFFECTS

NOTE

Add notes to Shark programs.

 NOTE <string>

Option:

<string>   any text line: the comment

This is the same as the command * (see *). Any Shark command line that starts with NOTE is ignored by Shark.

Notes can also be added to any command line with a semicolon(;)

Since notes are not compiled, they have no effect on the execution of programs. Comments should be used liberally to help you (and possibly others) understand your programs later. If programs are very large, however, some comments may have to be shortened or eliminated to allow the compiler and/or WRITE to load them properly.

Examples:

 
NOTE This is the start of the main menu display (Shark ignores this line)
IF cust=mcust ;the start of the processing for the current customer (Shark ignores text after ";")

NOUPDATE

Do not write changes made to the current record back to the disk.

NOUPDATE

Whenever a change is made to the current record in an open data file, leaving the record or closing the file causes the changes to be written to the disk. This automatic action can be overridden by the NOUPDATE command, which tells Shark to ignore the changes.

This is essentially what happens when Ctrl-Q is pressed during EDIT and BROWSE.

Example in a program:

Suppose full-screen editing is in effect with the READ command, and you want to ignore any changes made to the record if the user presses Ctrl-Q or an erroneous key like Ctrl-T and Ctrl-U. Using the :KEY system variable that stores the key number of the key pressed to terminate the last process:

DO WHILE t
   READ
   IF :key=17 .OR. :key=20 .OR. :key=21  ;key numbers of ^Q, ^T and ^U
      NOUPDATE
      LOOP
   ENDIF
   DO CASE
   CASE :key=...                         ;check a key
      ...                                ;action based on :key value
   ENDCASE
ENDDO

ON ERROR

Tell Shark what to do if an error is encountered during program execution.

ON ERROR

The command ON ERROR starts the ON ERROR/ENDON structure. There can be any program segment between ON ERROR and ENDON, except that no data files should be opened or closed, and no new variables created or released. This program segment is executed whenever the program encounters an error.

The ON ERROR is in effect in the program from the point where it is located. It remains in effect until another ON ERROR structure is found, or until execution leaves the current module, either on a RETURN or DO command.

ON ERROR has no effect within a subroutine called by the DO command; if the subroutine needs the same ON ERROR structure, repeat the structure in the subroutine.

Since the ON ERROR structure has no effect after returning to a calling program from a subroutine, you should consider putting this structure (possibly together with the ON ESCAPE structure) into a procedure that is performed at the beginning of the program, and after every DO command.

ON ERROR should normally include a CHAIN, CANCEL, or QUIT command to allow execution to leave the current program. Do not RETURN from a main routine.

When editing with the internal Shark programming editor (see WRITE command), Alt-F reformats the file with all structures properly indented, making it easy to see unbalanced structures.

Example:

ON ERROR
   ? 'Aborting program execution because Error',:error,'encountered'
   ? :message      ;  :error contains the latest error number, and
   ?               ;  :message contains its meaning
   RING
   CANCEL
ENDON

ON ESCAPE

Tell Shark what to do if the user presses .

 ON ESCAPE

The command ON ESCAPE starts the ON ESCAPE/ENDON structure. There can be any program segment between ON ESCAPE and ENDON, except that no data files should be opened or closed, and no new variables created or released. This program segment is executed whenever the user presses .

The ON ESCAPE is in effect in the program from the point where it is located. It remains in effect until another ON ESCAPE structure is found, or until execution leaves the current module, either on a RETURN or DO command.

ON ESCAPE has no effect within a subroutine called by the DO command; if the subroutine needs the same ON ESCAPE structure, repeat the structure in the subroutine.

Since the ON ESCAPE structure has no effect after returning to a calling program from a subroutine, you should consider putting this structure (possibly together with the ON ERROR structure) into a procedure that is performed at the beginning of the program, and after every DO command.

ON ESCAPE should normally include a CHAIN, CANCEL, or QUIT command to allow execution to leave the current program.

When editing with the internal Shark programming editor (see WRITE command), Alt-F reformats the file with all structures properly indented, making it easy to see unbalanced structures.

Example:

ON ESCAPE
   ? 'Aborting program execution because  key pressed.'
   RING
   CANCEL
ENDON

ON FIELD

Control the processing of data input during execution of the full-screen editing commands: READ, EDIT, APPEND, and BROWSE.

 ON FIELD

The command ON FIELD starts the ON FIELD/ENDON structure. There can be any program segment between ON FIELD and ENDON, except that no data files should be opened or closed, and no new variables created or released.

Inside the ON FIELD structure is a number of FIELD statements, each telling Shark what to do when the user leaves a specific field, enters a new record, or leaves the record. There can be one FIELD statement for each input field in a Get Table, in addition to the two FIELD statements controlling entry and exit from READ (or the current record in EDIT and BROWSE).

(Note that the term editing field does not refer in this case only to fields, but to the on-screen area where you're expected to enter or edit data; an editing field may be a "window into" a data-file field, a memory variable, or a system variable. An element in a matrix cannot be accessed with the full-screen editing commands, so cannot be tied to an editing field.)

ON FIELD is used primarily for the following three functions:

1. To verify data input. If the value entered does not meet a condition, the cursor can be directed back to the current field with the :FIELD=FIELD(fieldname) command.

2. To do data lookups from the selected or other files. For example, suppose the first field in the screen is mcust; when a customer number is entered FIND &mcust is executed and the proper record found in the current file. If an invoice number is entered, data can be retrieved from the proper invoice with a FIND into another indexed file.

3. To change the order in which the cursor goes to the next field. For example, a TEXT can have three columns of input figures; Shark normally goes left to right on each line, and then top to bottom, but appropriate use of the :FIELD system variable can direct the cursor to do one column at a time.

ON FIELD exception handling only works with memvars (eg: 'MC') and not with dbf fields (eg: 'CA1'). The data handling works OK, but the ON FIELD doesn't catch the exceptions.

The form of the ON FIELD structure:

ON FIELD
FIELD 0
<initiating command sequence>   ;The FIELD 0 code is executed when READ is
entered or whenever a new record is entered in BROWSE OFF, EDIT OFF, etc.
Field 1

<command sequence 1>            ;The FIELD 1 code is executed when the
cursor leaves the first editing field (and again when the current record is
exited provided SET EXECUTE ON).
Field 2

<command sequence 2>           ;The FIELD 2 code is executed when the
cursor leaves the second editing field (and again when the current record is
exited provided SET EXECUTE ON).
Field <n>

<command sequence <n>           ;The FIELD <n> code is executed when the
cursor leaves the nth (final) editing field (and again when the current record
is exited provided SET EXECUTE ON).
Field 65

<command sequence 65>           ;The FIELD 1 code is executed when the
cursor leaves READ or when the current record is exited in BROWSE OFF, EDIT
OFF, etc.

ENDON

Fields 1 through 64 may be referenced either by number of by the name of the field or variable being edited. Names are usually more understandable and always more flexible, since a field can later be added or omitted without having to renumber the entire ON FIELD structure.

You can force Shark to execute the entire set of FIELD commands from 1 through 64 by SET EXECUTION ON. The default is OFF. Do not use ON if there is a possibility of creating an endless loop which doesn't allow a graceful exit.

The Get Table is usually canceled as soon as execution leaves the current program, even when just executing a subroutine with the DO command. You can SET GET ON to maintain the Get Table, provided it is not cleared in the sub- program. (A Get Table is cleared either with the CLEAR GETS command, or by creating a GET with TEXT or an @ GET command after a READ command.) The default is SET GET OFF.

When editing with the internal Shark programming editor (see WRITE command), Alt-F reformats the file with all structures properly indented, making it easy to see unbalanced structures.

Example:

date1=date(1)
CLS
TEXT
.. date1,99/99/99
               Enter game date (must be a Wednesday)
                           @date1
ENDTEXT
ON FIELD
FIELD date1
   IF DATE(FULL,date1)<>"W"
      :field=FIELD(date1)          ;use FIELD( to get correct number
   ENDIF
ENDON
DO WHILE t
   READ
   <command modules>
ENDDO

Note the placement of the three elements: the TEXT with its input macro and the ON FIELD come before the READ or other full-screen editing command, and are usually outside the DO WHILE loop unless the screen is rewritten elsewhere inside the loop.

When filling in forms in a text screen, Shark moves from left to right. If you wish to fill in fields from top to bottom, you will need to use the field names/numbers to cause Shark to move to the field BELOW rather than the field to the right:

ON FIELD
FIELD 0
@ 0,0 say "Edit Image of Customer Record                                             "
@ 0,52 SAY "Screen 1      File:"+mrnum
color 31,24,0,24,78
:FIELD=1
FIELD 1
:FIELD=3 <-- This field is BELOW Field 1 in a 2 column screen.
FIELD 3
:FIELD=5
FIELD 5
:FIELD=6
FIELD 6
:FIELD=7
FIELD 7
:FIELD=2
FIELD 2
:FIELD=4
FIELD 4
:FIELD=8
FIELD 8
:FIELD=9
FIELD 9
ENDON

ON KEY

Begin ON KEY structure, which contains one or more KEY modules defining actions to execute when specific keys are pressed.

 ON KEY

The ON KEY structure, like the other ON structures in SharkBase, is not executed "in line'' as are other SharkBase commands; it is executed only when a specific condition is encountered.

In the case of the ON KEY structure, every time a key is pressed its key number is checked; if it is in the range 256 through 511, the ON KEY structure is checked to see if a special program segment has been specified for that key number and, if it has been, the program segment is executed.

The form of the ON KEY structure is as follows:

ON KEY
KEY <key spec 1> <caption>
   <program segment 1>
KEY <key spec 2> <caption>
   <program segment 2>
..
KEY <key spec n> <caption>
   <program segment n>
ENDON

Each KEY command introduced a program segment that is essentially a complete procedure, and like other procedures in SharkBase require a stable environment. Any program segments can be between ON KEY and ENDON, except that no data files may be opened or closed, and no new variables created or released. The data files open when the ON KEY structure is executed must remain use as long as the ON KEY is in effect.

In addition, the current work area for the program segments in the ON KEY structure will be the same as the work area in effect when the structure is first encountered. Therefore, an ON KEY program segment cannot be used to change the work area

There can be a maximum of 32 KEY statements in an ON KEY structure. All existing Key procedures are terminated by CHAINing or exiting from a program, or by encountering another ON KEY/ENDON structure.

ON KEY structures can be contained inside ON KEY structures. An ON KEY structure with no KEY commands is used to deactivate all KEY procedures.

Note: KEY commands in the ON KEY structures cannot be accessed while SharkBase waits for a keystroke in the MENU( function or the WAIT command.

The following is a trivial but complete program using an ON KEY structures to edit a file while READ is being executed on a TEXT screen:

USE test
WINDOW
CLS
dum1='1234'
dum2='ABCD'
ON key
   KEY F10 EDIT
   SAVE gets to test
   SAVE screen to test
   EDIT
   dum1='2468'
   RESTORE screen from test
   RESTORE gets   from test
ENDON
TEXT
    @dum1
    @dum2
 TEST SCREEN LINE ....................0
 TEST SCREEN LINE ....................1
ENDTEXT
DO while t
   READ
ENDDO

Here is a more complex example in which an ON KEY structure is used to add members to a data file while:

**  DEMO3.PRG
SET talk off       ;suppress messages
SET function off   ;we want the raw function keys - not the pre-loaded
messages.
:company="United Widgets, Inc."
USE#1 order index order
USE#2 members index cust_no
SET relation on cust:no to 2
ON escape
   PERFORM shutdown                ;turns on function keys and cancels
ENDON
WINDOW 0,23
ON KEY
KEY F5 'NEW CUST'
   SAVE gets TO temp
   SAVE screen TO temp
   WINDOW 0,23
   SELECT 2                      ;work on second file
   APPEND blank                  ;add new member record
   EDIT                          ;fill it in
   SELECT 1                      ;back to main file
   REPLACE CUST:NO WITH CUST_NO#2;transfer new member number to current order
   RESTORE screen temp
   RESTORE gets   temp
ENDON
IF :color<>7                     ;test for color monitor
   SET color to 31               ;white on blue
ENDIF
COLOR :color,0,0,23,79,177       ;fill screen with pattern
* 177 is a shaded fill character.
DO WHILE t                       ;put main menu in an infinite loop
   ERASE
   WINDOW 6,18,19,62 double      ;declare space for menu text
   mode='?'
   ERASE                         ;fills window with blanks
   SELECT 1
   TEXT
          Edit/Browse Demonstation

     0. Exit SharkBase And return to DOS.
     1. Edit Last Order.
     2. Edit New Order.
     3. Exit program - stay in Shark.
   ENDTEXT
   CURSOR 12,26 ; positions menu cursor over 1st character of 1st choice
* Note: KEY commands in the ON KEY structures cannot be accessed while
* SharkBase waits for a keystroke in the MENU( function or the WAIT command
   selection=menu(3,36); six choices menu bar width 36
   DO CASE
   CASE selection=0
      QUIT
   CASE selection=1
      GOTO bottom
      PERFORM order_edit
   CASE selection=2
      APPEND blank
      PERFORM order_edit
   CASE selection=3
      PERFORM shutdown
   ENDCASE
ENDDO
*
PROCEDURE shutdown
   WINDOW
   ON KEY
   ENDON
   SET function on
   CANCEL
ENDPROCEDURE shutdown
*
PROCEDURE order_edit
   WINDOW 0,23
   ERASE
   WINDOW 6,12,19,68
   TEXT orders
   ON field
   FIELD cust:no
      FIND#2 &cust:no#1
      IF lname#2=' '         ;member number not found in MEMBERS file
         SAVE gets to ord    ;saves get table to file ORD.GET
         SCREEN 1,2          ;save current screen to internal screen buffer
         WINDOW 0,23
         SELECT 2            ;work on members file
         NEAR#2 &cust:no#1   ;position as close as possible to right member
         BROWSE              ;give user chance to select correct member
         SELECT 1            ;back to main file
         REPLACE cust:no#1 with cust_no#2   ;transfer selected member number
         SCREEN 2,1          ;restore EDIT screen
         RESTORE gets from ord
      ENDIF
   ENDON
   EDIT OFF
   WINDOW 0,23
ENDPROCEDURE order_edit
*
*                          *** end of DEMO3.PRG ***

OTHERWISE

Introduce the optional clause in a DO CASE program structure.

OTHERWISE

In a DO CASE program structure, if no condition is true, Shark executes the program segment following the OTHERWISE command, if any. Only one OTHERWISE command is permitted within any DO CASE structure.

Example:

DO CASE
CASE CHOICE = 1
(some code to do something)
CASE CHOICE = 2
(some code)
CASE CHOICE = 3
(some code)
OTHERWISE
CANCEL
ENDCASE

See more information under DO CASE.

OVERWRITE TO

Copy the fields from a record in one data file directly into the current record of another data file.

 OVERWRITE TO <filenum>

 <filenum>   any number of the data file containing the record to
               be overwritten

The OVERWRITE TO command is primarily used to implement transaction processing and to avoid lengthy record locks while records are being edited in a network environment. Its companion command is APPEND TO.

The technique in both cases is essentially the same, utilizing a main, indexed file and a small, unindexed personal file for each operator.

The operator edits only in the personal file, adding records as required and verifying that everything is correct before moving the data back into the main file. If the records already exist in the main file, OVERWRITE TO is used to put the corrected records back where they came from; if new records were appended to the personal file, APPEND TO is used to add them to the end of the main file.

The two files do not need to have the same structures. Any fields which do not exist in both files will be unaffected; any that are smaller in one than the other create risks of losing some data due to string truncation or numeric overflow.

Executing OVERWRITE TO is much faster than a long series of REPLACE commands.

Example in a program with SET NETWORK ON (Shark Network Edition only):

USE customer INDEX custnum,custname SHARE
USE#2 personal
SET FUNCTION OFF
DO WHILE t
   SET SAVE OFF
   EDIT TEXT customer      ;use formatted EDIT
   IF usedby<>0
      WINDOW 20,30,22,75 DOUBLE   ;pop up a window for message
      recnum=RECNO(1)
      TEXT
.. recnum,'999,999'
.. usedby,999
    Record &recnum is in use by user &usedby

    Press any key to skip to next record...
      ENDTEXT
      junk=INKEY()               ;wait to keystroke
      SKIP
      LOOP
   ENDIF
   IF :key=324                   ;F10 means edit this record
      REPLACE usedby with :USER  ;mark record as in use by you
      OVERWRITE TO 2             ;then move into personal file
      SELECT 2                   ;select personal file
      SET SAVE ON                ;allow changes to be saved
      CLS                        ;clear the screen
      TEXT custedit              ;with "CHANGES PERMITTED" message
      READ
      WINDOW 20,30,22,75 DOUBLE  ;pop up a window for confirmation
      ans='No '
      recnum=RECNO(1)
      TEXT
.. recnum,'999,999'
..,ans,!xx
    Changes may have been made to record #recnum

         Save all changes (Yes/No)  @ans
      ENDTEXT
      IF ans='Y'
         OVERWRITE to 1
      ENDIF
      REPLACE usedby with 0      ;free the record for other users
   ENDIF
ENDDO

PACK

Remove deleted records from the selected file.

 PACK [TRUNCATE]

Option:

 TRUNCATE   reduce the DOS size of the file

This command removes records that have been marked for deletion by the DELETE command or the Ctrl-U of the EDIT and BROWSE commands.

All the index files in use are automatically reindexed after PACK. (See INDEX and REINDEX.)

Make sure you have a back up copy of the file before packing it. If PACK is interrupted, the file may be corrupt or contain duplicate records.

PACK does not release disk space unless the TRUNCATE option is used. If a file frequently gets large, has many records deleted and then grows again, it may be more efficient to PACK without TRUNCATE, so that DOS is not constantly adding disk clusters and recovering them again.

On a network with SET NETWORK ON in Shark Network Edition, attempting to PACK or create an index while another user is accessing the data file or an index file with the same name as any of the current indexes will cause a LOCK error. Always LOCK the data file before attempting to PACK.

Examples:

1>USE employee
1>GO 2
1>DELETE
      1 DELETE(S)
1>LIST name
      1  Marek
      2 *Balzer
      3  Steiner
      4  Rayme
      5  Poyner
      6  Wilson
1>PACK
      5 TOTAL PACKED
1>LIST name
      1  Marek
      2  Steiner
      3  Rayme
      4  Poyner
      5  Wilson

PERFORM

Execute a procedure.

 PERFORM <procedure>

 <procedure>      the name of the procedure

The command PERFORM is used to execute a procedure, <procedure>, defined in the current program; <procedure> cannot be a macro. The procedure is defined with the PROCEDURE command (see PROCEDURE).

The procedure is compiled where it is first called with PERFORM. If the procedure makes references to fields, the structure and order of the files in use must be the same any time the procedure is used. The same comment also applies to memory variables. Normally, procedures perform tasks that are independent of the environment (files in use and memory variables) or they are always invoked in the same environment.

If you need the same procedure in different environments, write the procedure as a separate program, and invoke it as a subroutine with the DO command. See the command DO.

Performing procedures is a very fast way of executing the same program segment from many places in the program. The procedures themselves must be at the end of the program.

Example:

PERFORM header
DO WHILE .NOT. EOF
   ...
   line=line+1
   IF line>55
     PERF header
   ENDIF
ENDDO
CHAIN menu
*
PROCEDURE header
   TEXT
&:DATE                             &:COMPANY                Page &page
                                 Sales Journal
Date    Invoice #  Description                     Units     Dollars
   ENDTEXT
   line=6
ENDPROCEDURE

POST

Post the FROM (transaction) file to the POSTING file (selected file with index).

POST ON <str exp> FROM <file> [FIELDS ] [<scope>]
      [FOR <cond>

 <str exp>   the expression that is the key for finding the records
                  in the FROM file
 <file>      the FROM file

Options:

 FIELDS <mixed field list>  the fields to be totalled in the
                            FROM file and added to the fields
                            in the POSTING file (the selected file);
                            <field> WITH <num exp> can add an expression
 <scope>               selection restricted by scope
                            (default scope: ALL)
 FOR <cond>            selection restricted by <cond>

The selected file, called the POSTING file, must be indexed by <str exp>, an expression formed from fields of the FROM file, called the FROM file, and constants and memory variables.

This procedure takes all the appropriate records (that is, the first record satisfying the <cond> and within the scope) of the FROM file, one at a time. It picks the first appropriate record, and evaluates <str exp> in the FROM file. Next it finds the matching record in the POSTING file. If the find is not successful, an error message POST ERROR" is sent.

If the find is successful, the procedure posts. Posting consists of one of two actions, depending on whether a field name is listed alone in the mixed field list, or if a field name has a WITH clause attached.

1. If the field is named alone, the value of that field in the FROM file is added to the value already in the POSTING file.; that is, it adds the fields in the <field list> of the current record of the FROM file to the fields of the same name in the current record of the POSTING file.

2. In a mixed field list, the clause <field> WITH <num exp> allows adding any numeric expression <field> to the field in the POSTING file. <num exp> is formed using the fields of the FROM file, and optionally fields from other files (including the POSTING file), variables, and constants.

If a find is unsuccessful and SET ADD ON, a record will be appended to the POSTING file, the non-numeric fields of the POSTING file record will be replaced by the matching fields in the FROM file record, and, finally, the procedure posts as above.

The procedure continues with the next appropriate record of the FROM file.

If there is no FIELDS clause, POST simply checks whether there is a record in the POSTING file for each value of <str exp> in the FROM file. This is valuable to check whether every record in the FROM file has a matching record in the POSTING file without changing any fields.

If SET PRINT OFF (the default), the error messages appear on the screen; otherwise, they are echoed to (printed on) the printer (or to the alternate text file, if SET ALTERNATE ON).

Deleted records are not posted, irrespective of SET DELETED.

Important programming note: The POST command automatically opens the FROM file in its internal work area; if the FROM file is already open in another work area, the compiler will assume it is closed when the POST command is passed during execution, even if that command is in an IF, CASE or other structure module that is not executed!

Therefore, if there is any reference to the FROM file later in the program, open the file in the proper work area again immediately after the POST command. If it is not actually needed after the POST is executed (e.g., the program exits after the POST), open it with the COMPILE keyword. Example:

USE#4 invoices COMPILE

See also the related commands: TOTAL and UPDATE.

Example:

Use the data files SALESMEN and ORDER (see Appendix), to record the amount of merchandise sold.

1>SET TALK ON
1>USE salesmen
1>INDEX ON slsman:no TO salesmen
      2 RECORDS IN TOTAL INDEXED
1>POST ON slsman:no FROM order FIELDS amount FROM order
                               2 ** POST ERROR ** 4
      5 POST(S)
1>LIST
      1  1   Smith           John              4386.00
      2  5   Willson         Tom              14679.50

The error message POST ERROR indicates that in the ORDER file there is a record (number 2) with a salesman code ("4") not found in the SALESMEN file.

Note that the amount for Smith is 2709.00 (the amount that was in the SALESMEN file) +1677.00 (the amount in ORDER record 5).

The amount for Willson is 12089.00 (the amount that was in the SALESMEN file) +597.50 (the amount in order 1) +559.00 (the amount in order 3) +1434.00 (the amount in order 4).

Of course, the most typical example of the use of the command POST is posting to a general ledger (the POSTING file) from a journal (the transaction file).

PROCEDURE

Procedure (subroutine) definition.

 PROCEDURE <procedure>

 <procedure>   the name of the procedure

The PROCEDURE command indicates the start of a procedure definition, the ENDPROCEDURE command indicates the end of the procedure:

PROCEDURE <procedure>
<program segment>
ENDPROCEDURE

Procedures should be used for all Shark program segments that are used more than once in a program. However, if the procedure makes references to fields, the structure and order of the files in use must be the same any time the procedure is used. The same comment also applies to memory variables. Normally, procedures perform tasks that are independent of the environment (files in use and memory variables) or they are always invoked in the same environment.

If the whole program will not fit in memory, then replace the procedures by subroutines invoked by the DO command. (See CHAIN, PERFORM, and PROCEDURE.)

The procedure name, <procedure>, follows the same rules as variable names (see Section 2); <procedure> cannot be a macro. Procedures must be placed at the end of the program. A procedure can perform other procedures.

A procedure is compiled at the first PERFORM invoking it. (See Example 1 in Appendix A)

Hint: If the same procedure must be used in more than one subroutine, add a digit (1, 2, 3, etc.) to the name in the various subroutines. Example: if a procedure called BELL is needed in main program ENTER and subroutines ENTER1 and ENTER2, call it BELL, BELL1 and BELL2 in the three program modules respectively.

Examples:

1. A simple label printing procedure.

INPUT 'Enter the number of labels to print ' TO nlabel
REPEAT nlabel TIMES
   PERFORM label
   SKIP
ENDREPEAT
*
PROCEDURE label  ; prints 5 lines of data and 4 blank lines
   ? name        ; on standard labels one across
   ? add:1
   ? add:2
   ? add:3
   ? postal
   ?
   ?
   ?
   ?
ENDPROCEDURE   ; end of label printing

2. A procedure to clear screen, make border, set standard heading, and create reverse video black for menu choices. This procedure would be called before any menu display in the program.

PROCEDURE MENUSCREEN
   ERASE
   WINDOW 2,1,23,77 DOUBLE
   COLOR 112, 6, 4, 22, 74
   @ 3,0 SAY CEN(:COMPANY, 80)
   @ 5,0 SAY CEN('Enter your choice below:',80)
ENDPROCEDURE menuscreen

PSTRING

The PSTRING command sends a printer-control string to the printer without itself printing. It is used for styling printer fonts in Shark documents.

PSTRING =  a list of characters, in a special format, to be output to the printer or the printer file

An enormous variety of printers emerged under MS-DOS, with their often-obtuse control languages such as HP's PCL (printer control language). Programming languages like Shark needed to pass these instructions embedded in text output in order to control attached printers.

SharkBase offers a limited set of tools to specify characters in your printouts.

The setup string is a list of character descriptors, separated by commas. Each descriptor may be a number (the ASCII value of a character), a hex number followed by an "h" (the hex value of a character), or any alpha character.

Examples:

PSTR 27,W,1Bh,41h,3h
     A variable or field containing the setup string may be used in a macro:
ps='27,W,1Bh,41h,3h'
PSTRING &ps

A group of HP's PCL instructions looks like this:

27,"(8U",27,"(sp12h5vs3b8T"
27,"(8U",27,"(sp10h12v3T"
27,"(8U",27,"(sp10h12v3T"
27,"(8U",27,"(sp10h12v0s3b3T"
27,"(8U",27,"(sp10h12v3T"
27,"(8U",27,"(s1p14v0s0b4T"
27,"(8U",27,"(sp10h12v3T"
27,"(8U",27,"(sp10h12v3T"
27,"(8U",27,"(sp10h12v3T"
27,"E"
12

These macros can be stored in a text file which is read by a Shark program along with a text document that is to be printed.

In order to be fed properly to the printer, the macros need to be parsed by a Shark program and stored in memory at the time of printing. They are read into memory with a small program such as this:

* read in printer data macros from PRINTER.DTA ...
OK=ROPEN("PRINTER.DTA",2); opens the printer PCL data file
IF .NOT. OK
RING
? "Printer not installed!"
WAIT
CANCEL
ELSE
OK=READ(_PNORM,2)<-- normal text
OK=READ(_PCOMP,2)<-- compressed
OK=READ(_PCOFF,2)<-- compressed off
OK=READ(_PBOLD,2)<-- bold
OK=READ(_PBOFF,2)<-- bold off
OK=READ(_PWIDE,2)<-- wide
OK=READ(_PWOFF,2)<-- wide off
OK=READ(_PRSET,2)<-- reset printer
OK=READ(_PFF,2)<--  form feed (not used in vDOS/Windows)
ENDIF
*release printer
OK=CLOSE(2)

vDOS prints Shark text output without PCL codes, but the printout will be limited to your single basic default font, likely the Windows "Courier" font. PSTRING allows some limited management of your default font, mainly character weight (light, bold, etc).

QUIT

Leave Shark.

 QUIT 


 Option:
     a value passed to DOS, which allows batch files
                 to control their execution with the
                 IF ERRORLEVEL command

The command QUIT exits from Shark. It closes all the files and gives you the prompt of the operating system.

If Shark is running unattended in a batch file, a program can pass an "errorlevel" to DOS indicating if some condition was encountered during execution. For instance, if there is an error reading a data file, you can QUIT to DOS with an errorlevel of 1, which the batch file can detect so that the tape backup is not run. The command in this case wound be QUIT 1. Consult your DOS reference manual for the IF ERRORLEVEL batch program command.

Example:

DO CASE
   CASE ans='0'
      QUIT
   CASE ans='2'
      CHAIN prog1
   ...
   OTHERWISE
      QUIT 1        ;tells DOS an error encountered by Shark
ENDCASE

READ

Enter full-screen editing and data entry specified by the @ GET and TEXT commands.

 READ

The READ command activates the input aspect of the @ GET commands (including the @ and % macros in a TEXT). The @ GET command displays the variable at the specified location and format. The READ command puts the screen in full-screen editing mode with the current values of all fields and memory variables shown, and the new values of all the variables in the @ GET (and the @ and % macros in TEXT) commands can be entered.

If the READ changes any key of a record in an index file in use, then the index files are updated.

The READ command clears all the pending GET commands.

For the use of the editing keys in full-screen editing.

Example:

@ SAY 20,0 'Enter your choice: ' GET ans
READ

is the same as:

ACCEPT 'Enter your choice: ' TO ans

except that @ SAY does not create ANS, ACCEPT does; @ SAY directs the query to a specific location on the screen.

Of course, the real use of the @ SAY and READ commands is to display more than one field for input.

RECALL

Undelete selected deleted records in the selected file.

RECALL <scope> [FOR <cond>]

Options:

<scope>       select by scope (default scope: current record)
 FOR <cond>    select by condition

Records are flagged as DELETED either with Ctrl-U in BROWSE, or EDIT, or with the DELETE command (see the commands BROWSE, DELETE, and EDIT). The command RECALL reverses the DELETED flag.

The command PACK physically removes all records flagged for deletion. After a PACK, the records can no longer be recalled.

Note that if SET DELETE ON, then RECALL will work only on a deleted record only if it is also the current record. Normally SET DELETE OFF before using RECALL.

Examples:

1>USE employee
1>GO 2
1>DELETE
      1 DELETE(S)
1>LIST name
      1  Marek
      2 *Steiner
      3  Rayme
      4  Poyner
      5  Poyner
      6  Wilson
1>GO 2
1>RECALL
      1 RECALL(S)            ;record 2 was recalled
1>RECALL                     ;the default is the current record
      0 RECALL(S)
1>DELETE RECORD 2
      1 DELETE(S)
1>DELETE RECORD 4
      1 DELETE(S)
1>DELETE RECORD 6
      1 DELETE(S)
1>RECALL ALL
      3 RECALL(S)            Note: Records 2, 4, 6 are recalled
1>GO TOP
1>DELETE
      1 DELETE(S)
1>DELETE RECORD 3
      1 DELETE(S)
1>DELETE RECORD 5
      1 DELETE(S)
1>LIST name
      1 *Marek
      2  Steiner
      3 *Rayme
      4  Poyner
      5 *Poyner
      6  Wilson
1>GO TOP
1>RECALL NEXT 4
      2 RECALL(S)            Note: Records 1 and 3 are recalled

REINDEX

Reindex all index files in use.

REINDEX [FOR <cond>]

Option:

FOR <cond>    select by condition

This command takes all the index files currently in use for the selected data file, and rebuilds each index file.

In Conversational Shark, and in programs with SET TALK ON, REINDEX will output the key, the progress of the indexing procedure, showing the completion of each 100 records, and the total number of records indexed.

A FOR clause can be used to limit the records in the index(es) to those for which <cond> is true. See INDEX.

On a network with SET NETWORK ON in Shark Network Edition, attempting to REINDEX while another user is accessing an index file with the same name as one of the current file's indexes will cause a LOCK error.

Examples:

The commands:

1>USE employee
1>INDEX on name+fname TO employee
accomplish the same as the following:
1>USE employee INDEX employee
1>REINDEX

Note that for REINDEX, you do not have to specify the key (name+fname) or the name of the index file (EMPLOYEE.NDX).

In a program:

USE employee INDEX employee,empl1,empl2
REINDEX

will rebuild three index files: EMPLOYEE.NDX,EMPL1.NDX,EMPL2.NDX.

The following uses a FOR clause to limit the index to current employee only, based on date of termination being blank:

USE employee INDEX employee,empl1,empl2
REINDEX FOR terminated=' '

RELEASE

Erase memory variables.

RELEASE <memvar list>/EXCEPT <memvar list>/ALL]

Options:

<memvar list>          the memory variables to be released,
                            separated by commas
EXCEPT <memvar list>   the memory variables not to be released, separated by commas
ALL                         release ALL

The command RELEASE erases memory variables; it releases memory space for new memory variables. You can make a list of the memory variables you want removed, use the parameter ALL to remove them all, or use the parameter EXCEPT <memvar list> to remove all except those on the list. RELEASE ALL may cripple your application if your application loops back to the beginning (the variables required will all be gone).

This command should be used in programs only with the utmost care. Compiled programs set pointers to memory variables. If the memory variables are released, the release must be absolute, not dependent on some conditions.

Since 128 memory variables can be used at any one time, and any number of them may be matrix variables, the use of RELEASE during a program may require careful debugging afterward! When programs are chained, Shark will do a CLEAR, which includes a RELEASE ALL.

RELEASE does not affect the values of the function keys and the system variables.

Examples:

1. In conversational Shark:

1>LIST MEMO

Name          Type    Width    Contents
** Total **  0  variables, 0  bytes
1>name='David'
1>age='11'
1>LIST MEMO

Name          Type    Width    Contents
NAME            C       5      David
AGE             C       2      11
** Total **  2  variables, 7  bytes
1>RELEASE age
1>LIST MEMO

Name          Type    Width    Contents
NAME            C       5      David
** Total **  1  variables, 5  bytes
1>RELEASE ;RELEASE by itself does nothing
1>LIST MEMO

Name          Type    Width    Contents
NAME            C       5      David
** Total **  1  variables, 5  bytes
1>age=11
1>LIST MEMO

Name          Type    Width    Contents
NAME            C       5      David
AGE             N       8      11
** Total **  2  variables, 13  bytes
1>RELEASE ALL
1>LIST MEMO

Name          Type    Width    Contents
** Total **  0  variables, 0  bytes

2. In programming, from a program you might DO a number of subroutines; each uses a number of memory variables, most of which are unique to it, but which in total exceed the 128 memory variable limit. In this case, decide which variables needed to be retained, and use the RELEASE EXCEPT after each subroutine as follows:

@ 20,30 SAY ' Enter your choice: ' GET choice PICTURE'!'
DO CASE choice                     ;menu choices
   CASE choice='A'
      DO proga
      RELEASE EXCEPT choice,cust,due,amount
   CASE choice='B'
      DO progb
      RELEASE EXCEPT choice,cust,due,amount
   CASE choice='C'
      DO progc
      RELEASE EXCEPT choice,cust,due,amount
   ENDCASE
ENDDO                              ;menu choices

REMARK

Display message on screen or printer.c

REMARK ['']

Option:

'<file>'       the text line to be displayed 

Same as the command ?. <file> may be an expression list.

RENAME

Rename a file.

RENAME <file> TO <new file>

 <file>        the file name to be changed (default extension DBF)
 <new file>    the new name for the file   (default extension DBF)

This command is similar to the RENAME command of the operating system: a file is renamed. No wild card characters are allowed.

If the file name has no extension, the extension DBF is assumed. (Do not rename a data or index file to a name starting with the letters COMP; Shark is unable to open such a file.)

Examples:

1>RENAME employee TO empl
Renames EMPLOYEE.DBF to EMPL.DBF
1>RENAME employee.dbf TO employee.xyz

RENAME FIELD

Rename a field in a data file.

 RENAME FIELD <field> TO <new fieldname>

 <field>          the field name to be changed
 <new fieldname>  the new name for the field

This command allows you to change the name of a field in a data file without doing a MODIFY, which potentially endangers the file and removes all deleted records, often necessitating a REINDEX.

Examples:

1>RENAME FIELD employee TO empl

Renames the field EMPLOYEE to EMPL in the current data file.

1>RENAME#3 FIELD cust TO customer

Caution: All programs, report forms and index files that reference the old field name must be revised before they will work properly after a field is renamed.

REPEAT

Repeat program segment a specified number of times.

REPEAT <num exp> TIMES [VARYING <num var>]

<num exp> a numeric expression; repeat the loop this many times

Option:

 VARYING <num var>   loop counter

The REPEAT command introduces the program structure:

REPEAT <num exp> TIMES [VARYING <num var>]
   <program segment>
ENDREPEAT

The program lines in the <program segment> are repeated <num exp> times. The end of the program segment is indicated by ENDREPEAT.

The optional VARYING clause is used to vary a memory variable from 1 to <num exp>; at the start of the first loop, <num var> is initialized as 1; <num var> is incremented by 1 each time the top of the loop is reached.

This command is especially useful to manipulate matrix variables.

Repeats can be nested.

The BREAK command is used in a REPEAT loop to exit at the bottom of the loop. If there are nested loops, the exit is at the bottom of the innermost loop then being executed.

The Shark keywords: TIMES and VARYING should not be in macros. <num var> cannot be a matrix variable.

Note that, if <program segment> contains commands that move the current record pointer (for instance, a SKIP command), REPEAT does not terminate if EOF becomes true. Thus displaying a record and skipping in a file with 50 records, using REPEAT 100 TIMES, will display the last record in the file 51 times. DO WHILE .NOT. EOF is the better construction for such a task.

When editing with the internal Shark programming editor (see WRITE command), Alt-F reformats the file with all structures properly indented, making it easy to see unbalanced structures.

Examples:

SET WIDTH TO 40
DIM NUM num[10]
REPEAT 10 TIMES VARYING count
   num[count]=POW(2,count)
ENDREPEAT
? num

This displays:

      2.00       4.00       8.00
     16.00      32.00      64.00
    128.00     256.00     512.00
   1024.00

REPLACE

Replace field(s) in the selected data file.

 REPLACE <scope> <field1> WITH <exp1> [,<field2> WITH <exp2> ... ]
      [FOR <cond>]

Options:

 <scope>                 select by scope
                            (default scope: current record)
 <field> WITH <exp>...   list fields and expressions for replacement
 FOR <cond>              select by condition

This command is used for changing some records in the selected data file. The number of <field> WITH <exp> is only limited by the length of a command line (254 characters).

The scope ALL can be used to change all the records in the data file. This could be dangerous. Consider backing up your data file before you use this command.

This command is very useful, especially in conjunction with SET RELATION TO, so that the fields from which <exp> is formed may come from a number of data files.

Examples:

1>USE employee
1>REPLACE name WITH 'Mareck'
1>? name
Mareck
1>REPLACE ALL salary WITH salary*1.05
      6 REPLACE(S)
1>LIST name,salary
      1  Mareck           27090.00
      2  Steiner          37569.00
      3  Rayme            83065.50
      4  Poyner            9145.50
      5  Poyner            9145.50
      6  Wilson           35563.50
1>GO TOP
1>REPLACE NEXT 4 salary WITH salary*1.06 FOR name < 'P'
      1 REPLACE(S)
1>USE order
1>USE#2 clothing
1>SET RELATION ON inven:no TO 2
1>REPLACE price WITH price#2

To replace more than one field:

REPLACE q1 WITH q1-q1#2,q2 WITH q2-q2#2,q3 WITH q3-q3#2

REPORT GENERATOR

The report generator.

REPORT [FORM] 
<scope> [FOR <cond>] the name of the form file

Options:

 FOR <cond>  select by condition
 <scope>  select by scope (default:ALL)

The command REPORT is a very versatile report generator. With a minimum of effort the user can generate a great variety of columnar reports. The command takes care of the width of the report, the arrangement of the date, page numbering, title(s), the columns, the data in the columns, headings, subtotals (two levels), totals, and many other parameters.

This command reports on the file(s) in use according to the format in the report form file . The form file can be created with the Shark editor (WRITE) or with any word processor; the default extension is FRM.

Shark computes the necessary width as the minimum required to accommodate the title(s), headings, the expression list, and the company name.

The report is automatically centered over 80, 112, or 132 characters wide, whichever is equal to or greater than the width of the report body. The SET WIDTH TO command also affects the heading, but not the width of the body.

The following keywords can be used in a report form file:

[NOTE: Printed output when using a DOS emulator may have limited options. Most emulators are limited to a single font with limited styles.]

COMPRESS                               Sends code 15 to the printer for compressed
                                                  printing on Epson and IBM Proprinter
                                                  printers, sends code 18 after completion
                                                  of the report to restore normal-width
                                                  mode. For non-compatible printers, use SETUP.

DOUBLE                                     Prints double spaced lines.
EJECT                                         Ejects a page after each subtotal.
FIELDS - <exp1>,<exp2>,...         The expressions for the columns of the
                                                   report.
FILE - <file> [INDEX <index file>]   Opens the data file <file> and, optionally,
                                                  the index file.
HEADING - string1,string2,...        The headings for the expressions in the
                                                   report.
INDEX - <exp> TO  [FOR <cond>]
                                                  Indexes on the expression <exp> to the
                                                  specified file the last data file opened
                                                  with the FILE keyword; a FOR clause is
                                                  permitted (see INDEX).
LENGTH - <num exp>            Number of printed lines per page.
MESSAGE - <str exp>           Introduces the message to be displayed for
                                                   a subtotaled group (2 allowed).
NODETAIL                                   Shows only the totals and subtotals. Should
                                                  not be used without SUBTOTAL keyword.
PICTURE -               Which expressions (in the FIELDS line) are
                                                  to be totaled.
PRINT                                        Sends the report to the printer.

[NOTE: Printed output when using a DOS emulator may have limited options. Most emulators are limited to a single font with limited styles.]

RELATION - <exp> TO <file number>  Sets a relation between file 1 and the file  <file number>
                                    .
SELECT - <cond>                  Selects the records by condition <cond>.
SETUP -                 A list of control codes to be sent to the
                                                  printer before beginning page 1 (do not
                                                  use without PRINT or SPOOL keywords).
SPOOL -                    Sends the report to the file 
                                                 (PRINT must not be used).
SUBTOTAL - <exp>                     Subtotals be printed when the expression
                                                 <exp> changes (2 allowed).
TITLE - string or <str exp>      The title of the report (2 allowed).

Some of these keywords can be used more than once. More detailed explanation follows in the subsection on keywords.

The REPORT command is influenced by the commands previously given, such as USE, INDEX, SET PRINT ON. Most of these can also be done from within the report form file.

COMMANDS INFLUENCING REPORT. The REPORT command works on the selected file (if any). So

1>SELECT 3
3>REPORT salary

means: report on file 3 using the report form file SALARY.FRM. If no file is in use as file 3, the report form file will have to specify (with the FILE keyword) the data file(s) to use.

Similarly, specifying the index file(s) to use with the data file(s) and reindexing can be done before the REPORT command is given.

Here is a simple example:

1>SELECT 2
2>USE clients
2>INDEX ON newdate TO newdate
2>REPORT call

The report can be directed to the screen, the printer, or to a text file.

To the printer:

2>SET PRINT ON

To a text file (TEMP.TXT):

2>SPOOL temp
2>SET PRINT ON
2>REPORT call
2>SET PRINT OFF
2>SPOOL

REPORT can use files related to each other:

1>SELECT 1
1>USE order INDEX order
1>USE#2 client INDEX client
1>SET RELATION ON client TO 2
1>REPORT order

REPORT can use linked files:

1>SELECT 1
1>USE order index order
1>USE#2 history1
1>USE#3 history2
1>SET LINK TO 2
1>SET#2 LINK TO 3
1>REPORT order1

It may be necessary to send control characters to the printer to set up the desired printing mode. (See "PSTRING")

Example:

1>SET PRINT ON
1>?? CHR(27)+CHR(121)+CHR(128)

The system variables :COMPANY, :TITLE, and :DATE influence the report. The company name in :COMPANY appears centered in the second line of the report. The text in :TITLE becomes the title of the report unless the report form file specifies otherwise (with the keyword TITLE). The date on the first line of the report comes from :DATE.

The three system variables may be changed before REPORT.

Much of what can be accomplished by setting the environment of REPORT before the command is given, can also be done in the report format file. There are some exceptions: for instance, since SPOOL adds to the top of an existing file with the same name as the spool file, you may want to delete the existing file before doing the report, or alternately using the SPOOL command outside the report and the keyword PRINT inside the report. You may also want to set page depth with SET LENGTH TO, the number of character over which the heading will be centered with SET WIDTH TO, the left margin with SET MARGIN TO, etc. See also SET EJECT.

THE FORM OF THE REPORT COMMAND. The selection criteria can be placed in the REPORT command and/or in the report form file. If the REPORT command contains a FOR clause, and the report form file has a SELECT line, then the FOR clause of the REPORT command overrules the SELECT line of the report form file.

You may restrict the range of records in the report by the LIMIT command or a scope; both must be invoked outside the REPORT form. The WHILE <cond> form of the scope may be very useful when reporting on a very big file. As an example,

1>USE orders INDEX clients
In the current record the field CLIENT contains A234.  To report on all the
orders by this client with part number > 1200:
1>REPORT ship WHILE client='A234' FOR VAL(part:num)>1200

or

1>LIMIT client
1>REPORT ship FOR VAL(part:num)>1200
1>LIMIT

Note that without either the scope or the LIMIT command, processing would stop only after all the records of the file had been processed.

REPORT FORM FILE: In a report form file, the first word of a line has to be a keyword, followed by any modifiers separated from the keyword by a hyphen (-). There are currently 18 keywords.

Only the FIELDS line is required; all the others are optional. Some keywords can occur more than once.

The lines in the report form file can be separated by any number of blank lines to increase readability.

An asterisk * can be put at the front a line to comment out (temporarily) that line.

The lines can appear in just about any order. The INDEX keyword must appear after the FILE keyword, and the MESSAGE keyword must appear after the SUBTOTAL keyword.

Keywords that take no arguments are described above. Details on others are available by pressing :

RESTORE

Restore memory variables, screen or Get Table from file.

 RESTORE [MEMORY] FROM <file> [ADDITIVE]
 RESTORE [SCREEN/GETS] FROM <file>

 <file>             name of source file on disk

For First Form only:

 MEMORY             restore memory variables from disk. If no
                    option is specified MEMORY is the default

For Second Form only:

 SCREEN             restore a screen from disk
 GETS               restore a Get Table from disk

Option:

 ADDITIVE           add new variables, update old ones (permitted
                    only with first form of command)

This command has two forms, used to restore memory and system variables in the first case, and to restore screens or Get Tables in the second case.

Their usage is as follows:

The First Form is used for restoring the memory and system variables that had previously been saved by the SAVE TO command. This command erases all the variables that are currently in memory. (See the command SAVE TO.)

The ADDITIVE clause inhibits clearing of memory variables. It adds the memory variables from the file to the memory variable table. If a memory variable occurs both in the table and the file, its value gets updated from the file. With the ADDITIVE clause, the position of the existing variables in the memory variable table does not change, so pointers to them remain correct. It is recommended that RESTORE FROM be always used with the ADDITIVE clause.

In general, never use the ADDITIVE clause in Conversational SharkBase, and always use it in programs.

This command should be used with the utmost care. Compiled programs set pointers to memory variables. If the memory variables are restored, the restore must be absolute, not dependent on some conditions. (See Compiler)

When using compiled programs (the most common form of using Shark) the compiler doesn't know what variables are in a called MEM file at compile time. It only works with the variables that are known and declared in the CPL compiled program. The CPL won't see the contents of the MEM file because the CPL reads the MEM file when the CPL is run - that is AFTER, not BEFORE. Therefore the variable NAMES must be known to the CPL beforehand. The values can be filled in when the MEM file is read by the RESTORE command at run time. This is how it's done:

1. The CPL is made aware of the variables with the VARIABLES declaration at the top of the CPL program in this way:

VARIABLES name1, name2, price1, price2, etc 

2. Then, immediately following, the variables are read from the MEM file and the compiler matches them to the respective variable names in the VARIABLES list:

RESTORE MEMORY FROM memfile

Only those variables named in the VARIABLES list will be restored and run in the CPL. A bonus from using a VARIABLES declaration, is that it also sheds the un-named (unwanted?) variables, thereby cleaning up the workspace.

The default file extension is MEM.

Another method:

It's also possible to save and restore variables by storing them in a DBF data file, but this uses more programming work. The above VARIABLES list method is much simpler to implement.

Form Two is used for restoring screens and Get Tables that have been previously stored to disk with the SAVE command.

When restoring a screen from disk, the screen is restored to the current SCREEN, including colors, window coordinates and cursor position. In essence it works exactly like SCREEN 2,1 which moves the screen image from background screen 2 to the foreground screen 1.

To restore a screen and make it appear with one of the available screen effects, set 2 as the current screen, restore the screen from disk, set the screen to 1, and the execute the special effect (see example below).

The default file extension is SCR.

When restoring a Get Table from disk, any existing Get Table is overwritten; it is therefore not necessary to CLEAR GETS first. This command restores not only the Get Table, but all formats and any ON FIELD structure as well.

The default file extension is GET.

NOTE: It is vitally important that the screen be restored BEFORE the Get Table, since part of the restoration process is to reverse the color of all input windows. Restoring the Get Table first will cause you to lose the proper screen colors.

Advanced technique: SAVE once, RESTORE many! The above discussion assumes that each time the Get Table is destroyed, it is SAVEd first and then RESTOREd. In actual fact, it is possible to save the Get Table and screen when they are first created, and restore each time it is needed. This is much faster and significantly improves performance.

Examples:

1. Memory

1>LIST MEMO

Name          Type    Width    Contents
NAME            C       5      David
AGE             N       8      11
** Total **  2  variables, 13  bytes
1>SAVE TO child
1>QUIT
C:\>SRI
1>RESTORE FROM child
1>LIST MEMO
Name          Type    Width    Contents
NAME            C       5      David
AGE             N       8      11
** Total **  2  variables, 13  bytes

2. Complete program using SAVE GETS and RESTORE GETS together with standard screen-swapping with the SCREEN command:

USE#1 members index members
WINDOW
ERASE
TEXT members
ON field
FIELD cust_no
   IF val(cust_no)<1000      ;test for legal record
      SAVE gets to ed        ;saves get table to file ED.GET
      SCREEN 1,2             ;save current screen to internal screen buffer
      BROWSE
      SCREEN 2,1             ;restore EDIT screen
      RESTORE gets from ed
   ENDIF
ENDON
EDIT off                     ;use 'painted' screen MEMBERS.TXT

3. Screens and Get Tables in program with CASE structure determining action based on key pressed to exit earlier READ

CASE :key=319    ;F5=browse

   SAVE GETS TO temp
   SAVE SCREEN TO temp
   CLEAR GETS
   BROWSE
   RESTORE SCREEN FROM temp
   RESTORE GETS FROM temp

4. Screens and Get Tables as above, except READ screen restored with special effect

CASE :key=319    ;F5=browse
   SAVE GETS TO temp
   SAVE SCREEN TO temp
   CLEAR GETS
   BROWSE
   SCREEN 2
   RESTORE SCREEN FROM temp
   RESTORE GETS FROM temp
   SCREEN 1
   SCREEN tear

RETURN

Return to the calling program.

RETURN

The RETURN command returns the current program to the program from which it was called with the DO command.

There may be any number of RETURN commands in a program. (See also the command DO.)

RING

Sound a beep on the computer speaker.

RING

1. In DOS systems, RING uses one of the sound effects from its effects library, and does not send anything to the screen.

2. When running Shark with an emulator, the emulator manages the sounds and RING will be dependent on the emulator's settings.

3. With the NOEFFECTS keyword in the SHARK.SET file), RING sends character 7 [chr(7)] (the ASCII bell character) to the screen at the current cursor position. If there is already a character in that position, it will be overwritten (erased). Without the NOEFFECTS keyword, chr(7) will produce a short beep tone useful for signalling errors or completion of a task.

See the SOUND command.

ROLL

Save and release SharkBase's memory area, release it, and execute a program that needs substantial amounts of memory; when that program is finished, resume SharkBase at same point.

ROLL 

<command line>  complete command to be passed to DOS command processor for execution; EXE or COM file name must be fully expanded, with drive, directory and extension specified

ROLL is one of several ways to run programs from within SharkBase. Other commands capable of this are RUN, which runs a program in DOS memory above SharkBase's high memory, and CALL, which allows users to run small assembly-language BIN files in a specially reserved BINSPACE in memory managed by SharkBase.

ROLL permits users to run any program of any type, using memory normally occupied by SharkBase. ROLL "rolls up" all of SharkBase's memory into a single DOS file, frees almost all of it to the program you want to run, and then restores SharkBase to its original state on completion.

The default name for the file (usually about 500K) is constructed using the name ROLLxxx.$$R where "xxx" is replaced by a string containing the value of :USER. The default is the current directory, but, like all SharkBase files, can be redirected using the FILES structure (see FILES . . . ENDFILES). If a ram disk is available and has sufficient free space, setting the PATH in the files STRUCTURE to the ram disk will yield impressive speed improvements.

Example in Files Structure:

*.$$R,F:\

Note that FILES only gets the path, not the file name.

If you ROLL to COMMAND.COM, SharkBase looks for it first in the current directory, and then where the DOS COMSPEC is set (see your DOS manual). If you ROLL to any other command program without giving a full pathname, SharkBase looks only in the current directory. It is most important that all pathnames and directories are properly set out.

If you have a dual boot system such as PC-MOS/DR-DOS/MS-DOS, you can rename the respective COMMAND.COM files so that they can co-exist in the same directory.

Examples:

DRDOSCMD.COM
MSDOSCMD.COM
PCMOSCMD.COM

A valuable feature of ROLL is the ability to pass commands to the child program through the keyboard buffer. The STUFF command fills or clears a special stuff buffer. Every time ROLL is executed, the contents (if any) of this buffer are passed to the child program, mimicking the way the user would enter the same commands directly from the keyboard.

See RUN and CALL commands, and STUFF command.

Examples:

ROLL C:\wordperf\wp.exe manual.doc
ROLL D:\lotus\123.exe project
ROLL C:\xywrite\xy.exe read.me
     Examples using STUFF:
STUFF FILE stuffinp.txt
ROLL c:\util\pe2.exe f:\wp\junk
STUFF STRING "name junk3",13,10,328,254
ROLL c:\util\pe2.exe f:\wp\junk
STUFF
ROLL c:\util\pe2.exe f:\wp\junk

ROLLing to BAT files.There may be times when you need to ROLL out to a batch file. This cannot be done directly, since BAT files can be executed only by COMMAND.COM.

But there is a complication in "shelling out" to DOS to run a BAT file, but this comes not from SharkBase but from COMMAND.COM itself. To execute a BAT from COMMMAND.COM when you are yourself executing COMMAND.COM from a program, you must tell COMMAND.COM that your command is coming.

You use the "/c" "switch" to introduce the command, and then everything else on the line is handled just as if it were being entered at the DOS prompt itself.

Example (to run a batch file):

1>ROLL command /c niteback                  ;NITEBACK.BAT is a batch file

This is the same as running

C:\NITEBACK.BAT

at the DOS prompt.

RUN

Execute DOS commands or run a program outside Shark.

RUN <command file>/<DOS command>

 <command file>   an EXE, COM or BAT file to be executed
 <DOS command>    an internal DOS command (COMMAND.COM must be
                       in the current directory or in the PATH

Provided your computer has sufficient memory available, the RUN command allows you to execute DOS commands and run small programs outside Shark without leaving Shark. For larger programs, the ROLL command is far superior and recommended, since it makes no demands on computer memory.

The amount of memory devoted to Shark is controlled by the MEMORY= command in the SHARK.SET file. The default is to use as much high memory as possible up to 128K. See MEMORY= and BINSPACE= commands.

Examples:

1>RUN chkdsk                  ;check current disk...CHKDSK must be
                              ;in current directory or path
1>RUN editor test             ;use an editor on file TEST...EDITOR
                              ;must be in current directory or path
1>RUN mode com1:2800,n,8,1    ;configure the COM1: port...MODE must be
                              ;in current directory or path

SAVE; also SAVE SCREEN, SAVE GETS

Save the memory variables, screen or Get Table to a file.

 SAVE [MEMORY] TO <file>
 SAVE [SCREEN/GETS] TO <file>

 <file>             name of destination file on disk

Options:

For first form only:

 MEMORY             save memory variables to disk. If no option is
                    specified MEMORY is the default
 

for second form only:

 SCREEN             save a screen to disk
 GETS               save a Get Table to disk
 

This command has two forms, used to save memory and system variables in the first case, and to save screens or Get Tables in the second case.

Their usage is as follows:

Form One is used for saving the current memory and system variables in a form that allows their restoration with the RESTORE FROM command. (See RESTORE.)

If no extension is given to the file name, the file will have extension MEM. If running under an emulator such as vDOS or DOSBox-X, Shark will save the MEM file according to your instructions, for example "\MEM\memfile.mem" as in the following example where it is saved as the file memfile.mem in the \MEM\ sub-directory:

Example:

1>SAVE TO \MEM\memfile.mem

Or:

1>SAVE MEMORY TO \MEM\memfile.mem

In either example, your memory file will appear in your Windows SHARK\MEM\ directory as:

<<SHARK>MEM
Name              Date            Type         Size
MEMFILE.MEM       2022-03-14      MEM File      1KB

Any subsequent save will overwrite a previously saved memory file

If no option, e.g.[SCREEN] or [GETS] is given, MEMORY is the default. That is, SAVE TO TEST (i.e. SAVE TO TEST.MEM) is equivalent to SAVE MEMORY TO TEST.

During debugging, it is often useful to save the memory variables to a file for later analysis.

Form Two is used for saving the current screen or the current Get Table to disk in a form that allows their later restoration with the RESTORE [SCREEN/GETS] FROM command.

In general, SAVE SCREEN should be used only if there is no available or convenient background screen position available.

SAVE GETS saves not only the Get Table, but all formats and any ON FIELD structure as well. SAVE GETS also executes CLEAR GETS. If you wish to save a get table for later use, but still continue using it, you will have to RESTORE GETS immediately.

Default extension for screens is ".SCR", and for Get Tables is ".GET".

NOTE: It is vitally important that the screen be saved AFTER the Get Table, since part of the storing process is to CLEAR GETS and un-reverse the color of all input windows. Saving the screen first will cause you to lose the proper screen colors.

Examples:

1. Memory

1>LIST MEMO

Name          Type    Width    Contents
NAME            C       5      David
AGE             N       8      11
** Total **  2  variables, 13  bytes
1>SAVE TO child
1>QUIT
C:\>SRI
1>RESTORE FROM child
1>LIST MEMO
Name          Type    Width    Contents
NAME            C       5      David
AGE             N       8      11
** Total **  2  variables, 13  bytes

2. Screens and Get Tables in program with CASE structure determining action based on key pressed to exit earlier READ

 
 CASE :key=319    ;F5=browse
   SAVE GETS TO temp
   SAVE SCREEN TO temp
   BROWSE
   RESTORE SCREEN FROM temp
   RESTORE GETS FROM temp

SCOPE [or LIMIT]

Limit the records available within the current master index to those matching all or part of the current records index key. A synonym for LIMIT command.

 SCOPE

Options:

 <num exp>     the number of characters in the key expression to to match
 <key exp>     the string expression to match in the current master index
 
  SCOPE <num exp> Example: SCOPE 5
  SCOPE <key exp> Example: SCOPE NAME
 

When the current file has an index, Shark can be made to treat the file as though it includes only those records matching the current record's key expression, or some leftmost part of it. When a SCOPE is in effect, no Shark command can access a record outside that limit.

You can most quickly implement this command by using the <num exp> option. The effect is to have Shark set the SCOPE to the leftmost <num exp> characters of the key expression of the master index. If <num exp> exceeds the length of the key, the effect is identical to setting the SCOPE to the entire index expression.

When SCOPE is used with no option, or when <num exp> is zero, the limit is deactivated.

Using SCOPE with <key exp> requires precision in its use to avoid problems that may become extremely serious. Note that the <key exp> expression must be the same as the master index key in use at the moment, or some LEFT( portion of it. Do not attempt to use an expression that does not meet this requirement. Example:

1>INDEX ON DI+TITLE TO BOOKLIST
1>FIND MCU
1>SCOPE LEFT(CITY+NAME,3) [or LIMIT LEFT(CITY+NAME,3)]
1>BROWSE

The above will list all the titles belonging to MCU, in alphabetical order.

Cautions:

1. FIND should not be used on a file with an active scope/limit. If you choose to do so, be certain that the FIND will be successful. An unsuccessful FIND places the record pointer on record 0 which is by definition not in the index. This causes an error, suspends operation of a program, and turns off the SCOPE.

2. Do not use REPLACE ALL on a field included in an active scope/limit expression, since upon completion, no records will be included in the limit; the result is the same as above.

3. Do not use APPEND, APPEND BLANK or BROWSE APPEND, or enter "append mode" in EDIT, while a scope/limit is active unless you are sure to make all new records equal to the current SCOPE key before leaving the new records. Doing so causes the file to move outside the SCOPE or LIMIT; the result is the same as above.

4. SCOPE should be used with extreme care, and left in effect for the minimum number of commands possible. For instance, if used with BROWSE, SCOPE should be invoked immediately before the BROWSE command and canceled immediately afterward.

5. SCOPE should be canceled before closing the index or the file with which it is active, or before the master index is changed with SET INDEX TO n. If not done by the user or programmer, the SCOPE is automatically turned off by Shark.

6. SCOPE cannot be used with a string constant instead of a <key exp>. The <key exp> can be implemented with a macro.

7. SCOPE is a synonym for the LIMIT command, and can be used interchangeably.

SCREEN

Save and restore screen images between the displayed screen and up to three additional background screens.

One of three forms:

 1. SCREEN <source, destination>
 2. SCREEN <destination>
 3. SCREEN <effect>


 <source>      the number of the screen to be transferred to
                    destination in form 1
 <destination> screen number to which all screen output in to be
                    directed in form 1; the "active" screen in form 2
 <effect>      transfer the stored image of Screen 2 to Screen 1
                    (the visible screen) in form 3; transfer uses the
                    named effect in Shark only if NOEFFECTS
                    not in CNF file

Screen 1 is the screen the user can see, although screen output can be directed to any of three background screens, numbered 2 through 4, and images can be transferred directly from any one to any other.

In DOS, the visual impact of these transfers can be enhanced by using any of seven special effects, each accompanied by a characteristic sound effect. These seven special DOS effects are achieved by naming them with these keywords:

Keyword   Effect
Tear      Push the current screen up and to the right
Left      Push the current screen to the left
Right     Push the current screen to the right
Up        Push the current screen up
Down      Push the current screen down
Open      Expose Screen 2 gradually from the middle
Close     Push the current screen into itself at the middle
Shortcut: When specifying effect by name, only the first character is required.

NOTE: Windows/Linux computers may process effects too fast to be noticed!

In all cases, these effects move screen 2 to Screen 1; in order to see to effect, the active screen should be Screen 1.

In its default mode, color attributes and cursor positions are stored and restored automatically. SET SCREEN OFF to allow color attributes and cursor position to be unaffected by the SCREEN command.

Example in a program:

CLS
? "Wait while directory listing is processed . . ."
SCREEN 2          ;direct output to background screen

DIR
etc
etc
SCREEN 1          ;make the visible screen active again
SCREEN TEAR       ;same as SCREEN 2,1


SCROLL

Scroll a part of the screen.

 SCROLL <line1>,<line2>

 <line1>      from this line number
 <line2>      to this line number

Scroll the screen up one line from line number line1 to line number line2; line1 and line2 are numeric expressions. If line1 is less than line2, the scrolling is reversed. line1 cannot equal line2.

This command is used to scroll text on the screen.

Examples:

1. Interactive demo:

1>SCROLL 2,5
1>SCROLL 5,2

2. Scrolling demo. Needs two data files:

CUST.DBF, with fields CUSTN (customer number), NAME (customer name), ADD:1 (address)

INVEN.DBF, with fields STYLE, COLOR, DESCRIPT, QUANT, COST

USE cust
USE#2 inven
@ 2,0 SAY CEN('Shark can scroll windows',80)
@ 5,0 SAY CEN('windows can scroll up !',80)
DELAY .5
@ 7,0 SAY 'CUSTN  NAME                           ADDRESS'
REPEAT 5 TIMES VARYING i
   ? custn,name,add:1,i
   SKIP
   DELAY .5
ENDREPEAT
REPEAT 5 TIMES
   SCROLL 8 12
   @ 12,0
   ?? custn,name,add:1
   DELAY .5
   SKIP
ENDREPEAT
@ 14,0 SAY CEN('and windows can scroll down',80)
DELAY .5
@ 16,0 SAY 'STYLE  COL DESCRIPTION          QUANT    COST'
DELAY .5
SELECT 2
REPEAT 5 TIMES VARYING i
   ? style,color,descript,quant,cost,i
   SKIP
   DELAY .5
ENDREPEAT
REPEAT 5 TIMES
   SCROLL 21 17
   @ 17,0
   ?? style,color,descript,quant,cost
   DELAY .5
   SKIP
ENDREPEAT

SEEK

Find the first record matching a the value of a given FIND expression by its index in the selected data file.

 SEEK <char exp>

 <char exp>   expression to be evaluated and found in the current
                index

SEEK is one of a family of commands that finds a record in an indexed data file by matching a given string with key values in the index file:

SEEK is identical to FIND, except that it searches for the match to the value of a character expression instead of a string constant (no-find positions the file at the top of file)

FIND positions the file on the first record in the index matching the LAST string (no-find positions the file at the top of file)

LAST positions the file on the last record in the index matching the FIND string (no-find positions the file at the top of file)

NEAREST positions the file on the first record in the index equal to or greater than the FIND string

All forms allow a search to be made on a character expression when the expression if preceded by the macro symbol "< & >". When the variable var='TAYLOR', all of the following command lines are equivalent:

SEEK var
FIND &var
SEEK &var

If SET DELETE ON, deleted records will not be found. (See the command SET)

Numbers must always be treated as strings, even if the key expression is a numeric field. If NUM is a numeric field of width 2, FIND 1 will not find 1, but SEEK STR(1,2) or SEEK ' 1' will be successful.

When SEEK is successful, the value of the current record pointer (as shown by the # and RECNO( functions) is set to the current record number, and the system variable :NEAR is set to the same number.

If the record is not found, the current record pointer will be set to 0 and the value of :NEAR will be set to the number of the first record in the index with an index key greater than the FIND string; if the index contains no key greater than the FIND string, :NEAR is set to the bottom of the file and EOF( is set to T (true).

For a fuller discussion, see the FIND command.

SELECT

The SELECT command provides an easy way for the programmer to move from one data file to another during the running of a program, for example, from customers to invoices, and back again.

The SELECT command selects the file number to work with.

 SELECT <num const>/PRIMARY/SECONDARY
 <num const>    a file number between 1 and 10

This command selects a file number, <num const>. Once this number has been selected, the data files opened with the USE command will be referred to as file <num const>.

There can be ten data files open at the same time in Shark; each must have a different file number.

SELECT 1, SELECT 2, and so on are regarded as command verbs; no part of the command can be in a macro.

Examples:

1>SELECT 4
4>

You can temporarily change the selected file by putting the file number after the command keyword.

Example:


1>USE#1 invoices
1>SELECT 1
1>USE#2 customer
1>LIST

The LIST command will list from #1 (the invoice file), and the customer file will be opened as file #2. To change the selected file to "customer", say SELECT 2. Then when you give the command "LIST", Shark will list CUSTOMER data.

Note to dBASE and Clipper programmers: No version of dBASE or Clipper uses file numbers the way Shark does, but both have a method of field redirection that must be adjusted when porting dBASE applications to Shark. dBASE III and later versions use aliases, established when the file is opened with USE, that are linked to a field name with an arrow (example: cust->name). Your first step in program conversion is replacing these constructs with Shark file-numbering scheme (example: cust#2).

SET (environment control switches)

Set up environmental control switches in a program or, for example, in the VPI.CNF or SHARKNET.CNF file where preferred ON/OFF switch settings can be saved:

SET <param> where parameter is chosen from the table below:

Switch: ON/OFF NOTE: All settings have a default setting as shown in the following table if nothing is specified. Individual switches can also be set in a program if required

Example (in a program):


1>USE#1 invoices
1>SET APPEND OFF

NOTE: Not all "SETS" are switches. Some (such as SET DATE or SET FORMAT) are formatting instructions listed separately in this article.

The following SETS have default settings and do not need to be specified unless you wish to change the default. To set Shark preferred environmental controls in the .CNF configuration file, select from the following settings using the SET <parameter> <switch> syntax. (In each example, the default setting is marked with an asterisk: *)

It is not necessary to specify the default settings. Some of the following settings are managed by Windows when running Shark/VP-Info under vDOS.

.
Parameter Switch Explanation
ADD ON When doing a POST, and the find is unsuccessful, a record will be appended to the Master File, the non-numeric fields of the Master File record will be replaced by the matching fields in the Transaction File record, and, the posting is done to the new record.
*OFF When doing a POST, and the find is unsuccessful, an error message is sent
ALTERNATE ON An alternative to SET PRINT ON and SET FORMAT TO PRINT commands: output that would be sent to the printer is sent to a disk text file instead. The name of the disk file is specified in the SET ALTERNATE TO <file> command (see also SET ALTERNATE TO). SET PRINT ON is ignored when SET ALTERNATE ON.
*OFF Stop sending output to the disk file. (NOTE: SET PRINT OFF also sets ALTERNATE OFF if ALTERNATE ON. Do not mix SET PRINT and SET ALTERNATE commands, however; only use these commands in ON/OFF pairs.)
ANSI ON ANSI.SYS is no longer supported for terminal emulations by Shark, but the SET ANSI command is allowed for compatibility with programs written for earlier DOS versions of VP-Info. It has no effect under Shark on vDOS/Windows
*OFF SET ANSI has no effect in Shark on vDOS/Windows.
APPEND *ON Pressing Ctrl-PgDn in BROWSE & EDIT appends a blank record
OFF Ctrl-PgDn is ignored in BROWSE & EDIT
APRI ON Prevents access to Shark interactive system when a program is cancelled by placing "SET APRI ON" in CNF file
*OFF Allows access to Shark system when a program is cancelled
BELL ON The computer rings the bell whenever illegal data is entered or when data input goes from an editing field to the next editing field. Also activated by the RING command in a program.
*OFF Bell is turned off
CARRY ON When in APPEND or the append mode of EDIT, make the appended record identical to the current record.
*OFF Appended records are blank.
CONFIRM ON In full-screen editing, data entry into an editing field must be terminated by pressing . (When filling a numeric field, this condition will drop the last numeric character, the one under the cursor. The remedy is to make the input picture one character wider.)
*OFF Once an editing field is filled, data entry proceeds to the next editing field.
CONSOLE *ON The output directed to the screen goes to the screen. This flag is always set when is pressed or Shark stops execution on an error.
OFF All output directed to the screen is suppressed. (Note, however, that scrolling is not suppressed by this command, so existing material on the screen can be scrolled off the top of the screen. Consider directing screen output to a background screen instead of SET CONSOLE OFF.) Refer to the SCREEN command.
DEBUG ON Activate all the DEBUG print commands and force Shark to recompile all programs; does not use pre- existing CPL files.
*OFF Ignore all the DEBUG print commands and use CPL files when present.
DELETED ON All records with the DELETED flag are ignored by all the commands except the GOTO command.
*OFF Records with the DELETED flag are listed, found with FIND, etc., but marked as DELETED (however, these records are never appended, averaged, copied, counted, summed, totalled, or reported).
DELIMITER ON The editing fields in the @ GET, EDIT, BROWSE, TEXT (@ and % macros) commands are bounded by colons.
*OFF These editing fields are not bounded by colons.
DISPLAY *ON Displayed macros are immediately updated in a TEXT during READ when their values are changed in an ON FIELD structure.
OFF Displayed TEXT macros are not updated during READ.
DIVZERO *ON Division by zero is permitted and does not cause execution of a program to cease with an error message; the result of division by zero is arbitrarily set at zero.
OFF Division by zero is not permitted and causes program execution to abort with an error message.
ECHO ON When compiling an Shark program (including the compiling done on-the-fly before running an uncompiled program), the text of each program line is shown on the screen as it is compiled; it has no effect while programs are actually being executed. This allows the programmer to verify the compiling of each PRG file. (Always "ON" in the vDOS Windows environment)
*OFF Program lines are not shown.
EJECT *ON In a report form file, the EJECT line will send a form feed character after each subtotal. Useful in a DOS environment; however this is disabled under Windows since printer output is directed to a text file. If you wish to print to a continuous printer roll in vDOS, you will need to install the vDOS Print tool.
OFF Under DOS, in a report form file, the EJECT line will send enough carriage returns to move the paper in the printer to the form depth set by the SET LENGTH TO command (default is 66).
END *ON During READ while SET FUNCTION OFF, pressing any function key has the same effect as pressing <End>; READ is exited and the function key number is stored into :KEY.
OFF If SET FUNCTION OFF, then all function keys give a carriage return and line feed combination (leave input field) and the function key number is stored in :KEY. READ is not exited, but action can be controlled in an ON FIELD structure.
ERROR *ON If an ON ERROR structure is in effect, it is executed in event of an error. Stops at every little error!
OFF An active ON ERROR structure is ignored and Shark reacts as though the structure did not exist.
ESCAPE *ON Hitting <Esc> aborts program execution, or if an ON ESCAPE structure is in effect, program execution jumps to the start of the structure.
OFF <Esc> is ignored.
EXACT ON Whenever strings are compared for equality (in conditions, or when invoking FIND), all characters in both strings, including trailing blanks, are compared, and only perfect matches are true. Thus 'ABCD'='ABC' is false, and FIND ABC will not find 'ABCD'.
*OFF Whenever strings are compared for equality, trailing blanks are ignored, and only the number of characters to the right of the = sign are compared. Thus 'ABCD'='ABC' is true, and FIND ABC will find 'ABCD' (if 'ABCD' is the first record key starting with 'ABC').
EXECUTE ON All FIELD modules in an ON FIELD structure are executed before exiting READ (or the current record in BROWSE OFF and EDIT OFF), as well as when leaving their respective input fields.
*OFF FIELD modules are executed only when leaving their respective input fields.
FUNCTION *ON Function keys display values stored in them when each key is pressed. There are default values pre-stored in the keys, and they can be over-written manually if desired. Values can be stored in each function key by typing ":F[n]=<value> where "n" is the number of the function key, e.g. :F2, :F3, etc. Example: :F3="WRITE"
OFF Disable the usual functions of the function keys <F1> to <F10>. The number of the function key pressed is available to the programmer in the :KEY system variable. Turning the function keys OFF doesn't remove the values stored in the keys; it only turns off any action.
GET ON A Get Table*is assembled for every input screen and is maintained when calling a sub-program; it is, therefore, still in effect upon return from the sub-program, provided it is not cleared in the sub-program. (A Get Table is cleared either with the CLEAR GETS command, or by creating a get with TEXT or an @ GET command after a READ command.) *NOTE: in VP-Info/Shark, the group of screen organizing values which surround the collection of inputs on a screen is called a "Get Table"
*OFF A Get Table is cleared whenever program execution leaves a sub-program.
HEADING ON Field names are displayed over each column during LIST and DISPLAY command execution. If fields names are longer than column width, the name is truncated as in BROWSE. Headings are not displayed if an expression list is given on the LIST or DISPLAY command line.
*OFF Field names are not displayed with LIST and DISPLAY.
INTENSITY *ON The editing fields in full-screen editing are shown in reverse video. This setting also illuminates menu buttons.
OFF Editing fields are shown in normal video, and no menu buttons are illuminated.
KEEP ON When a TEXT file is read from the disk, it is stored in memory so that subsequent calls for the same TEXT will use the version in memory instead of reading it in from the disk again.
*OFF The disk is accessed every time the TEXT file is called. Note: If the TEXT filename is a macro or variable name, Shark always goes to the disk for the text whether SET KEEP is ON or OFF.
LINE *ON Place line numbers in compiled program to be used with error messages. This is very useful when using a programmer's editor like Notepad++ since the line numbers in Shark and Notepad++ match exactly. The efficient programmer will have Shark-on-vDOS & NPP open at the same time!
OFF No line numbers in compiled program.
LOCK ON Shark Network Edition only. All data file records are automatically locked whenever the user is positioned on them.
*OFF Records are not automatically locked.
MENU ON Display the meaning of the editing keys for EDIT and BROWSE, and displays a help box when Shark starts and whenever the screen is cleared.
*OFF No editing keys or help box are displayed.
MONO ON A monochrome monitor is used. (Has no default setting) Not required unless both monochrome and color adapters are present in your computer). This choice is handled by Windows.
OFF A color monitor is used.
NETWORK ON Turn network facilities on (Shark Network Edition only; enables the user to LOCK and UNLOCK records on any network or multi-user system adhering to the standard conventions of Microsoft DOS 3.1 and above. See SET NETWORK [ON][OFF] command).
*OFF Network facilities are not turned on (Shark Network Edition Only)
PROMPT ON A dot prompt, as in dBASE.
*OFF The n> prompt (Example : 1>, 2>), where n is the current work area.
RAW ON No blanks separate the expressions when the DISPLAY or LIST command is used with an expression list (see ?, ??, DISPLAY, and LIST).
*OFF Blanks are placed between expressions.
SAVE *ON Changes are saved to disk when the user leaves a changed record or closes the data file.
OFF Changes are not written to disk.
SCREEN *ON SCREEN command works as described under SCREEN command. This instruction is most often used to hide background Shark activity (e.g. searching or indexing) when running a program. Most screen effect options such as "tear away", while entertaining on a DOS computer, happen too fast to be noticed on a Windows computer!
OFF When screens are switched with SCREEN command, cursor position and color attributes are not saved or restored. (Provided only to allow user to force compatibility with early versions of VP-Info.
SNOW *ON When using a CGA color monitor and some other monitor types under DOS, Shark may cause screen flicker called "snow". This issue is handled by Windows.
OFF Snow is suppressed on DOS computers, at a cost of slowing screen displays.
SOUND *ON Turns on sound effects if NOEFFECTS was not found in the SET file when Shark started. SOUND command and all screen effects will emit various sounds. May not be useful on Windows systems.
OFF Suppresses sound effects for all screen effects, and replaces output of SOUND command with sinple beep (same output as RING command).
STEP ON Execute an Shark program a line at a time (SET LINE ON must have been in effect when the program was compiled.) The line number is displayed on the top line of the screen display. Useful for debugging programs.
*OFF Execute Shark programs continuously.
TALK *ON Shark messages from commands are displayed. This flag is always set when <Esc> is pressed and when the conversational mode is entered.
OFF Messages are not displayed
TEXT *ON The TEXT display macros created with <&≫ and <#≫ are put into the Get Table; usually required for input screens created with TEXT.
OFF Display macros are not put into the Get Table; usually required when using TEXT for printer output, as in mail-merge programs.
TRIM *ON The <&> macro in TEXT trims string variables.
OFF The trimming is turned off.
UPPER ON All keyboard-input characters from "a" to "z" are forced to upper case "A" to "Z"; a software "Caps Lock".
*OFF Lower-case keyboard entry is not altered.
ZERO *ON Display zeros whenever the numeric value zero must be displayed.
OFF If the value zero has to be displayed, display blanks instead.

SET ALTERNATE


Specify text file for output.

 SET ALTERNATE TO <file>

 <file>          text file name

The command SET ALTERNATE specifies the text file to be used when the SET
ALTERNATE ON command is given.  The default extension of the file is TXT.  If
the file already exists, the new data is appended at the end.  (See SET
ALTERNATE ON under the SET command.)

All data that would normally go to the printer is sent to this file.

Example:
SET ALTERNATE TO record
SET ALTERNATE ON
@ 10,0 SAY 'This goes to RECORD.TXT'
SET ALTERNATE OFF

SET COLOR

COLOR ATTRIBUTE TABLE:


 SET COLOR TO <attrib>

 <attrib>   numeric expression, the attribute byte: 0 to 255

This command sets the attribute byte of all characters to be displayed on the screen, and updates the system variable :COLOR with <attrib>. SET COLOR TO 0 returns to the normal mode. An alternative way of getting the same result is:

:COLOR=<attrib>

These commands work with standard color monitors. There is no harm in experimenting with values! Not all monitors function in an identical manner, but these demos will give you the general idea.

Every character displayed on the screen has an attribute byte that determines how the character is displayed.

Compute ATTRIB by adding up (up to) four numbers (background+ foreground+brightness) from the following tables:

BASE BACKGROUND COLOR ADD:TEXT COLOR ADD:BOLD/BRIGHT TOTAL VALUE
0 - black background 15 - white text 0 - normal Total: 15
16 - blue background 14 - yellow text 0 - normal Total: 30
32 - green background 0 - black text 0 - normal Total: 32
48 - cyan background 0 - black text 0 - normal Total: 48
64 - red background 0 - black text 0 - normal Total: 64
80 - magenta background 15 - white text 0 - normal Total: 95
112 - white background 0 - black text 0 - normal Total: 112
120 - white background 0 - black text 8 - bold Total: 120

Color Examples:

COLOR 15 white on black (15+0=15)
COLOR 31 white on blue (15+16=31)
COLOR 36 red on green (4+32=36)
SET COLOR TO 18 Sets DEFAULT attribute to green on blue (2+16=18)
SET COLOR TO 26 Sets DEFAULT attribute to bold green on blue (2+16+8=26)
SET COLOR TO 208 Sets DEFAULT attribute to black on pink (0+208=208)
SET COLOR TO 30 Sets DEFAULT attribute to yellow on blue (14+16)
SET COLOR TO 38 Sets DEFAULT attribute to bright yellow on blue (14+16+8)
COLOR 112 black on white (0+112=112)

To change color of a portion of text on screen, add text coordinates. For example:

SET COLOR TO 30,5,0,10,79 

will change text to yellow on rows 5 to 10 for all programs.

COLOR 30,5,0,10,79 

will change text to yellow on rows 5 to 10 for the current program only.

To view colors available on your monitor while running Shark, copy the attached file to your Shark environment and call it at the Shark prompt with "DO COLORS":

Demo Program: A Shark program to show all available colors on a monitor

Depending on how you lay out your screens, some experimenting is required since some colors may be set to over-write other colors. The following instructions will have quite different results:

:COLOR=30
SET COLOR TO 30, . . .
COLOR 30, . . .

Be patient!

SET DATE

Set the default form for dates. This is normally done in the .CNF file since it rarely, if ever, changes.

 SET DATE TO <str exp>

 <str exp>     the default date format

This command, in conjunction with the date function DATE(7, <str exp>), is designed to give control over input of dates. The order of the day, month, and the year, and the number of digits in year (2 or 4), is controlled as follows:

    SET DATE TO                 formats '12/31/2021' as follows:
     'mmddyy'                             123121
     'ddmmyy'                             312121
     'yymmdd'                             211231
     'mmddyyyy'                           12312021
     'ddmmyyyy'                           31122021
     'yyyymmdd'                           20211231 

These are the six available arrangements of the date elements. Example:

SET DATE TO 'yyyymmdd' 

Another example: A useful method to style the default date format throughout all your current programs is to include the following lines in your VPI.CNF or SHARKNET.CNF file using one of the above valid formats:

SET DATE TO 'YYYYMMDD'
:DATE=DATE(8)
:UNDOC=PIC(DATE(8),"XXXX.XX.XX")

Thus, when wishing to insert today's date into a new invoice, for example, your program can request "? :date" - (or "? :undoc" for the more fancy example). You can even further style your dates by creating a lookup to change the "MM" value into the full name of the month.

Calling "? date(0)" resets :date with today's date until Shark is restarted. If you "LIST SYSTEM" at this point you will see (for example):

:DATE           C      27      Thursday, February 22, 2024

Other date displays (e.g. "date(8)" are unaffected. The only difference at this point is the calendar date is changed to reflect the computer system clock. This is useful if your Shark is running past midnight and the date needs to be refreshed. NOTE that VP-Info doesn't offer this function and the only way to refresh the date in VP-Info is by restarting VP-Info.

It's quite likely that you will rarely, if ever, change your date style in daily use once you have found a preferred date style.

SET DEFAULT

[Obsolete on new systems] Set the drive letter of the default floppy disk drive for data and index files*.

 SET DEFAULT TO <drive letter>

 <drive letter>  the drive letter of the default floppy drive

This command sets the drive letter of the default floppy drive for data and index files only. If this drive letter is, say, C, every data and index file will be searched for on drive C, unless the file name contains an explicit drive letter.

This command will rarely be used on new systems, but is provided for compatibility with older versions of Shark. Most users will prefer the extra flexibility of the FILES command, the FILES ... ENDFILES structure, and the SET DIR command. The first two allow you to specify exactly where specific files and groups of files are to be found, and the third actually "logs" you onto any disk and/or directory.

Sample FILES...ENDFILES list (from your SHARKNET.CNF file on a large SSD with terabytes of empty space). With lots of space, you can store/save your files wherever you like:

FILES
*.TXT,C:\DAT\
*.BAK,c:\BAK\
*.ERR,c:\ERR\
*.LOC,C:\LOC\
*.MEM,C:\MEM\
*.SCR,C:\SCR\
*.PRG,c:\PRG\
*.FRM,C:\FRM\
*.DTA,C:\DTA\
*.CPL,C:\CPL\
*.DBF,C:\DBF\
*.NDX,C:\NDX\
ENDFILES

On an older floppy drive setup with limited capacity, you might use the following instead of the more flexible FILES ...ENDFILES setup shown above:

SET DEFAULT TO C

For more information, see the FILES command, the FILES ... ENDFILES structure, and the SET DIR command.

Example:

1>SET DEFAULT TO C
1>USE employee INDEX a:emp2

In this example, the data file EMPLOYEE.DBF will be looked up on drive C: - however, the index file EMP2.NDX will be fetched from drive A:.

*NOTE: this command may be useful on older systems with floppy drives, but unnecessary with large-capacity (SSD) solid-state drives.

SET DIR

Change drive and/or current directory.

 SET DIR TO [<drive>:][<directory>]

 <drive>         the drive letter of the new default drive
 <directory>     the directory name (according to DOS rules)

This command changes the current drive and/or the current directory; equivalent to combining the DOS commands change drive and CHDIR (CD).

Contrast this with the FILES and SET DEFAULT TO commands, which only tell Shark where to look for certain categories of files without changing the user's current position on the disk. Exit from Shark after SET DIR is in the new directory on the new drive.

If <drive> is not specified, the new directory is on the same drive. If directory is not specified, the new directory will be the last directory DOS changed to on the target drive or, if no directory has been changed to, the root of that drive.

If <directory> begins with a backslash (example \DATA), the directory will be off the root; if not, the directory will be off the directory onto which the user is currently logged.

If the <drive> is invalid, no message will be given, but the change will not take place. If no <drive> is given and the <directory> is invalid, again no change will occur. However, if <drive> is valid and <directory> is invalid, the drive will change and the user will be logged into the current directory on that drive.

The current drive and directory can be checked with the :DIR system variable, which always contains the current drive and directory (example C:\INFO).

Caution: If you change directories within Shark, you may lose track of where some of your files are. This is particularly likely if you have a FILES structure in use without full path names giving both drive letter and leading backslash on the directory.

Example:

1>SET DIR TO D:\UTIL
1>? :DIR
D:\UTIL

SET FIELDS

An obsolete command retained in the language for compatibility with earlier versions of VP-Info.

 SET FIELDS TO <num const>

 <num const>   the number of fields

This command is ignored in Shark. In Shark, its role is taken by the FILES= command in the SHARK.SET file.

SET FILTER

Set a condition which applies to all subsequent data-file commands.

 SET FILTER TO <cond>

Option:

 <cond>    the condition applied to all subsequent data-file commands

Most commands that use data files (LIST, REPLACE, REPORT, etc.) allow a selection condition to be specified with a FOR clause.

Shark also allows a global condition to be attached to all data- file commands, including many that do not allow a FOR clause, including SORT, EDIT, and BROWSE.

The filter is turned off with FILTER TO without a condition.

While a filter is in effect, a FOR clause can be used with commands to limit further the records subject to the command.

Examples:

1. Browse a filtered data file:

1>SET FILTER TO amt:due>0
1>BROWSE

2. Produce a listing of payables due to vendors in California, only if there is actually an amount due.

1>SET FILTER TO amt:due>0
1>REPORT owing FOR state='CA'

SET FORMAT

Directs the @ SAY commands to screen or printer.

 SET FORMAT TO SCREEN/PRINT

Switch:

 SCREEN     send output to screen; the default
 PRINT      send output to printer

SET FORMAT TO SCREEN or PRINT is used to send data formatted with the @ SAY command to the screen or the printer (but not to both). The default is SCREEN. (See the command @.) The default is always set when <Esc> is pressed.

IF SPOOL or SET ALTERNATE TO has redirected print output to a disk file, SET FORMAT TO PRINT will cause output to go into the disk file.

SET INDEX

Specify index files.

 SET INDEX TO
 SET INDEX TO <file>
 SET INDEX TO <file list>
 SET INDEX TO <num const>

 <file>        the name of the index file
 <file list>   a list of up to 7 index files
 <num const>   a number between 1 and 7

The command SET INDEX TO specifies the index file(s) to be used with the selected data file. If more than one index file is given, the first index file will be used as the Master Index. The Master Index is used by the FIND command, and all the display type commands (BROWSE, LIST). However, all the index files specified in the list are maintained by the commands that add or edit records (APPEND, EDIT, @ GET, and so on).

The Master Index can be changed with the SET INDEX TO <num const> command. The index files are assigned numbers when they are activated in a file list. Say, SET INDEX TO 3, makes the third on the list the Master Index. This involves no disk action; no file is opened or closed. Index files can also be opened with the USE command (see USE).

SET INDEX TO with no file name, closes all the index files for the selected data file, but the data file is not closed. Index files are also closed when the data file is closed. (See the commands CLOSE and USE.)

Examples:

1>USE employee
1>SET INDEX TO employee,empl2,empl3
1>LIST
1>SET INDEX TO 3        ; makes empl3 the Master Index
1>SET INDEX TO          ; closes all index files for the selected file

SET LENGTH

Set page depth on a dot-matrix printer when the printer does not support a standard formfeed control character. Not used on a laser printer.

 SET LENGTH TO <num exp>

where <num exp> = the page depth

The page depth is the number of lines from the top of the page to the very bottom of the page. If the SET LENGTH command is not used, page depth is assumed to be 66.

Warning: SET LENGTH does not set how many lines will be printed on a page but the physical size of the page. This command is used if the page depth is unusual (e.g., filling in a preprinted form), or if the usual 6 line per inch printing is changed, say, to 8 lines per inch.

Example:

1>SET LENGTH TO 40

SET LIBRARY

Set the drive letter of the default disk drive for data and index files.

 SET LIBRARY TO <library>

 <library>     a library file, default extension LIB

This opens a special form of file called a library, which contains up to 65,000 library entries each of 256 bytes. Library entries are automatically combined into volumes of up to about 20,000 characters by creation of an internal linked list, analogous to the way DOS links disk clusters together to make large disk files.

If the <library> does not exist, it will be created. The default extension for library files is LIB.

Library volumes can be created only with the WRITE command, and output only with the TEXT command (although a programmer can also access the data through use of the sequential file functions SEEK(, GET(, and PUT( if sufficiently skilled).

Both WRITE and TEXT distinguish between standard disk files and volume numbers in their command lines by preceding volume numbers with a period. Do not mistake this usage for a decimal number.

Technical information for experienced programmers: the structure of a library file is as follows:

Header:

  Bytes 0 and 1        next volume to be added, an unsigned integer
  Bytes 2 and 3        next available volume, an unsigned integer; may be
                            less than next to be added because existing
                            volumes may have been released with
                            REMLIB( function or shortened with WRITE

Bytes 4 through 15 unused

Each volume:

Bytes 0 through 253 the text contents of the volume; end of file indicated by 1A hex

Bytes 254 and 255 a pointer to the next part of the volume, an unsigned integer; if no next part, pointer is null

Examples:

1. In Conversational Shark

1>SET LIBRARY TO screens
1>? :avail                  ;get number of next available volume
     65.00
1>WRITE .:avail             ;use WRITE to enter a file in volume 65

2. In a program, use a library to attach notes and memos to records in a data file. Library entry numbers are stored in a numeric field called MEMONUM:

*****************************************************************************************
* EDITMEMO.PRG:
* DEMONSTRATION USING LIBRARY ENTRIES FOR RECORD MEMOS
* implemented as subroutine, assuming library already opened in
* calling routine; each record has field MEMONUM with memo number
*****************************************************************************************
SCREEN 1,3 ;store screen into memory WINDOW ;cancel existing window CLS ;erase entire screen WINDOW 4,5,21,74 double ;make bordered window WINDOW 5,5,21,71 blank ;long lines don't hit right border @ 24,0 say cen('Use function keys for TEXT storage.',80) IF memonum=0 ;only make new memo if one REPL &mscreen with :avail ; not already started ENDIF SET function on ;allows normal function key use WRITE .memonum off @ 24,0 ;erase message at bottom of screen SET function off ;keys usable for program control SCREEN 3,1 ;restore original screen RETURN

SET LINK

Set up a physical link between two data files.

 
 SET LINK TO <num const>
 SET LINK OFF

 <num const>  the selected file is linked to the file with
                   this file number

The command SET LINK TO sets up a link between two files by record number. After the link is set up between the selected file and another file, as the record pointer is moved in the selected file (for instance, with GO, FIND, or LIST), the record pointer in the other file is similarly moved. If the selected file has more records, once the record number is too large for the other file, its current record number pointer will stay on the last record.

SET LINK OFF turns off the linkage (if any) from the selected file.

SET LINK TO can "chain" many files together.

 
1>SET LINK TO 2
1>SET#2 LINK TO 4
1>SET#4 LINK TO 6
links together the files 1, 2, 4, and 6.
     There can be only one SET LINK TO command from any one file.
2>SET LINK TO 3
2>SET LINK TO 4

The second command overrules the first.

It is the user's responsibility to make sure that there are no "loops" such as in:

 
1>SET LINK TO 2
1>SELECT 2
2>SET LINK TO 1

NOTE: If SET LINK is used, SET RELATION should be avoided.

SET MARGIN

Specify text margin for dot-matrix printer.

 SET MARGIN TO <num exp>

 <num exp>   the margin

The command SET MARGIN sets the left margin for the printer. This command can be used in conjunction with any command that sends output to the printer.

Example:

SET PRINT ON
SET MARGIN TO 5
? 'This is indented'

Prints:

       This is indented.

SET NETWORK [ON][OFF]

Specify the network.

 SET NETWORK TO <num exp>
 SET NETWORK  ON/OFF

 <num exp>   the network number

This command enables the user to LOCK and UNLOCK records on any network or multi-user system adhering to the standard conventions of Microsoft DOS 3.1 and above.

The network calls are turned on with SET NETWORK TO 1 or SET NETWORK ON.

The network calls are turned off with SET NETWORK TO 0 or SET NETWORK OFF.

Caution: Do not SET NETWORK ON when the SHARE command or your network's equivalent is not in effect. If you want to run Shark Network Edition in both modes, start from different directories depending on whether the network is loaded. Put SET NETWORK ON in the SHARKNET.CNF file in one directory, and SET NETWORK OFF in the other.

Examples:

1>SET NETWORK TO 1
1>SET NETWORK TO 0
1>SET NETWORK ON

SET PRINT ON

Output produced by display commands as LIST, DISPLAY, ?, and ?? is sent to an MS-DOS printer port, or to a Windows printer if Shark is running on a Windowsm emulator (or to a text file if SPOOL is in effect).

SET PRINT ON
? "Some printed text"
SET PRINT OFF
 

If SET PRINT OFF is activated when a text file is being sent, the output is sent to the SCREEN instead. This flag is always set OFF when <Esc> is pressed or an error is encountered while running a program.

NOTE: Under Windows, the single command "SET PRINT ON" requires that Shark is running on a Windows emulator because Shark sends output to a MS-DOS printer port (e.g. LPT1) which does not exist in Windows. The emulator manages Shark printed files on Windows, either directly to a Windows printer or spooled to a FILE and printed by a text editor such as NotePad. In this case, "SET PRINT ON" is combined with "SPOOL" to direct output to a text file, which can then be printed by Windows. Example:

SPOOL \TXT\EXAMPLE.TXT
SET PRINT ON

Output is directed to a file named "EXAMPLE.TXT" in the \TXT\ folder by default. Depending on the "SPOOL" instruction, the output can be directed to any other folder, for example "SPOOL EXAMPLE.DOC" or "SPOOL \DOC". The folder name is limited to 3 letters because of the MS-DOS 8+3 file name limitations. Your printout can be directed to any 3-letter folder such as \TXT or \DOC thus:

SPOOL \TXT\EXAMPLE.TXT or
SPOOL \DOC\EXAMPLE.TXT

This is a VERY useful feature for organizing and saving your output, regardless of what's requested in your SETUP.CNF file in order to better organize your output. Just think of how useful it would be to have all your customer invoices stored in sequence in one convenient folder! Any invoice could then have notes added as needed without modifying your source code!

Printer spooling to a file is ended with the simple "SPOOL" command:

SET PRINT OFF
SPOOL

Syntax Example:

INVONUM=INVONUM+".TXT"
SPOOL \TXT\&INVONUM
SET PRINT ON
USE INVOICES
LIST ALL FOR INVOICE=INVONUM
?
CLOSE INVOICES
SET PRINT OFF
SPOOL

NOTE that the two PRINT ON/OFF instructions are enclosed by the two SPOOL commands!

SET RELATION [ON][OFF]

Set up a relation between the selected file and another indexed data file.

 SET RELATION ON <str exp> TO <num const>
 SET RELATION OFF

 <str exp>      the key of the relation
 <num const>    the relation is set between the selected file
                     and file <num const>

<str exp> is an expression made up of fields (of character type) of the selected file, string constants, and string variables.

Any time the current record pointer is changed for the selected file, <str exp> is evaluated, and a FIND is made with the result in the file <num const>.

A file can be related to a number of other files: 1 is related to 2, 1 is related to 3, 1 is related to 4 (file 1 has 3 fields on which additional information is available in files 2, 3, and 4); 1 is related to 2, 1 is related to 3, and 3 is related to 4 (the information linking 1 and 3 has additional data on file 4).

Relations can also be chained: 1 is related to 2, 2 is related to 3, and 3 is related to 4.

However, only one file can SET RELATION TO a given file: you cannot have both 1 related to 6 and 2 related to 6.

It is the user's responsibility to make sure that there is no loop, such as 1 related to 2, 2 related to 3, and 3 related to 1.

To disable a relation, SET RELATION OFF, close either the selected file or the target file, or close the indexes on the target file.

Examples:

1>USE order
1>USE#3 customer
1>INDEX#3 ON cust:no TO customer
      3 RECORDS IN TOTAL INDEXED
1>SET RELATION ON cust:no TO 3
1>LIST order:no,fname#3,name#3
      1  10001  Robert          Steen
NO FIND
      2  10002
      3  10003  Joe             Smiths
NO FIND
      4  10004
      5  10005  Robert          Steen
1>SET RELATION OFF

Note: the first order has CUST:NO 0050; this was found in the customer file, and the customer name was listed. The second order has CUST:NO 105; there is no such customer in the customer file, so a NO FIND message is sent (this can be turned off in programs only with SET TALK OFF), and only the ORDER:NO was listed.

SET VIDEO

Change EGA or VGA screen to display 25, 43 or 50 lines when running Shark on a DOS system. This command has no effect when running Shark on an emulator like vDOS or DOSbox. The emulator will set screen parameters in its config file.

 SET VIDEO TO <num const>

 <num const>   the number of lines for the EGA/VGA video display

If your monitor supports 43- or 50-line displays, you can switch your video mode with this command. Numbers other than 25, 43 and 50 are ignored. If you specify a mode not supported by your monitor, you may lose video output.

Example:

1>SET VIDEO TO 43

SET WIDTH

Specify text width for printer when using a dot-matrix printer on a DOS system.

 SET WIDTH TO <num exp>

<num exp> page width

The command SET WIDTH sets the page width (number of characters per line) for the TEXT and REPORT commands. The WIDTH is the width of the text from the left margin; the default is 80. So if the commands:

SET MARGIN TO 10
SET WIDTH TO 50

are given, TEXT will wrap the words at character position 60.

When a matrix variable is displayed, it is wrapped by the value set by SET WIDTH.

The only aspect of a report that is affected by SET WIDTH TO is the number of characters over which its heading is positioned. It has no effect on the report columns themselves.

See the commands SET MARGIN, SET PRINT ON, SET FORMAT TO PRINT, TEXT.

Examples:

1. Program segment:

SET WIDTH TO 40
TEXT
This is a nice long sentence to illustrate SET WIDTH.
ENDTEXT

Prints

This is a nice long sentence to illustrate SET WIDTH.

2. Program segment:

SET WIDTH TO 80
TEXT
This is a nice long sentence to illustrate SET WIDTH.
ENDTEXT

Prints:

This is a nice long sentence to illustrate SET WIDTH.

3. Matrix variables:

1>DIM NUM num[20]
1>? num
      0.00       0.00       0.00       0.00       0.00       0.00       0.00
      0.00       0.00       0.00       0.00       0.00       0.00       0.00
      0.00       0.00       0.00       0.00       0.00       0.00
1>SET WIDTH TO 30
1>? num
      0.00       0.00       0.00
      0.00       0.00       0.00
      0.00       0.00       0.00
      0.00       0.00       0.00
      0.00       0.00       0.00
      0.00       0.00       0.00
      0.00       0.00

SKIP

Move ahead or back in data file.

 SKIP <num exp>

Option:


 <num exp>   by this many records; may be positive (forward) or
               negative (backward); default 1 record forward

The command SKIP moves the current record pointer ahead or back in the selected data file.

SKIP by itself advances the record pointer to the next record.

If you SKIP ahead more records than there are records left in the data file, then the current record becomes the last record. Skipping past the last record sets the function EOF true.

If you SKIP too many records back, the current record pointer will be set to 0.

If there is an index file, ahead and back is understood in the indexed order.

Examples:

1>USE employee
1>? #
     1.00
1>SKIP
1>? #,EOF
     2.00 F
1>SKIP 5
1>? #,EOF
     6.00 T
1>SKIP -2
1>? #,EOF
     4.00 F
1>SKIP -10,EOF
1>? #
     0.00 F

SORT

Sort the selected data file into another data file.

 SORT ON <str exp> TO <file>

 <str exp>     the key of the sort
 <file>        the data file to contain the result of the sort

This command sorts the selected data file to the data file specified. The sort is done by evaluating the <str exp>, creating a temporary index, and copying the file to <file>.

Example:

1>USE employee
1>SORT ON name+fname TO empl2
     This is equivalent to the following:
1>USE employee
1>INDEX ON name+fname TO temp
1>COPY TO empl2

However, the second version has the advantage of allowing a field list and FOR clause, and output as an SDF file, none of which is available in SORT.

For example, suppose the intention is to create a small, sorted data file with only name and address information on single employees for use by the company social club for a mailing about an upcoming event.

The correct way to accomplish this is:

1>USE employee
1>INDEX ON name+fname TO temp FOR .NOT. married
1>COPY TO empl2 FIELDS fname,name,addr,city,state,zip,tel_no

See COPY and INDEX.

SOUND

Use the computer speaker to generate a sound effect on a DOS computer. This command has no effect when running Shark on a DOS emulator like vDOS or DOSbox. The emulator will handle sound effects in its config file.

 SOUND <numeric exp>

 <numeric exp>  the number of the sound required

When effects are enabled (i.e., the NOEFFECTS keyword is not in the SHARK.SET file), SOUND activates the computer speaker with one of a library of sounds effects.

At publication time, there are 13 preprogrammed sound effects, numbered 1 through 13. "SOUND 0" terminates any sound. Values outside the range 0 through 13 are ignored.

As naming the effects is not meaningful, Shark users are urged to run the program example below and try all of them.

Note that effect 2 continues until another sound is activated or SOUND 0 is executed; all other effects have defined duration.

The command RING actually executes SOUND 7 in DOS and in an emulator.

Examples:

1>SOUND 3

A program to demonstrate all 13 effects (running Shark on MS-DOS only):

CLS
REPEAT 13 TIMES VARYING effect
   @ 10,35 SAY 'Effect'+STR(effect,3)
   SOUND effect
   DELAY 1               ;timed pause
   SOUND 0               ;terminate sound if not self-terminating
ENDREPEAT

You may find on your Shark setup running on an emulator that "SOUND 7" may produce nothing, but "RING" may produce a beep sound. Some experimentation will be required!

SPOOL

Redirect printer output to disk file, or send disk file to printer.

Five forms:

 1.  SPOOL <filename>
 2.  SPOOL
 3.  SPOOL <dirname> <filename>
 4.  [DOS ONLY] SPOOL <filename> TO <device> [PAGE <num exp>]
 5.  [DOS ONLY] SPOOL/T

Options explained:

 Form 1:      Create file <filename>  and direct print output to
              that file; default extension TXT
 Form 2:      Close any open spool file and stop redirection
 Form 3:      Create file <filename>  and direct print output to named directory, 
              in this example, to "\doc\"
 Form 4:      [DOS ONLY] Do background printing of <filename> on <device>, usually PRN
              but can be any DOS device PAGE <num exp> start printing on
              page <num exp>
 Form 5:      [DOS ONLY] Stop background printint started with FOrm 3

This command allows printer output to be captured into a disk file, and optionally spooled out to disk while other processing continues. This command has five forms listed above:

1. Used with a filename, it creates a new spool file with the name of filename (default extension TXT).

2. Used without a filename, SPOOL closes any open spool file and restores printer as standard print device.

3. Used with a filename, SPOOL creates a new named spool file and saves it in the specified directory, example: "\INV\12345.TXT" or "\DOC\INFO.DOC". The directory name can be extended up to 8 characters, as in "\INVOICES\&INVNUM"

4. [DOS ONLY]Used with both filename and device name, <filename>is spooled to the specified DOS device, such as PRN, LPT1, etc. If PAGE option is used with a page number (can be an expression) printing starts with the top of that page number.

5. [DOS ONLY]Used with a slash-T (/T), spooling is terminated. This is same symbol as used with the DOS PRINT command for the same purpose.

If SPOOL is used to create a file, and a file already exists with that name, the user in Conversational Shark is required to confirm that the file should be overwritten; in programs, the existing file is overwritten without prompting.

Examples:

1>SPOOL reports
1>REPORT custlist
1>SPOOL
1>SPOOL reports TO prn

SPOOL output can be directed to a different directory on the same drive. Consider this example:

1>SPOOL reports

This sends the reports.txt output to the default directory requested in the FILES list, usually the \TXT directory:

A file stored as a macro can be spooled in the same manner:

1>STORE reports TO repo 
1>SPOOL &repo 

This will send the output to a file named REPORTS in the default directory

The same file stored as a macro can be spooled to a different directory in the same manner:

1>SPOOL \REPORTS\&repo

This sends the reports.txt output to the \REPORTS\ directory, not the default \TXT directory:

SPOOL output cannot be directed to a different drive.

Syntax Example in a program:

INVONUM=INVONUM+".TXT"
SPOOL \INVOICES\&INVONUM
SET PRINT ON
USE INVOICES
LIST ALL FOR INVOICE=&INVONUM
?
CLOSE INVOICES
SET PRINT OFF
SPOOL

NOTE that the two PRINT ON/OFF instructions are enclosed by the two SPOOL commands!

STATUS

Display status information.

 STATUS                                       
 

If used in the interactive mode, this command displays two screens of information on the status of Shark.

The first page lists the data files in use, the current record numbers, which file number is selected (marked by an asterisk), the expressions on which the index files had been indexed (the index file names are not shown).

In the example below, the lines:

Rec #               File name       Indexed by
0000008 *File 1 ... SALES.DBF       SALESMAN+PART , PART , DATE

tell you that SALES.DBF is file 1; the asterisk shows that file 1 is selected; the current record number is 8; there are three index files, indexed by the expressions: SALESMAN+PART, PART, DATE. Next, you find the setting of all the flags; ON is show as Y, OFF as N.

The "Total space left" message gives the number of bytes left in the 64K data space (see Appendix A).

By default, Shark can use 20 files altogether, of which only 16 are actually available to the user. Shark users with DOS 3.3 and above can have up to 50 files open at one time, provided FILES= commands are in both the SET file and the CONFIG.SYS file in the root directory of the boot drive, and both call for at least that number of files. "Files in use" shows how many are being used; you can infer how many are still available (16-4=12 in the standard setting, 46-4=42 if FILES=50).

"High memory remaining" is the number of bytes available for use by matrix variables and background-screen storage.

"Width" and "Left margin" show the most recent setting by SET WIDTH and SET MARGIN, respectively, or the default.

In the example shown below, the top line shows NETWORK ON; when not on, or when not using Shark Network Edition, this message is omitted. When SET NETWORK ON and data files are opened with file modes (READ, WRITE, LOCK, or SHARE), the first letter of the mode is shown immediately before the index expressions.

The second page of the STATUS display is the same as the listing produced by the command LIST MEMORY.

If STATUS is a command in a program, the execution of the program stops, the user can view the two screens, and then program execution resumes. In this use of STATUS, the first page also shows the name of the current program.

Example:

If you give the following commands:

1>number=21
1>name='David'
1>USE sales INDEX sales,part,date
1>STATUS

STATUS will display:

Thursday, March 22, 1990            Shark STATUS                 NETWORK ON

Rec #               File name       Indexed by
0000001 *File 1 ... SALES.DBF       W SALENUM , PARTNUM , DATE
0000000  File 2 ...
0000000  File 3 ...
0000000  File 4 ...
0000000  File 5 ...
0000000  File 6 ...
0000000  File 7 ...
0000000  File 8 ...
0000000  File 9 ...
0000000  File 10 ...


 Add......    N  Delete... N  End...... Y  Heading..   N  Print... N  Step..... N
 Alternate    N  Delim.... N  Error.... Y  Intensity   Y  Prompt.. N  Talk..... Y
 Bell.....    N  Display.. Y  Escape... Y  Keep.....   Y  Raw..... N  Text..... N
 Carry....    N  Divzero.. Y  Exact.... N  Line.....   Y  Save.... Y  Trim..... Y
 Confirm..    N  Do....... Y  Execute.. Y  Lock.....   N  Screen.. Y  Upper.... N
 Console..    Y  Echo..... N  Function. Y  Menu.....   Y  Snow.... Y  Zero..... Y
 Debug....    N  Eject.... Y  Get...... N  Mono.....   Y                       

Program .............. GENERAL.PRG      Files in use ......... 1
Memory remaining ..... 23490            High memory remaining. 39744
Width................. 80               Left margin .......... 0

STORE

Assign value to a memory variable.

 STORE <exp> TO <memvar>                      
                                              
 <exp>      the value assigned                
 <memvar>   name of memory variable   

This command assigns a value to a memory variable; if the variable does not exist, it will be created. An equivalent way of assigning value is with the = command. See the command =.

Examples:

1>STORE 3 TO b
1>STORE 5*b TO c
1>? c
    15.00

STUFF

Stuff the keyboard buffer with characters and scan codes to be fed to a "child" program to be executed with the ROLL command.

Examples:

 STUFF STRING <string>
 STUFF FILE <file>
 STUFF

Options:

 <string>           a specially formatted string to be passed to a
                      "child" program
 <file>             name of file containing stuff string       
 no option          clear the STUFF buffer

When a program is started with the ROLL command, commands can be "fed" to the "child" program through the keyboard buffer. The child program reacts exactly as though the user is typing commands directly at the keyboard.

The STUFF command uses a special stuff buffer, to transmit these keystrokes to the child program.

STUFF has three forms, used to fill or clear the stuff buffer. Once filled, the buffer retains its contents until another STUFF command either overwrites its contents or clears it.

The first two forms convert a stuff string, a sequence of key descriptions, into the form required by the keyboard buffer. The stuff string contains any combination of the following, separated by commas:

1. STRINGS enclosed in quotation marks

2. NUMBERS defining keys using the same numbering scheme as that reported by the INKEY(function CHARACTERS which are converted directly (all keyboard characters permitted except 0-9, which are interpreted as numbers)

There are two special characters. The termination character for a string is the number 254, and the character to respond to a child program's "clear keyboard buffer" command is the number 253. (Some programs, such as Lotus 1-2-3, begin by clearing the keyboard buffer one or two times; the 253 is required to allow the balance of the stuff string to survive this command.)

Here is an example:

STUFF "name junk3",13,10,328,254

This sequence passes the string name junk3 followed by a carriage return (13), a linefeed (10), an <> (328), and a string terminator (254). The maximum number of characters that can be passed through the stuff string is 120. Exceeding this limit may cause unpredictable results.

Examples:

1>STUFF FILE stuffinp.txt
1>ROLL c:\util\pe2.exe f:\wp\junk
1>STUFF STRING "name junk3",13,10,328,254
1>ROLL c:\util\pe2.exe f:\wp\junk
1>STUFF
1>ROLL c:\util\pe2.exe f:\wp\junk

SUM

Sum numeric expressions for selected records.

 SUM <scope> <num exp list> [TO <memvar list> [FOR <cond>]

 <num exp list>    the numeric expressions to sum

Options:

<scope>           select by scope (default scope: ALL)
 <memvar list>     store the results in these memory variables
 FOR <cond>        select by condition

The command SUM adds up numeric expressions for selected records of the selected data file. Up to 10 expressions can be summed with one command. Optionally, the results can be stored in numeric memory variables; the expression list and the numeric memory variable list must have the same number of entries. <memvar list> cannot contain numeric matrix variables.

Records flagged as DELETED are not summed. See also AVERAGE, COUNT, MIN, and MAX.

Example:

The total payroll of the company presently, and after a 5% raise:

1>USE employee
1>SUM salary, salary*1.05
      6 SUM(S)
191980 201579
1>SET TALK OFF
1>SUM salary,salary*0.05 TO sal,salincr
1>? sal,salincr
191980 201579

SUM returns the sum requested only, even though it displays the number of items SUMmed. If you need the command to return the number of items SUMmed, plus the SUM itself, it's necessary to change the operation slightly:

1>SUM IFF(state='NY',1,0)

This command will return the sum of all quantities for transactions where quantity is greater than 500, and a count of all records where STATE='NY', thus combining two separate commands (SUM FOR and COUNT FOR) into one.

TEXT

Send text to screen or printer. Optionally incorporate variables as macros.

TEXT <file>/.<volume>/M.<memo>

Options:

 <file>    the name of the text file to use
 <volume>  the number of a volume in the current library; a    
             numeric constant
 <memo>    the name of a field of type M (MEMO) in the current 
             data file

The TEXT command has two forms. The first form is the TEXT/ENDTEXT program structure:

TEXT
   
ENDTEXT

The variables within the text block can be read in several ways, e.g.: EDIT OFF BROWSE [OFF] READ

All lines following the TEXT command up to ENDTEXT are displayed on the screen or if the command SET PRINT ON was given, then also sent to the printer.

The second form is:

TEXT <filename>/.<volume>

where the text is taken from the file <filename> (default extension TXT) or from the numbered volume in the current library (see SET LIBRARY TO command). This is the same as

TEXT
   the text from <file> or .<volume> or M.<memo>
ENDTEXT

The second form is preferable in many circumstances, since it:

1. Keeps the size of the program module down

2. Allows manipulation of the text in <file> or in .<volume>

3. Allows the choice of text to be used, since <file> can be a macro, and <volume> can be a numeric expression

Note that library volumes are addressed by placing a period in front of the volume number, which can be either a numeric constant or a numeric expression. Do not confuse this usage with a decimal designation.

Formats in TEXT.

TEXT formats let you control the display on fields and variables used in TEXT macros. They are similar to the formats used in the PICTURE and USING clauses of the @ command (see @ for format rules and examples).

In TEXT blocks and files, formats must appear at the beginning of the block, with a separate line for each formatted variable. Each line must begin with two periods and a space, followed by the name of the field or variable, a comma, and the format picture.

Examples:

.. cust,!!!!-!-99
.. today,99/99/99
.. balance,$$$$$$$$$9,99
.. price,$$,$$$.99
.. codes#3,' xxx xxx xxx '
.. exception,'First: "xxxxxxxxxx"'

Format lines may NOT contain comments, NO leading spaces, NO quote marks unless the format itself includes leading or trailing blanks (not recommended) or quote marks of the other type; see last two examples above.

If a field is not in the selected data file, be sure to use field redirection as in CODES#3 above.

Effect of SET TEXT ON/OFF and CLEAR GETS.

A Get Table with room for up to 64 gets is available for full-screen editing commands, like READ, EDIT, and BROWSE. Whenever a GET is issued (either by TEXT or @ GET), it is entered into the Get Table so that Shark can rapidly ascertain its position and format during later processing.

When SET TEXT ON, the TEXT display macros created with & and # are put into the Get Table. This setting is usually required for input screens created with TEXT.

When SET TEXT OFF, display macros are not put into the Get Table. This setting is required when using TEXT for printer output, as in mail-merge programs, to avoid trying to create a 65th entry in the Get Table. Over- filling the Get Table is an error that causes termination of a program.

It is good practice to place a CLEAR GETS command before the TEXT command to ensure that the Get Table is empty before starting to fill it again.

Examples:

1. A text file used in data input with EDIT TEXT (see screen output in

EDIT command section):

.. zip,!9! 9!9 .. phone,999-9999 (999) .. wphone,999-9999 (999) .. training,99/99 NAME........... %FNAME %NAME ADD_1.......... %ADD_1 %AREA ZIP............ @ZIP PHONE.......... @PHONE WPHONE......... @WPHONE EXPERIENCE..... @EXPERIENCE COMMENTS @COMMENT1 @COMMENT2

2. A program that does formatted output from a data file, including multi-line output from certain fields:

SET PRINT ON
SET TEXT OFF
SET MARGIN TO 0
SET WIDTH TO 80
IF row()>1                     ;if current row not at top of form,
   SPOOL junk                  ;  eject into throw-away spool file
   EJECT
   SPOOL
ENDIF
USE customer INDEX customer
page=1
PERFORM heading
DO WHILE .not. eof
   IF ROW()>50                  ;start new page if past line 50
      EJECT
      PERFORM heading
   ENDIF
   nameline=TRIM(fname)+' '+TRIM(name)
   address=TRIM(addr:1)+' '+TRIM(addr:2)+' '+TRIM(city)
   remarks=comments
   nameline2=WRAP(nameline,15)  ;WRAP( function trim long strings,
   address2=WRAP(address,17)    ;  leaving remainder for next line
   remarks2=WRAP(remarks,20)
*  text for main line includes customer number, formatted with picture
   TEXT
.. cust,xxx-x-xx
#cust    #nameline2      #address2         #remarks2
   ENDTEXT
*  test in next line depends on fact that concatenating several fields
*    of blanks and then trimming the result leaves a single blank
   DO WHILE ' '<>TRIM(nameline+address+remarks)
      IF ROW()>55               ;start new page if past line 55
         EJECT
         PERFORM heading
      ENDIF
      nameline2=WRAP(nameline,15)
      address2=WRAP(address,17)
      remarks2=WRAP(remarks,20)
*     text same as main text except customer number omitted
      TEXT
         #nameline2      #address2         #remarks2
      ENDTEXT
   ENDDO
   ?                           ;skip line after every customer
   SKIP                        ;get next customer record
ENDDO
EJECT
SET PRINT OFF
*
PROCEDURE heading
   ? DATE(full)
   ?? BLANK(52-col()),'Page '+LTRIM(STR(page,5))
   ? CEN(:COMPANY,60)
   ? CEN('Current Customer Listing',60)
   ?
   ? 'Number   Name            Address           Comments'
   ? '======== =============== ================= ===================='
   ?
   page=page+1
ENDPROCEDURE heading
*
PROCEDURE heading
   ?
   ?? DATE(full)
   ?? BLANK(52-col()),'Page '+LTRIM(STR(page,5))
   ? CEN(:COMPANY,60)
   ? CEN('Current Customer Listing',60)
   ?
   ? 'Number   Name            Address           Comments'
   ? '======== =============== ================= ===================='
   ?
   page=page+1
ENDPROCEDURE heading

Sample output:

Saturday, March 31, 1998                             Page 1
                  Computer Resellers Corp.
                  Current Customer Listing

Number   Name            Address           Comments
======== =============== ================= ====================
ALB-A-65 Arthur          876 Main Street   Develops LAN-based
         Albredge        Suite 987A San    software
                         Francisco
BRO-W-53 Walter          Freeridge         Hard-disk
         Brownstone      Company 8765      controller and
                         Corvis Drive San  cache expert
                         Jose, CA

TEXT HANDLING:

TEXT MACROS

Contents of fields and variables can be merged into text blocks for data input, reporting, listing and mail-merge applications. Shark provides four special macro symbols for this purpose as follows:

                                Fixed position    Floating position
   Input macros (display/edit)         @                   %
  Output macros (display only)         #                   &

When a text macro symbol is encountered, Shark does the following:

1. Checks whether the following characters are the name of a field in the selected file. If it is, the current contents of the field replaces <&var> in the text.
2. If not a field name, then the characters following the macro symbol are assumed to be a memory variable name. If that name is valid, the contents of the memory variable replaces <var> in the text.
3. If <var> is neither a field nor a variable, it is assumed not to be a macro, and both the macro symbol and <var> are output as a literal.

When the macro symbol & is used and SET TRIM ON, <var> is trimmed before it is merged. The position of all text to the right of <var> in the same line is adjusted so that the number of spaces after <var> in the output is the same as in the TEXT, no matter how wide <var> is.

Caution: In a TEXT macro, <variable> must be terminated by blank, tab, punctuation mark, or a macro symbol; it cannot be terminated by a graphics character (since in many non-English character sets these characters are normal or accented alphanumeric characters). It also cannot be terminated by a colon or an underscore, since these are valid parts of a field or variable name.

OUTPUT PROCESSING

The TEXT command can be used to do output or list processing.

Any variable (field, memory variable, or system variable) can be merged into the document and output by using &<var> or #<var> in the text.

As described above, the & macro will trim the contents of <var> when output when SET TRIM ON, and always adjusts the material to its right on the same line depending on the width of the contents of <var>. Sometimes, it is more useful to output at an absolute location with a variable (as opposed to merging); to do this use the #<var> form. #<var> does not trim or adjust the position of other items on the line, creating the possibility that later items in the line may be overwritten.

A paragraph is a portion of the text between two carriage returns (obtained by hitting <ENTER>). A paragraph is formatted by the TEXT command using word wrap (if there is not enough room for a word on a line, it is displayed/printed at the start of the next line). The page width and the left margin are set by the SET WIDTH and the SET MARGIN commands (see SET WIDTH and SET MARGIN).

Control codes can be sent from the text using the symbols ^ (caret) and \ (backslash).

The caret. When Shark comes across a ^, it checks for the next character. If the next character is also a ^, the two characters are sent as a single ^. If the next character is not a ^, it is sent as a control character; for instance, ^C is sent as Ctrl-C.

Examples for ^:

         ^^        sent as ^
         ^C        sent as Ctrl-C
         ^^C       sent as ^C

The back slash. When Shark comes across a \, it checks for the next character. If the next character is also a \, the two characters are sent as a single \. If the next character is not a \, Shark checks for digits; it grabs as many digits as there are, up to three. The digits are converted into a number, and the number is sent as a code between 0 and 255.

Examples for \:

         \\        sent as \
         \2b       sent as code 2, followed by b
         \0020     sent as code 2, followed by the character 0 (002 is the 2)
         \27x\000  sent as code 27 (escape), x, code 0

Examples:

TEXT
This text will be sent to the screen or the printer.  You can set the left
margin and the text width.  The text is automatically word wrapped.
ENDTEXT

Now the same with prepended printer control codes:

TEXT
\27x\001This text will be sent to the screen or the printer.  You can set the
left margin and the text width.  The text is automatically word wrapped.
ENDTEXT

INPUT SCREENS

The TEXT command can be used "to paint" input screens. @<var> is a GET, activated by a READ command.

@<var> also has a floating-position form, %<var>, which adjusts the material to its right on the same line depending on the width of the contents of <var>.

Neither @<var> nor %<var> trims the present contents of the variable.

Examples:

TEXT
     @fname              @name               @dept
ENDTEXT
TEXT
     %fname  %name  %dept
ENDTEXT

Both create a one-line input format that can be used with BROWSE OFF (or, if the macro line is placed in a text file, with BROWSE TEXT. The second form is easier to use, since there is no concern about the width of the various fields. For example, the maximum width available for NAME in the first form is 20 characters; if it is 20, it runs into DEPT, and if more than 20, it will suppress DEPT input completely.

TOTAL

Summarize the information from the selected file (indexed) to a new file.

TOTAL <scope> ON <str exp> TO <file> [FIELDS <field list>]
      [FOR <cond>]

<str exp>    trigger expression
<file>       new file to contain summary information

Options:

<scope>               selection of records by scope
                           (default scope: ALL)
FIELDS <field list>   the fields to be totalled
FOR <cond>            selection of records by <cond>

The selected file must be indexed or sorted on <str exp>. The records of the selected file can be grouped by the value of <str exp>: in each group <str exp> has the same value.

This command creates a new file <file>; for each group of records of the selected file, a record is entered in the new file.

This new record is the same as the first record of the group, except that the numeric fields in the <field list> are replaced by their total for all the records in the group. (Specifying a logical or a character field in the <field list> will cause an error.)

Deleted records are ignores irrespective of SET DELETED command.

The following steps describe in detail how this command works:

Step 1. Copies the structure of the selected file to <file>.
Step 2. Appends the first record which satisfies the FOR clause (note also scope, deleted records are disregarded) from the selected file to the new file.
Step 3. Evaluates <str exp> and saves it in a temporary variable.
Step 4. Takes all subsequent records (if any) for which <str exp> does not change. Adds up the fields in the FIELDS clause (if any) and stores the sum in the record appended to <file> while <str exp> continues to match the value saved in the temporary variable.
Step 5. Continue with Step 2, using the first record for which <str exp> has a new value.

If no FIELDS clause is in the command line no addition is performed, and the resulting file consists only of the first record encountered for each different value of <str exp>. A frequent use of this feature is to purge the file of records with duplicate keys.

See also the related commands: POST and UPDATE.

Example: Use the ORDER file to find out which STYLE:NO and COLOR have been ordered:

1>USE order
1>LIST style:no+color
      1  A120B1
      2  C001R3
      3  M100G5
      4  A120B1
      5  M100G5

Of course, this way you get a lot of duplicates. To get each STYLE:NO+COLOR only once, make the file STYLESUM (style summary) with TOTAL:

1>INDEX ON style:no+color TO order
      5 RECORDS IN TOTAL INDEXED
1>TOTAL ON style:no+color TO stylesum
      5 TOTAL(S)
1>USE stylesum
1>LIST inven:no, style:no, color
      1  AB0011 A120 B1
      2  AB0110 C001 R3
      3  QA1001 M100 G5

This is the desired list.

UNLOCK

Unlock the current record.

UNLOCK

This command unlocks the current record previously locked. See the SET NETWORK command on how to get into the multi-user mode. See also LOCK.

Example:

mcust=cust
FIND &mcust
LOCK
REPLACE balance with 0
UNLOCK

UNLOCK INDEXES

Unlock all indexes on the selected data file.

UNLOCK INDEXES

This command unlocks the indexes previously locked on the selected data file with the LOCK INDEXES command.

See the SET NETWORK command on how to get into the multi-user mode. See also LOCK INDEXES.

Example:

UNLOCK INDEXES

UPDATE

Update the selected file from an indexed file by replacing selected fields.

UPDATE FROM <scope> <file number> ON <str exp> [REPLACE <field1>]
      WITH <exp1>,..., WITH  [FOR <cond>]

<file number>     the location of the FROM file
<str exp>         the expression that is the key for finding
                      the record in the FROM file

Options:

<scope> selection restricted by scope (default scope: ALL) REPLACE <field1> WITH <exp1>,..., WITH where field1,..,fieldn are fields of the file in use <exp1>,..., are expressions involving fields of both files FOR <cond> selection restricted by <cond>

The selected file need not be indexed. This procedure takes all the appropriate records of the selected file one at a time.

The FROM file has to be indexed by <str exp>; the expression, <str exp>, is made up of character fields shared by the two files, and by memory variables and constants.

This procedure works as follows:

1. Takes the first appropriate record (that is, the first non-deleted record satisfying the <cond> and within the scope).
2. Evaluates <str exp> in the selected file.
3. Finds the first matching record in the FROM file.
4. If the FIND is not successful, an "UPDATE ERROR" message is sent showing both the record number and the value of <str exp> in the selected file. If SET PRINT ON, messages are sent to the printer.
5. If the FIND is successful, the procedure replaces the fields of the selected file with the expressions, <str exp>, made up of fields of both files. All fields names are assumed to be in the updating file, so make sure #n is attached to any field names from the FROM file.
6. Procedure continues with the next appropriate record as long as records remain within the <scope>.

If there is no REPLACE clause, UPDATE simply checks whether all the expected records of the FROM file are present.

See also the commands: POST and TOTAL. SET ADD ON has no effect on UPDATE.

Example:

The cost of an item is kept updated in the INVENTRY file. To update the COST in the ORDER file:

1>USE#4 inventry INDEX inventry
1>USE order
1>UPDATE FROM 4 ON inven:no REPLACE cost WITH cost#4

USE

Open data file for use, optionally, with index files.

 USE <file> [INDEX <file list>][ <mode>] [COMPILE]

 <file> the data file to use

Option:

 INDEX <file list>    list of index file names to use
 <mode>               the file access mode under which DOS is to
                           open the file
 COMPILE                   open data file at compile time only

The command USE opens a data file for use. To open one or more index files with the data file, use INDEX and the index file name(s). The first index file is the Master Index; this one is in use with the FIND, LIST, SKIP, etc. commands. All other index files named will be updated by all commands.

The option COMPILE is used to open a data file at compile time only. It is used in situations where the data file to be used at run time is not available at compile time. One remedy is to put the name of the data file in a macro, but then all the field names must be in macros. COMPILE offers a better solution if a data file with the same structure is available at compile time. For example,

USE inven COMPILE         ;you may also say "USE inven READ"
USE &file INDEX &file2

will open the data file INVEN at compile time only. At compile time the command: USE &file index &file2 is ignored. Now if the structure of INVEN is the same as the structure of the data file(s) whose name will appear in &file, then the program can use the field name without macros. Note that index files are not opened at compile time, so the same problem does not effect index files.

Caution: Avoid using data and index file names that start with the letters "COMP", since the compiler may mistake the file name for the COMPILE keyword and make it impossible to use the file in a program.

Shark supports four different modes (READ, WRITE, LOCK, and SHARE). The meaning of the four modes is as follows:

LOCK - Open the file for both reading and writing, and maintain exclusive use; allow no other users on a network to read or write to the file while it is open in LOCK mode. This is the default mode for all versions.

WRITE - Open the file for both reading and writing, and allow no other users on a network to write to the file, but allow other users to open the file in READ mode.

READ - Open the file for reading only, without restricting other users on a network from opening it in WRITE or SHARE mode. When not on a network, READ mode is useful in ensuring that changes made to a file are not saved to disk.

SHARE - Open the file for both reading and writing, without restricting the ability of others on a network

See also SET INDEX TO.

Examples:

1. To open a data file as file 5 while currently you are on file 2:

2>USE#5 customer
2>USE#2 invoice INDEX invoice
2>USE#1 sales INDEX color,style,ddate

Three data files were opened under the appropriate file numbers. Note that the default file number is still 2; the index files are separated by commas.

2. To open a file in READ mode before using EDIT to check data without the risk of writing any changes back to disk:

1>USE employee INDEX emplname READ
1>FIND TAYLOR
1>EDIT

VARIABLES

Enters a list of memory variable names into the variables table.

VARIABLES <variables list>

<variables list> indicates a list of memory-variable names

Shark allows up to 128 variables to be defined at a time. Their names are listed in a variables table, which is displayed with the LIST MEMORY command.

When a program is compiled, each time Shark encounters a name not already in the table, it is added. As a programmer, you can control the order of variables in the table by naming them in the variables list with the VARIABLES command. This is not only good practice in general, but it can help in debugging, and makes it possible to be sure every variable you use is being defined, and that no others are being inadvertently created. When you are finished with a variable, you can let it go with the RELEASE command:

RELEASE <variables list>

The variables command should never be used in a subroutine, and can be used only once in the main routine. It should come after any GLOBAL command, but before any other variable is defined.

Example in a program:

VARIABLES start,finish,mcust,mserial

WAIT

Accept one character from the keyboard.

WAIT [TO <memvar>]

Option:

TO <memvar>    store the character into this variable

When Shark encounters the WAIT command, the program execution stops, the message: WAITING is displayed; Shark waits for a character to be entered at the keyboard. When a key is hit, program execution continues.

If the option: TO <memvar> is used, the character is stored in the string memory variable <memvar>; this cannot be a matrix variable. If the variable <memvar> does not exist, it will be created.

This command is useful to suspend the program execution so that the user can read a message on the screen, and maybe make a choice.

See also the INKEY( function which waits for input without displaying the "Waiting" message.

Examples:

1. A program segment:

@ 20,0 SAY 'Turn the printer on. Hit any key when ready.'
WAIT

After the message is displayed, Shark waits for the user to hit a key indicating that the printer is now on.

2. A typical, simple menu using WAIT:

DO WHILE T
ERASE
TEXT
                            MENU

      1. General Ledger
      2. Invoicing
      3. Receivables

                    Type in your choice:

ENDTEXT
WAIT TO ans
IF ans>'0' .OR. ans<'4'
BREAK
ENDIF
ENDDO
DO CASE
CASE ans='1'
DO ...

See MENU( function for a better method of doing menus

On the other hand, INKEY() makes a more attractive screen than the WAIT command:

CLS
@ 2,0 SAY "The following items will be included in your TOTAL:"
@ 3,0 
LIST PERD,T1,T2,T3,T6,T9,P OFF
?
? "Press <Enter> to continue, or press <Esc> to return to menu"
A=INKEY()

WINDOW

Defines the active window, that part of the screen to which relative output can be sent.

WINDOW

 
WINDOW <row1>,<row2> [COLOR <windowcolor>,<bordercolor>]
WINDOW <row1>,<col1>,<row2>,<col2> [COLOR <windowcolor>,<bordercolor>] [BLANK/DOUBLE]

 <row1>,<row2>         the top and bottom of the window to be created; with no 
                       column numbers given, the window is full width with no 
                       border permitted
 <row1>,<col1>    the coordinates of the top-left corner of the window
 <row2>,<col2>    the coordinates of the bottom right corner of the window

Options:

 
 COLOR <windowcolor>   the color of the area inside the window
       <bordercolor>   the color of the window border
 BLANK                      the window has no border
 DOUBLE                     the window double-line borders (default single-line borders)

Unlike the BOX command, WINDOW erases the area within the coordinates given, and if corners are specified, displays an optional border one space outside the border coordinates.

Although the fixed-position display commands like @ SAY can write either inside or outside the window, all the relative display commands like ?, ??, LIST, DISPLAY, TEXT, etc., are restricted to the active window.

The window can be deactivated (i.e., reset to the entire screen size) by the WINDOW command alone.

The rows are numbered 0 to 24. Since a row is always allowed above and below the window coordinates, the actual range of row numbers for the WINDOW command is 1 through 23.

The columns are numbered 0 to 79. Since a column is always allowed to the left and right of the window coordinates, the actual range of column numbers for the WINDOW command is 1 through 78.

Note that commas are required between coordinates, but are not permitted before the keywords COLOR, BLANK, and DOUBLE.

In programs, WINDOW is often used to position TEXT and may be useful in setting up BROWSE, EDIT, WRITE and other input/output displays.

Examples:

1. Use WRITE to edit a file in the bottom half of the screen:

CLS
CURSOR 5,20
ACCEPT "Enter name of file to edit " to fil_nam
WINDOW 8,5,22,74 color 7,112 double
WRITE &fil_nam OFF
WINDOW

2. Use BROWSE with a TEXT file in a window:

USE customer
WINDOW 2,22 color 112
BROWSE TEXT customer
WINDOW

WRITE Program Editor

The built-in WRITE editor is a simple built-in WordStar-type program editor for working on small Shark text and program files. It cannot handle files bigger than 20000 characters (about 18k), but it is still useful for locating and fixing run-time errors since it is designed to go to the location where the program fails at run-time. It actually goes to the line where the code fails, but in most cases that is close enough to find the error.

The WRITE command activates the program editor:


WRITE <file>

Options:

<file>     name of file to be created or edited
<volume>   number of a volume in the current library; a numeric
                expression
OFF             omit header and opportunity to rename file or volume

Example:

WRITE <file>.<volume> [OFF]

If <file> or <volume> is not specified, the last file used is understood to be the file to edit. If no extension is specified, PRG is assumed. This editor is very useful for debugging programs and reports. If a program fails to run, typing WRITE <Enter> takes you to the location of the error.

Note that library volumes are addressed by placing a period in front of the volume number, which can be either a numeric constant or a numeric expression. Do not confuse this usage with a decimal designation.

OFF causes WRITE to omit the top three lines of the screen (file name and ruler, etc.) and places the cursor at the beginning of the file in the top left corner of the current window (the entire screen if no window is active), and to save the file immediately upon sensing the <End> key without giving an opportunity to change the file name. WRITE OFF is used primarily inside programs under program control, and with an active window.

The editing keys are the same as in full-screen editing. WRITE uses an 80 character "window" for its 254 character lines.

Using data and index files reduces space available for WRITE, as does running WRITE inside a program; consider running WRITE from a subroutine instead of the main routine if maximum file size is required.

Editing keys: The following is the WRITER help screen, displayed by pressing Alt-H when editing in WRITER :

                           SharkBase WRITER HELP                              
                                                                             
Delete and Insert              Block Commands            Miscellaneous       
=================              ====================      ====================
delete character..... Del      Mark block.... Alt-B      QUIT:               
delete to end of line  ^Y      Move block.... Alt-M      with save.... End, or ^W
                               Copy block.... Alt-C      without save.  ^Q
delete line..........  ^T      Delete block.. Alt-D                          
insert line..........  ^N      Remove marks.. Alt-K      PRINT TEXT...  ^P   
                                                                             
insert-mode toggle... Ins      tab.......... TAB Key     FORMAT PROGRAM Alt-F
                                                                             
 +------------------------  FAST CURSOR MOVEMENT   --------------------------+
 |  end of line... ^Right Arrow   page up....... PgUp  top of text... ^Home  |
 |  start of line. ^Left Arrow    page down..... PgDn  bottom of text ^End   |
 +---------------------------------------------------------------------------+


NOTES:  1. ^ is Ctrl  2. Keys in pointed brackets are on the Numeric Keypad

<Left> or Ctrl-S   moves the cursor back one character
<Right> or Ctrl-D  moves the cursor forward one character
<Up> or Ctrl-E     moves the cursor to the previous line
<Dn> or Ctrl-X     moves the cursor to the next line
Ctrl-<Left>        moves to the beginning of the line
Ctrl-<Right>       moves to the end of the line
Ctrl-<Home>        moves to the beginning of the document
Ctrl-<End>         moves to the end of the document
Ctrl-N             inserts a new line
Ctrl-T             deletes the line
<PgUp> or Ctrl-R   displays previous page
<PgDn> or Ctrl-C   displays next page
<BACKSPACE>        deletes the character to the left of the cursor
<Del> or Ctrl-G    deletes the character on the cursor
Ctrl-Y             deletes the rest of the line
<Ins> or Ctrl-V    puts you in insert mode: what you type gets
                   inserted  (normally, you are in overtype mode:
                   what you type overtypes the existing text); pressing
                   <Ins> or Ctrl-V again, puts you back into overtype
                   mode
<End> or Ctrl-W    quits and updates text
Ctrl-Q             quits and does not update text
Ctrl-P             prints entire document on printer
Alt-F              formats program
Alt-H              displays WRITER HELP screen (above)

To break a line into two, press <Ins> to get into insert mode, and press <ENTER>. To merge two lines, delete the end of line character. When you leave the line (with a cursor key or <End>), the two lines merge.

Alt-F formats program files; it indents the lines according to the program structures and capitalizes the first command verb on every line.

When using WRITE, Alt-H displays a screen of information (press any key, and the help screen disappears).

Examples:

1>WRITE test             ;write TEST.PRG
1>WRITE test.txt         ;write TEST.TXT
1>WRITE test.dat OFF     ;write TEST.DAT with suppression of header
1>WRITE .65              ;write volume 65 in the current library
1>WRITE .num             ;write volume number contained in NUM in the current
                          library
1>WRITE .num OFF         ;write volume number contained in NUM in the current
                          library with suppression of header
1>WRITE .:avail          ;write the next available volume (Caution: be sure to
                          capture this value before using this construct or
                          you'll never be able to find your text again.)

ZAP

Erase all records in the selected file.

 ZAP

This command erases all the records. This is not a DELETE. The records cannot be recalled! Use this command with care!

If the selected file is indexed, it is automatically reindexed after ZAP.

ZAP releases the disk space previously used by the records of the data file.

On a network with SET NETWORK ON in Shark Network Edition, attempting to ZAP while another user is accessing the file will cause a LOCK error. Always LOCK the file before ZAP.

Example:

1>USE employee
1>COPY TO empl1
1>USE empl1
1>ZAP

COMMAND & FIELD REDIRECTION

The # symbol can be used to redirect a single command or field to a data file other than the selected file.

To redirect a command, follow the first word of the command with the # symbol and the file number; e.g.:

USE#2 members INDEX memno

This command opens the "members.dbf" as file 2, without changing the selected file number. When command verbs consist of more than one word, the redirection operator is appended to the first word:

LIST#2 STRUCTURE

Redirection can also be used with field names in a list, e.g.:

DISPLAY trans_no#4, mem_no#2, inven_no#3

displays fields from the current records of three separate data files.


[ End of Shark Commands ]