Shark Reference Manual
*

Shark Reference Manual

A brief history: This language was first released in 1983 by Sub Rosa Inc as dCOMPtm. It was revised and released as MAXtm in 1985. Following the MAXtm release, it was revised and renamed VP-Infotm by Paperback Software in 1986. In 1992, the Clippertm-compatible (file and index) network edition was released by Sub Rosa Publishing Inc under the name SHARKtm.

Shark is available as freeware, and it runs on any version of MS-DOS, PC-DOS, or DR-DOS. On later Windows and Linux machines, Shark runs nicely using a DOS emulator such as DOSbox with one exception: DOSbox prints only to a device (LPT1, for example) or to a file, like MS-DOS. Since Linux and later versions of Windows don't print to a device, printed output can only be directed to a file. In most cases, this is not a major problem since the output file can be printed from Windows (or Linux).

© Sub Rosa Inc 1992
© Intelligent Webware Partnership 2003

The following topics constitute a Table of Contents for this on-line manual for the SHARKtm dbf language. The topics contain the core abilities of the language, plus sample code and advice. Clicking on each topic will cause a jump to a detailed explanation of the selected topic.


Configuration:
System Variables:
Commands:
Functions:
Mathematical Functions
Color Attributes
Command and Field Redirection
Date Output Formats
Date Input Formats
Editing Keys
Format Strings
Get Tables
Macros
Relations
Operations
Constants
Text Handling
Error Messages
Write Program Editor

Commands:


* (comment)
= (equal)
?
@ (at)
# (number)
ACCEPT
APPEND
APPEND BLANK
APPEND FROM
APPEND TO
ARRAY or MATRIX
AVERAGE
BINLOAD
BINSPACE=
BINUNLOAD
BOX
BREAK
BROWSE
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
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 FROM
INPUT
KEY
LAST
LIMIT
LIST
LIST FILES
LIST MEMORY
LIST STRUCTURE
List SYSTEM variables
LOCATE
LOCK INDEXES
LOCK
LOOP
MATRIX or ARRAY
MAX
MEMORY=
MIN
MODIFY
NEAREST
NOEFFECTS
NOTE
NOUPDATE
ON ERROR
ON ESCAPE
ON FIELD
ON KEY
OTHERWISE
OVERWRITE TO
PACK
PERFORM
POST
PROCEDURE
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 NETWORK [N]
SET PRINT [ON][OFF]
SET RELATION
SET VIDEO
SET WIDTH
SETS (miscellaneous)
SKIP
SORT
SOUND
SPOOL
STATUS
STORE
STUFF
SUM
TEXT
TOTAL
UNLOCK INDEXES
UNLOCK
UPDATE
USE
VARIABLES
WAIT
WINDOW
WRITE (WRITE command and the WRITE editor)
ZAP

Functions:


A function is just like an operation; the addition operation (+)
requires two arguments (numbers) and returns their sum; a function requires
some arguments (0 to 3) and returns some value.

Every function has a type: numeric, string, or logical, depending on
the values it returns.

A function has arguments; the values put into the function between the
parentheses, separated by commas.  Shark functions have at most three
arguments; a few have none.  Some arguments may be optional.

The arguments can be variables or expressions of type string: str var
or str exp, or of type numeric: num var or num exp.  (Expressions are
discussed in Section 3.5)

These are the available Shark functions:
!(
$(
@(
ABS(
ACOS(
ASC(
ASIN(
ASTERISK (*)
AT(
ATAN(
BIT(
BLANK(
BOF
BOF(
CEIL(
CEN(
CHR(
CLOSE(
COL(
COS(
COSH(
CTONUM(
DATE(
DAYS(
DBF(
DBFX(
DELETED(
DESCEND(
DIR(
DIRF(
DIRX(
EOF
EOF(
EXP(
FIELD(
FILE(
FLD(
FLOOR(
GET(
IFF(
IFKEY(
IN(
INKEY(
INSERT(
INT(
LEFT(
LEN(
LOC(
LOG(
LOG10(
LOWER(
LTRIM(
MASK(
MAX(
MENU(
MIN(
MOD(
MONTHS(
NDX(
NTX(
NUMTOC(
OUT(
PIC(
POW(
PRINTER(
PUT(
RAND(
RANK(
READ(
RECNO(
REMLIB(
REPLACE(
RESET(
RIGHT(
ROPEN(
ROW(
SEEK(
SET(
SIN(
SINH(
SPACE(
SQRT(
SSEEK(
STR(
SUBSTR(
TAN(
TANH(
TEST(
TIME(
TRIM(
TYPE(
UPPER(
VAL(
WOPEN(
WRAP(
WRITE(

Color Attributes:

The following values are used to select an attribute byte for use with the COLOR and SET COLOR commands.

BACKGROUND ========CHARACTERS========= BLINKING BRIGHTNESS
(color only) (color) (monochrome)
---------- ---------- ---------------- ---------------- ----------------
0 - black 0 - black 0 - normal 0 - no blink 0 - normal
16 - blue 1 - blue 1 - underline 128 - blink 8 - bright
32 - green 2 - green 112 - reverse
48 - cyan 3 - cyan
64 - red 4 - red
80 - magenta 5 - magenta
96 - brown 6 - brown
112 - white 7 - white

Color Examples:

SET COLOR TO 20 Sets default attribute to red on blue (4+16)
COLOR=31 Sets DEFAULT attribute to bright white on blue (15+16)
COLOR 36,2,0,12,79 Changes rows 2-12 to red on green (4+32)

COMMAND AND 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.

DATE OUTPUT FORMATS

These are the output format numbers for use with the DATE() function.

Number Name      Display

   1    YMD       yymmdd (6 characters: 990601)
   2    MDY       mm/dd/yy (8 characters: 06/01/99)
   3    CHAR      Month name, day, year (variable length: June 1, 1999)
   4    FULL      day of week, month name, day, year (variable length:
                  Sunday, June 1, 1999)
   5    Lchar     Last day of month (variable length: June 30, 1999)
   6    DMY       dd-mmm-yyyy (11 characters: 01-JUN-1999)
   7    VARIABLE  Format determined by the SET DATE command (variable length)
   8    LONG      yyyymmdd
   9    LAST      yymmdd or yyyymmdd, depending on format specified with
                  SET DATE

Date information can be further enhanced by using the PICTURE format.

Example:

1>? date(8) ; i.e. LONG date format
20031205
1>? date(8) pic("XXXX.XX.XX)
2003.12.05


DATE INPUT FORMATS

These are the valid formats for date strings used with the DATE(,
DAYS(, and MONTHS( functions:

          FORMAT        EXAMPLE (09/17/91):
          mmddyy           091791
          ddmmyy           170991
          yymmdd           910917
          mmddyyyy         09171991
          ddmmyyyy         17091991
          yyyymmdd         19910917

Optionally, use a hyphen, slash or space to separate elements of the
date input string (e.g., 07-04-91, 12/25/91, 03 11 91).  If a date string
entered for the DATE() function is ambiguous (e.g., the string "110391"
could be March 11 or November 3), Shark reads the string according
to the format set by the SET DATE command.

Date INPUTS are prone to errors, so it's better to firmly format all date
inputs using @...SAY...GET...READ constructs.

EDITING KEYS

Use these editing keys to edit field contents during APPEND, EDIT,
and BROWSE.

Except as noted, these commands work identically with the above commands:
Moving the Cursor

     Within a field:  Left arrow or Ctrl-S    (one character left)
                      Right arrow or Ctrl-D   (one character right)
                      Ctrl-Left arrow         (to beginning of field)
                      Ctrl-Right arrow        (to end of field)
     Between Fields:  Up arrow or Ctrl-E      (to previous field)
                      Down arrow or Ctrl-X    (to next field)
                      ENTER                   (to next field)
     Between pages:   Ctrl-K                  (to previous page)
                      Ctrl-L                  (to next page)
     Between records: PgUp or Ctrl-R          (to previous record-EDIT/BROWSE)
                      PgDn or Ctrl-C          (to next record)
Entering and Editing Data
                      INS or Ctrl-V           (toggles insert/overwrite modes)
                      DEL or Ctrl-G           (deletes character at cursor)
                      BACKSPACE or Ctrl-H     (deletes character to the left)
                      Ctrl-Y                  (deletes to end of the field)
Saving and Ending
                      END or Ctrl-W           (save changes and end)
                      Ctrl-Q                  (cancel changes to this record)
Other keys
                      Ctrl-U                  (toggles deleted flag status)
                      Ctrl-HOME               (move to top of file)
                      Ctrl-END                (move to end of file)
                      Ctrl-PgDn               (append a new record)
                      Alt-E                   (skips backward in file as many
                                              records as can be displayed in
                                              current window - BROWSE)
                      Alt-X                   (skips forward in file as many
                                              records as can be displayed in
                                              current window - BROWSE)

FORMAT STRINGS

Format strings determine how numbers and strings are displayed.  Format
strings are used in the PICTURE clause of @...GET, in the USING clause of
@...SAY, in the format lines in a TEXT block, in the REPORT keyword PICTURE,
in the PIC() function, and in the system variable :PICTURE.

Format strings don't affect how Shark stores information; only how it is
entered, displayed, or printed.  Format strings are made up of format
characters and background characters.  In most cases (except TEXT and
PICTURE in a report form), format strings are enclosed in quotes.

Format characters work as placeholders for displayed data and as "masks"
to limit the kind of data that can be entered.  There are separate format
characters numbers and strings (listed in the next two help screens).

Background characters are primarily decorative, added to make data easier
to read. They include all characters (including spaces) not listed in the
format character tables.  Background characters are displayed exactly
as they appear in the format clause, but are not stored as data.

NUMERIC FORMATS

These are the format characters for numbers:
  9 -- Displays or permits entry of any digit (0-9), the minus sign (-),
       or a decimal point (.).
  $ -- Displays any digit.  The leading digit of a value
       is preceded by a dollar sign (e.g., 182.34 is displayed as $182.34).
  comma (,) -- Determines placement of commas in a displayed number.
  period (.) -- Determines placement of the decimal point in a display or
       input number.

Any other character in a numeric format clause is a background character
and is displayed "as is".  Here are some display examples (invalid for input):

   Number     Format         Display      Effect
   1123.89    "9,999.99"     1,123.89     Commas added
   100.89     "$9,999.99"    $  100.89    Fixed dollar sign
   100.89     "$$$$$$.99"    $100.89      Floating dollar sign

Rule: Do not use formats for numeric field input; okay for variables.

STRING FORMATS

These are the format characters for strings:

  X or x -- Any typed character.
  A or a -- Any letter, upper- or lowercase.
  9 -- Any digit or letter.
  ! -- Any character, but converts lowercase letters to uppercase.

All other characters are regarded as background characters: they are
depicted literally when displayed and ignored upon input.

GET TABLES

To set up a Get Table, use the @...GET command or the input macros
(@ and %) of a TEXT block to set up the layout of an input screen.  These
commands specify how the input screen will be "painted" and to which fields
or memory variables the entries are to be stored.  These variables are called
Get Variables.  A Get Table can contain as many as 64 variables.

The READ, APPEND/EDIT OFF or BROWSE OFF commands cause Shark to "activate"
the Get Table, allowing the user to view and edit the values of the Get
Variables.  During this time the command sequences in an ON FIELD
structure will execute as the user moves from one Get Variable to another.

The CLEAR GETS command erases the current Get Table definitions, as will
any @...GET commands or text macros executed after the Get Table has been
activated.

See also: READ, TEXT

MACROS


One of Shark's most powerful features is the rich variety of ways in
which macros can be used.  Unfortunately, some users encounter difficulties,
especially in the following areas:

1.  Putting a data file into use with a macro.  This technique requires a
data file to be put into use with the COMPILE keyword or the compiler will
not "know" that a data file is open.  Secondly, users of the file-as-a-vector
technique must reference the file only by the name of the COMPILE file.
See the sample program VECTOR.PRG for an example of these techniques.

2.  Using macros in TEXT blocks.  Only standard variables and fields may be
used as macros in TEXT.  Do not use system variables, matrix variables, or
functions.

3.  Using a macro in a command when what is intended is use of the variable
itself.  Remember:  a macro used in a command always contains the name of a
field or variable, and means that you intend to use the value of that field
or variable in the current command instead of the macro.

4.  Using macros with commands that do not allow their use.  The following
commands may not be used with a macro:

COMMANDS PROHIBITED IN MACROS:

@
CLOSE
CLS
COLOR
DO
DO WHILE
ERASE
FIELD
FILES...ENDFILES
GLOBAL
GOTO
HELP
LOCK
ON
PERFORM
PROCEDURE
SELECT
SET INDEX TO 
UNLOCK
VARIABLES

CONSTANTS


There are three types of constants: numeric, logical, and string.

A numeric constant is a number (the minus sign is a part of it):
12.78
0.00064
-3.14

There are only two logical constants:  T (true, also written as t, Y,
and y) and F (false, also written as f, N, and n).

A string constant is a string in quotation marks:
"This is a character constant."
'This is another one, delimited with single quotation marks.'
"Here's another one, enclosing a single quotation mark (apostrophe) within
double quotes."
"This is incorrect because the quotation marks do not match.'

OPERATIONS

There are three types of operations: numeric, logical, and string.   Each
works with constants and variables of that type, and yields a value of that
type.

NUMERIC OPERATIONS:

The numeric operations are

+     addition
-     subtraction
*     multiplication
/     division
2+3.2          yields 5.2
10/4           yields 2.5

All numeric operations require two numbers to act on.  - is also used to
indicate that a number is negative: -2, -3.14.  Instead of  -QTY, write 0-QTY or -1*QTY.
There are three logical operations:

.AND.
.OR.
.NOT.

.AND. and .OR. take two logical values and yield a logical value:

T.AND.T        yields:  T
T.AND.F        yields:  F
F.AND.T        yields:  F
F.AND.F        yields:  F
T.OR.T         yields:  T
T.OR.F         yields:  T
F.OR.T         yields:  T
F.OR.F         yields:  F

.NOT. takes a logical value and yields a logical value (the opposite):

.NOT.T         yields:  F
.NOT.F         yields:  T

STRING OPERATIONS:

There is only one string operation:

+ (concatenation, i.e. placing one string after another)

'This is a'+' sentence.'

yields the value:

This is a sentence.

Note that one cannot mix numbers and strings:

2+'string'

will give a syntax error message (Error 1, see Appendix C).

RELATIONS


A relation takes two numbers or two strings, compares them, and yields a
logical value (true or false).

There are six relations that compare numbers or strings:

= (equal)

<     less than
<=    less than or equal to
>     greater than
>=    greater than or equal to
<>    not equal

For numbers, these have their usual meaning:

1<2            is true
2<1            is false
1.2<>5         is true
1.2>=1         is true

You should be careful when using = for numbers.  Two numbers may be
displayed as equal while, in fact, they differ in the third or fourth decimal
place.  Instead of

num1=num2

in many instances you could use

ABS(num1-num2) < 0.01
or

(PIC(num1-num2,'9999.99'))=0

For strings, string1=string2 is true if string2 is of the same length as
string1, and the characters of string1 equal the corresponding characters of
string2; if string2 has more characters, string1=string2 is always false.

However, the result of comparing strings of unequal length, in which all
of string2 is exactly the same as the beginning of string1, is affected by the
setting of the "EXACT" switch.  If SET EXACT OFF, then such string1=string2 is
true; with SET EXACT ON, it is false.

Examples:

                 SET EXACT OFF       SET EXACT ON
'abc'='abc'         true                true
'abc '='abc'        true                false
'abc'='abc '        false               false
'abc'='ab'          true                false
'ab'='abc'          false               false

To make sure that two strings are really equal, write
(string1=string2) .AND. (string2=string1)
or SET EXACT ON.

One way of remembering the above rule, is that string1=string2 if FIND
with string2 finds string1.

Although this definition of string1=string2 may at first sight seem
awkward, it may really be quite useful both in conversational Shark
and in Shark programs.  For instance, the condition to select all
customers (field: CUST) whose name starts with P:

LEFT(cust,1)='P' (or less efficiently SUBSTR(cust,1,1)='P')
or cust='P'
if SET EXACT OFF.

For strings, string1 < string2 means: in a dictionary, string1 would come
before string2.  Single characters are compared by their ASCII value, see the
functions CHR( and RANK(.  string1 is compared to string2 by comparing their
first characters; if the first character of string1 is less than the first
character of string2, then string1 < string2;  if they are equal, then the
second character of string1 is compared to the second character of string 2,
and so on.

Examples:

'I am smaller' < 'I am bigger'    is false
'David' < 'david'                 is true
'122' > '17'                      is false
'122' > '017'                     is true
'seven' > '7'                     is true

Note that in the ASCII sequence, all digits, 0 to 9, come before all
upper-case letters, A to Z, which, in turn, come before all lower-case
letters, a to z.

Note that strings and numbers cannot be mixed in these relations:

2 < '123'

gives a syntax error message (Error 1, see list of error messages in
Appendix of Reference Guide).

FUNCTIONS:

!(


Converts a string to upper case.

!(str exp)
str exp the text to be converted to upper case

Type: character

All lower-case letters in the str exp are converted into upper case by
the !( function.  See also the LOWER( function.

Examples:

1>a='Aa12b'
1>? !(a)
AA12B
1>? !('David!')
DAVID!
Note that only the lower-case letters are changed.

# (number)

Gets the current record number.

#

Type: numeric

This function returns the record number of the current record of the
selected file.  Note that ? # displays the current record number in the form
specified by the system variable :PICTURE (see Section 2.7).  Shark
also has a more general form of this function, RECNO(, which allows the user
to specify file other than the selected file.

When used with the option RECNO(filenum), it gives the record number of
the current record in file filenum.

Examples:

1>USE employee
1>? #
     1.00
1>GO BOTTOM
1>? #
     6.00
1>GO TOP
1>? #
     1.00
1>SKIP 2
1>? #
     3.00

$( (substring)


Gets a substring of a string.

 $(str exp, , )
 str exp         the string from which the new string is formed
    the position from which the new string is taken
    the number of characters to place in the new string

Type: character

This function takes the string in str exp from position 
(fractions are thrown away); the number of characters taken is .  (In both numeric expressions, the fractions are disregarded).


Examples:

1>name='David Barberr'
1>? $(name, 7,3)
Bar
1>? $(name, 7,12)
Barberr
1>? LEN($(name,7,12))
      7.00
     Note that $(name,7,12) is of width 7, not 12; there are only 7 letters
     left in name from position 7.
1>s=3
1>t=1
1>? $(name+name, (s+t)/2, 1.9)
a
     Note that 1.9 was taken as 1.

ASTERISK (*)

Determines whether a record is deleted.


 Type: logical

In the selected file, the current record pointer points at a record. If
this record has been marked for deletion (in BROWSE or EDIT, or with the
DELETE command), then * gives the value T; otherwise, it is false.

Example:

1>USE employee
1>DELETE RECORD 2
      1 DELETE(S)
1>GO 2
1>? *
T
Do not confuse this function with * command (NOTE).

@( (at)


Gets the location of a substring.

@(find str exp, str exp [,start)

find str exp    the string searched for
str exp         the text to be searched

Option:
start byte position at which to start looking for find str exp
within the string: str exp.  If it occurs, the function returns the
character position of the first (left-most) substring of str exp which
is the same as find str exp; if it does not occur, the function
returns a 0.

@( and its equivalent, the AT( function, can easily search for
successive occurences of a substring within a string.

Consider the previous paragraph.  How many occurences are there
of the substring "string"?  How many of "s"?  This function can determine
the answer as follows if the paragraph is stored as a single string in the
variable STR:

STR='@( and its equivalent, the AT( function, can easily search for successive 
occurences of a substring within a string.'
SUBSTR='s'
COUNT=0
START=0
LEN_STR=LEN(STR)
DO WHILE START<LEN_STR
   START=@(SUBSTR,STR,START+1)
   IF START>0
      COUNT=COUNT+1
   ELSE
      BREAK
   ENDIF
ENDDO

Be sure that start always advances; if it stays in the same place, it
will perform the same operation indefinitely since it will never get to the
end.

Ambitious programmers will have noted that, if substr is longer than one
byte, start should begin at 1-LEN(SUBSTR) and advance each time by the
length.  Furthermore, the condition on the DO WHILE line should then be:

start<=len_str-len_sub

(assuming you've saved the length of the substring in this last variable).

Examples:

1>greeting='Good morning'
1>? @('oo', greeting)
      2.00
1>? @('good',greeting)
      0.00

In a program:

IF @(answer,'YNQynq')>0

checks whether the user response is correct.

This program segment finds and marks every occurence of a specified
string in a page of text displayed on the screen:

CLS                                ;start by erasing the screen
DO WHILE t                         ;set up continuous loop -break embedded in segment
   IF row()<mLineNumber            ;stop at end of screen
      IF .not. read(mPrintLine,1)  ;be sure there's more to display
         BREAK                     ;if not, break out of loop
      ENDIF
      ?? mPrintLine                ;display the line, no linefeed
      IF mText>' '                 ;if looking for input text
         mPrintLine=!(mPrintLine)  ;capitalize line from file
         mSearchPos=1              ;start search at 1
         DO WHILE t
            mSearchPos=@(mText,mPrintLine,mSearchPos)
            IF mSearchPos=0        ;no more to find, so...
            BREAK               ;   get out
            ELSE
* we found something...highlight it and increment search-start position
               COLOR colorFind,row(),mSearchPos-1,row(),mSearchPos+mTextLen-2
               mSearchPos=mSearchPos+mTextLen
            ENDIF
         ENDDO
      ENDIF
      ?                            ;emit carriage return/linefeed pair
   ELSE
      BREAK                        ;stop when screen is full
   ENDIF
ENDDO

ASC(

Converts a character to its ASCII number.

ASC(str exp)
str exp the first character of this string is converted

Type: numeric

The characters in the character set used by the computer are numbered
from 0 to 255.  For the first character of the string str exp, ASC(
returns the corresponding number.  RANK( is a synonym for ASC(.  See also
the functions CHR(, CTONUM(, and NUMTOC(.

Examples:
1>? ASC('x')
   120.00
1>? ASC('xyz')
   120.00
    Note that only the first character of the string matters.

AT(

Gets the location of a substring . . . a synonym for @(

AT(find str exp, str exp, [start]

find str exp    the string searched for
str exp         the text to be searched

Option:
[start]         byte position at which to start looking for

Type: numeric

This function finds out whether a string: find str exp occurs in the
string: str exp.  If it occurs, the function returns the character
position of the first (left-most) substring of str exp which is the same
as find str exp; if it does not occur, the function returns a 0.

@( and its equivelent, the AT( function, can easily search for
successive occurences of a substring within a string.

Consider the previous paragraph.  How many occurences are there of the
sunstring "string"?  How many of "s"?  This function can determine the
answer as follows if the paragraph is stored as a single string in the
variable STR:

Example:

SUBSTR='s'
COUNT=0
START=0
LEN_STR=len(str)
DO WHILE start<len_str
   start=@(substr,str,start+1)
   IF start>0
      count=count+1
   ELSE
      BREAK
   ENDIF
ENDDO
Be sure that start always advances; if it stays in the same place, it
will perform the same operation indefinitely since it will never get to the
end.

Ambitious programmers will have noted that, if SUBSTR is longer than one
byte, START should begin at 1-LEN(SUBSTR) and advance each time by the
length.  Furthermore, the condition on the DO WHILE line should then be

START<=LEN_STR-LEN_SUB

(assuming you've saved the length of the substring in this last variable).

Examples:

1>greeting='Good morning'
1>? @('oo', greeting)
      2.00
1>? @('good',greeting)
      0.00

In a program:

IF @(answer,'YNQynq')>0

checks whether the user response is correct.
     This program segment finds and marks every occurence of a specified
string in a page of text displayed on the screen:

CLS                                ;start by erasing the screen
DO WHILE t                         ;break embedded in segment
   IF row()<mLineNumber            ;stop at end of screen
      IF .not. read(mPrintLine,1)  ;be sure there's more to display
         BREAK                     ;if not, get out
      ENDIF
      ?? mPrintLine                ;display the line, no linefeed
      IF mText>' '                 ;if looking for input text
         mPrintLine=!(mPrintLine)  ;capitalize line from file
         mSearchPos=1              ;start search at 1
         DO WHILE t
            mSearchPos=@(mText,mPrintLine,mSearchPos)
            IF mSearchPos=0        ;no more to find, so...
               BREAK               ;   get out
            ELSE
* we found something...highlight it and increment search-start position
               COLOR colorFind,row(),mSearchPos-1,row(),
mSearchPos+mTextLen-2
               mSearchPos=mSearchPos+mTextLen
            ENDIF
         ENDDO
      ENDIF
      ?                            ;emit carriage return/linefeed pair
   ELSE
      BREAK                        ;sop when screen is full
   ENDIF
ENDDO

BIT(


Bit-set function determines if a given bit is 0 or 1

BIT(string,bit position)

string          a string or string variable to test
bit position    a numeric expression; position of a given bit
                      within string

Type: logical

Each character in the ASCII character set is identified by an eight-bit
binary number from 0 to 255 inclusive.  Each bit may be either 0 or 1; for
example, the letter A has a decimal value of 65 and a binary value of
01000001.

When used with the SET( and RESET( functions, which turn specific bits to
1 or 0 respectively, the BIT( function can be used to access large amounts of
logical data much more compactly than in a set of logical variables.  BIT(
returns T (true) if the specified bit is set (0), F (false) if not set (0).

NOTE: Bit positions are counted differently than in some other schemes.
In these functions, all bits are counted from the left of the string starting
at 1, so that each character contains bits numbered as follows:
 1. Bits 1 to 8.
 2. Bits 9 to 16.
 3. Bits 17 to 24.
  . . . and so on

Example in a program:

To print the binary value of each character in an input string:

SET RAW ON         ;eliminates spaces between listed output
DO WHILE t
   ACCEPT 'Enter a short string or binary representation: ' TO string
   IF string=' '
      BREAK
   ENDIF
   ?
   REPEAT LEN(string)*8 TIMES VARYING position
      ?? IFF(BIT(string,position),'1','0')
      IF MOD(position,8)=0
         ?? ' '
      ENDIF
   ENDREPEAT
ENDDO

Now run the program:

Enter a short string for binary representation: Bit <--- enter text "Bit"
01000010 01101001 01110100   <--- result displays on screen
Enter a short string for binary representation: <--- prompt reappears

BLANK(


Creates a string of blanks or other specified characters.
BLANK(num exp[,charnum)

num exp    a number from 0 to 255

Option:
charnum    the ASCII number of the character used to fill the
                  blank string; default is 32, the blank character

Type: character

This function creates a string of num exp blanks or other specified
characters.

When charnum is specified, many interesting effects can be created,
particularly by using the special pattern characters in the IBM screen
character set, 176-178, and the solid block character, 219.

Examples:

1>name='DAVID'
1>? name+BLANK(15)+name
DAVID               DAVID
1>num=23
1>? name+BLANK(num+5)+name
DAVID                            DAVID
1>? BLANK(20,65)
AAAAAAAAAAAAAAAAAAAA
1>? BLANK(20,196)
--------------------

BOF


Gives the beginning-of-file flag for the currently selected data file.

 BOF

 Type: logical

If the current record pointer is on the first record of the file in use
and a SKIP -1 is issued, BOF returns T (true); otherwise it is F (false).
Since SKIP -n is treated as n SKIP -1 commands, BOF returns true if SKIP -n
goes past the last record.

To check an open data file other than the currently selected one, use
the BOF( function.

Examples:

1>USE employee
1>GO 3
1>SKIP -2
1>? #
      1.00
1>? BOF
F
1>SKIP -1
1>? BOF
T
1>GO 4
1>SKIP -5
1>? #
      1.00
1>? BOF
T

BOF(


Gives the beginning-of-file flag for a specified data file.

BOF(filenum)


Option:

filenum the number of the data file to be checked

Type: logical

For the data file number specified, if the current record pointer is on
the first record and a SKIP -1 is issued, BOF( returns T (true); otherwise
it is F (false).  Since SKIP -n is treated as n SKIP -1 commands, BOF(
returns true if SKIP n goes past the first record.

An extended form of the BOF function which, since it takes no
parameter, works only on the currently selected data file.  If no filenum
is specified, the current file is assumed.

Examples:

1>USE employee
1>GO 3
1>SKIP -2
1>? #
      1.00
1>? BOF()
F
1>SELECT 2
2>USE inventry
2>GO TOP
2>? #
      1.00
2>? BOF()
F
2>SKIP -1
2>? #
      1.00
2>? BOF()
T
2>SELECT 1
1>? BOF(2)
T

CEN(


Centers a line of text.

CEN(str exp,num exp)

 str exp    the text to be centered
 num exp    the line width

Type: character

This function centers (from the present position) the text str exp in a
line (column) with num exp characters.


Examples:

1>compiler='Shark'
1>? CEN(compiler,40)
                  Shark
1>@ 10,20 SAY CEN('Center this',40)
     Note: the last command centers the text between columns 20 and 60.

CHR(


Converts an ASCII number to character.

CHR(num exp)

num exp a number from 0 to 255

Type: character

The characters in the character set used by the computer are numbered
from 0 to 255; this number for a character is called the ASCII number.  For a
given num exp in this range, CHR(num exp) is the corresponding
character.

This function is useful to send control codes to the printer.  For
instance,

1>? CHR(27)+CHR(120)+CHR(1)

puts the Epson LQ-1500 printer into letter quality mode.

The functions ASC( and RANK( do the reverse.  These functions combine
nicely.  If the memory variable LETTER contains a letter of the alphabet
(other than z or Z), then LETTER=CHR(ASC(LETTER)+1) places in LETTER the next
letter of the alphabet.

Examples:

1. To send unprintable or other characters to a printer
1>? CHR(27)
sends ESC to the printer

1>letter='C'
1>? CHR(RANK(letter)+1)
sends "D" to the printer

2. To set a standard IBM or Epson printer into double-wide mode:
1>SET PRINT ON
1>? CHR(14)+'First line.'
prints:
First line.                    in double-wide characters

NOTE: the character '0' is difficult to send to a printer since it represents
the end-of-line instruction.  A better method of sending characters is the PSTR
command, which permits sending any character to the printer.

CLOSE(


Closes a DOS file.

CLOSE([filenum])

Option:

filenum      the DOS file number (between 1 and 4)

Type: logical

This function closes the DOS file (in particular, the sequential file)
opened with the ROPEN( or WOPEN( function.  It returns T if successful, F
otherwise.  See the functions ROPEN(, WOPEN(, SEEK(, SSEEK(, READ(, WRITE(,
GET(, PUT(, IN(, OUT(, and CLOSE).

If filenum is not specified, filenum=1 is the default.

Example:
1>ok=ROPEN('a:label.prg',3)
1>? ok
T
1>ok=CLOSE(3)

COL(


Gets print column position.

COL()

Type: numeric

This function gives the current column position of the cursor; if the
printer is on, it returns the column position of the printer head.  See the
commands SET PRINT ON and SET FORMAT TO PRINT, and the function ROW(.

Example:
@ ROW(),COL()+3 SAY 'Hello'
prints 'Hello' starting three characters to the right of the end of the last
printing.

CTONUM(

Convert a hexadecimal string into a decimal number.

CTONUM(type,string exp)

type         the length of the numeric value to be returned
string exp   the string to be evaluated as a hexadecimal value

Type: numeric

A general conversion function for converting hexadecimal values into
decimal numbers.  Input can be any length string or string variable up to
eight characters as follows:

 Type     String Length  Returns
   1      1 byte         integer 0 to 255
   2      2 bytes        integer -32768 to 32767
   4      4 bytes        integer +/- 2 billion
   8      8 bytes        a floating point number

If string is shorter, conversion still assumes the string is the format
of the given width.  When type is 1, this function is equivalent to RANK(
or ASC(.

The NUMTOC( and CHR( functions convert numbers into strings.

Do not confuse these function with STR( and VAL(, which convert decimal
numbers into their string representations, and vice versa.

Examples:

1>? CTONUM(1,'a')
     97.00
1>? CTONUM(2,'ab')
  25185.00
1>? CTONUM(4,'abc')
6513249.00
1>? CTONUM(4,'abcd'); number too large for format in :PICTURE

DATE(


Displays a date in a specific format, or update :DATE with the computer's
system date.

DATE(type[,str exp)

type one of 9 type basic date-output formats

Option: str exp  the date to be converted

Type: character

This function has three distinctly different purposes and results:

1.  with only type specified in the range 1-9, rewrites the current
    Shark date in :DATE in the format specified by the type, and
    returns the result.
2.  with two parameters (the format in the range 1-9, and the date)
    returns the given date in the specified format.  :DATE is not
    effected.
3.  with only type specified as zero, updates the Shark date with
    the computer's current system date, and the computer time with
    the current system time.  The Shark and system dates are always
    the same when Shark is started, but the Shark does not
    automatically advance at midnight as the computer's system date
    should.  When Shark can be in use overnight, or even for days at
    a time, it may be important to ensure that these dates are kept
    in synchronization.  Returns a string of length zero.

The type can be given in either of two forms, a name or number
(numeric expression) as follows:

Type            Date-output format
-------------   -----------------------------------------------------------
0               a string of length zero
1 or YMD        6-character format without slashes: yymmdd
2 or MDY        8-character format with slashes: mm/dd/yy
3 or Char       Spelled out: Month dd, yyyy
4 or Full       Spelled out: Weekday, Month dd, yyyy; valid only for years 1980-2079
5 or Lchar      Last day of month spelled out in format 3 (Char)
6 or DMY        11-byte string in format dd-MMM-yyyy (example 03-NOV-1990)
7 or Variable   formatted without slashes according to SET DATE TO command (See SET DATE TO)
8 or Long       8-character format without slashes: yyyymmdd
9 or Last       Last day of month in format 1 (YMD) or 8 (Long), depending on whether SET 
                DATE TO command set year to YY or YYYY

Shortcut: When specifying type by name, only the first character is
usually required. The exception is for Lchar, Long, and Last, which
require two characters to resolve ambiguity. If only one is given, Lchar
is assumed.

Note: No name equivalent is provided for type 0, which updates the
Shark date from the computer's calendar setting.

str exp must contain the date in one of the following formats:

mmddyy      ddmmyy       yymmdd   mmddyyyy   ddmmyyyy   yyyymmdd

Optionally, a slash, a hyphen, or a space may be used to separate the
elements of these formats.  For example, YY/MM/DD, YY-MM-DD, DD MM YYYY are
all equally valid.

There should be two digits each for month and the day, and two or four
digits for the year.  01 3 92 is not acceptable.  If str exp is not
acceptable, then DATE( returns a string of blanks.

In the event of ambiguity, dates will be decoded in accordance with
the format set in the SET DATE TO command.  For example:

SET DATE TO    date           is interpreted as   Comment
-------------  -------------  ------------------  -------------------------
'ddmyy'        11/03/99       March 11, 1999
'mmddyy'       11/03/99       November 3, 1999
'mmddyy'       11/03/60       November 3, 2060    all dates converted to range 1980-2079

See also the system variable :DATE and the command SET DATE TO.

Examples:

1>:DATE= '10/05/99'
1>? :DATE
10/05/99
1>? DATE()
19991005
1>? :DATE
19991005
1>? DATE(1)
991005
1>? :DATE
991005
1>? DATE(2)
10/05/99
1>? :DATE
10/05/99
1>? DATE(3)
October 5, 1990
1>? :DATE
October 5, 1990
1>? DATE(4)
Saturday, October 5, 1990
1>? :DATE
Saturday, October 5, 1990
1>? DATE(4,'12/08/90')
Sunday, December 8, 1990
1>? :DATE
Saturday, October 5, 1990
1>? DATE(5,'90-30-27')
March 31, 1990
1>? DATE(6,'03  27 90')
27-Mar-1990
1>? :DATE
Saturday, October 5, 1990

If the time has passed midnight during the current run of Shark, you
can update the Shark date with DATE(0):

1>? DATE(0)
1>? DATE(4)
Sunday, October 6, 1990

A preferred date format can be stored in Shark's .CNF file as a system variable. It's then visible to all 
applications in Shark:

:UNDOC=PIC(DATE(8),"XXXX.XX.XX")

Calling :UNDOC will show today's date, properly formatted.


DAYS(

Computes dates and date differences in days.

DAYS()
DAYS(str exp,num exp)

In the first form:

str exp1 and str exp2 are dates

In the second form:

str exp is a date and num exp is a number
Type: numeric/character

In the first form, DAYS( returns the number of days between two dates.
The result is an integer.

In the second form, DAYS( returns the date (as a string) which is
num exp days past or before the date str exp.

The string expressions containing dates can be of many different formats
(see the DATE( function for more examples):

               yy/mm/dd    yy-mm-dd    yyyy mm dd
               mm/dd/yy    mm-dd-yy    mm dd yy

There should be two digits each for yy, mm, and dd, and four digits for
yyyy.  01 3 90 is not acceptable.

In the second form, the date is returned in the format set with the SET
DATE TO command (default: mmddyyyy).  If you wish a different format, use the
DATE( function.  See also MONTHS( and SET DATE TO.

Examples:

1>? DAYS('04 06 90','04 29 90')
     23.00
1>? DAYS('01/01/88','01 23 90')
    753.00
1>? DAYS('01/01/90','01 23 88')
   -708.00
1>? DAYS('01/01/91','01 02 91')
      1.00
1>? DAYS('01/02/91','01 01 91')
     -1.00
1>? DAYS('02/28/88','03 01 88')    ;leap year
      2.00
1>? DAYS('02/28/90','03 01 90')    ;not a leap year
      1.00
1>? DAYS('04 03 90',30)
050290
1>? DAYS('02 03 90',30)
030590
1>? DAYS('02 03 90',-3)
010490
1>? DAYS('020390',-30)
010490
1>monthday='0203'
1>offset=30
1>? DAYS(monthday+'90',offset+1)
030690

DAYS( and DATE( may be combined to form complex expressions.  For
instance, the end of the month closest to today in the form set in the SET
DATE TO command:

DATE(7,DAYS(DATE(2),-15))

The end of NEXT month:

DATE(5,DAYS(DATE(2),30))

See DATE( and MONTHS( functions, and SET DATE TO command.

DBF(


Allows access to data-file attributes of a file in use.

 DBF(type[,filenum)

 type      the information required from the data file header

 Option:

 filenum   the data file number; default is the currently
               selected data file

 Type: character/numeric

Each data file has a file head which contains information about its
structure, most of which is displayed with the LIST STRUCTURE command.

Using the DBF(, DBFX( and FLD( functions provides users access to this
information in a programmable form suitable for display and use in
expressions.

The type can be given in either of two forms, a name or number
(numeric expression) as follows:

TYPE             EXPLANATION                        RESULT
1 or (T)ype      file type ("0", "1", "2" or "3")   string
2 or (N)ame      data file name                     string
3 or (F)ields    number of fields in structure      integer
4 or (R)ecords   number of records in file          integer
5 or (I)ndexes   number of indexes currently open   integer
6 or (M)aster    index number of master index       integer
7 or (Q)ualified fully-qualified file name from
                 SharkBase FILES structure if
                 one exists; otherwise from DOS    string
8 or (E)xpanded  fully-qualified file name from DOS string

Shortcut: When specifying type by name, only the first character is
required.

Examples:

1>? DBF(type),DBF(n),DBF(fields),DBF(recs),DBF(indexes),DBF(master)
0 CUSTOMER.DBF       9.00       4.00       2.00       1.00
1>? DBF(q)
C:\SHARK\DBF\CUSTOMER.DBF

1>USE#1 CUSTOMER READ
1>SET INDEX TO NAME
1>APPE BLANK
1>GO TOP <--- takes you to blank (NEWLY APPENDED) record of indexed table
1>GO BOTT <--- takes you to last record before new record appended to table
1>GOTO DBF(R) <--- takes you to the last (NEWLY APPENDED) record in table

Since appended record is blank, it won't show as the last (BOTTOM) record
in an indexed table.  DBF(R) will take you to the last record in the table.


DBFX(


Gives additional information about an open data file; an extension to the
DBF( function.

DBFX(type [,filenum)

type      one of three types of information as listed below

Option:

filenum   the data file number; default is the currently
                 selected data file

 Type: logical

The DBF( and FLD( functions provide information contained in the data
file headers.

Shark provides this extended function to give three additional types
of information in a programmable form suitable for display and use in
expressions.

The type can be given in either of two forms, a name or number
(numeric expression) as follows:

TYPE           EXPLANATION
1 or Filter    TRUE if a FILTER is in effect
2 or Limit     TRUE if a LIMIT is in effect
3 or Relation  TRUE if file is related to another
4 or Write     TRUE if current record has changes to be written to disk

Shortcut: When specifying type by name, only the first character is
required.

In a program, the programmer has control over whether filters, limits
and relations are established, so the first three options are primarily
helpful in Conversational SharkBase, in program debugging and in displaying
the current environment for the aid of end-users.

The fourth option, however, is extremely helpful in programming,
especially on networks, for it allows the programmer not only to check
whether the user actually wants to save changes made to the record, but to
avoid locking and changing records when the user was only looking.

A second valuable use of this feature is to time-stamp changes and
leave a record of who made them.

Examples:
1>USE customer
1>SET FILTER TO state='CA'
1>? DBFX(filter)
T
1>? DBFX(r)
F

In a program segment, starting with the READ command):

READ
IF DBFX(w)
   @ 22,0 say CEN('Record changed. Save the Changes (Y/N)?',80)
   CURSOR 23,39
   IF !(CHR(INKEY()))='Y'
      REPLACE changedby WITH DATE(1)+user+TIME(1)
      FLUSH
   ELSE
      NOUPDATE      ;all changes are discarded
   ELSE
ENDIF

The same approach is used in programming for SHARE files on a network,
but the actual technique is beyond the scope of this section due to the many
different ways networkin-data-indegrity is implemented.  See specific
network sections of your SharkBase documentation for more on this topic.

DELETED(


Determines whether a record is deleted.

 DELETED(filenum)

 Option:

 filenum    the number of the data file to be checked

 Type: logical

In a specified data file, the current record pointer points at a record.
If this record has been marked for deletion (in BROWSE or EDIT, or with the
DELETE command), then DELETED( gives the value T; otherwise, it is false.

This is a more general form of the * function, which operates the same
way as DELETED( but, because it allows no parameter, works only with the
currently selected data file.

Examples:
1>? DELETED(4)
T

DESCEND(


Reverses all bits in string; equivalent to NOT of string.
 DESCEND(string)

 string    the string to be converted; every "1" bit is returned
               as "0", and every "0" bit is returned as "1"

 Type: character

Each character in the ASCII character set is identified by an eight-bit
binary number from 0 to 255 inclusive.  Each bit may be either 0 or 1; for
example, the letter A has a decimal value of 65 and a binary value of
01000001, while the letter B has a decimal value of 66 and a binary value of
01000010.

The DESCEND( function can be used to return a "mirror image" of the
input string . . . i.e., one in which evey bit set to 1 is reset to 0, and
every 0 is set to 1.

The result is familiar to programmers who use C and other low-level
languages, who would use the NOT operator to obtain the same result.

The main use of DESCEND( in Shark is to create indexes that are
in reverse, or descending, order.

Remember that an index arranges its keys in order of the value of the
characters making up the keys.  "A" comes before "B" because the value 65 is
smaller than 66.

But suppose the index expression, instead of being on the key expression itself
is on the NOT value of it, as in:

INDEX ON DESCEND(NAME) TO REVERSE

Now you have an index called REVERSE.NTX in which B comes before A.

This function is especially useful in creating reports.  For example,
suppose you want to report transactions for your customers in reverse date
order (latest transactions first).  Your index command could be:

INDEX ON CUST+DESCEND(DATE) TO CUSTREPT

Note: if you create an index using the DESCEND( function, you will have
to use the same function to modify any find strings if you need to use the
index to FIND, SEEK, etc.

Example in a report form:

TITLE - Transactions by Customer, with Dates in Descending Order
FILE - trans
INDEX - cust+descend(date) to custrept
FILE - cust index cust1
RELATION - custnum to 2
FIELDS - date(6,date),desc,amount
HEADING - Date;===========,Description;==============================;Amount;==========
PICTURE - ,,9999999.99
SUBTOTAL - custn
MESSAGE - 'Customer: '+pic(custnum,'xxx-x-xx  -- ')+name#2

Note: This report form includes a number of features worth noting,
including the fact that it creates its own index, sets up a relation to a
second file, includes underlined headings and subtotals, and includes one
line split into two.  In report forms, the comma (,) is a continuation
character when it is the last character on a line.  See REPORT.

DIR(

Get file information from disk directory.
 DIR(filespec)
 DIR()

 Option:

filespec  a string or string expression containing a file name
                 (or skeleton using ? and/or * wildcards), with
                 optional drive and/or path specification (enclosed
                 in single quotes)

 Type: character

Searches for specific files specified by the drive path, subdirectory
and/or filename and provides specific information on files found.

If an argument is given, it must be a string or string expression
naming a file, with * and ? wildcards optional). Returns the first file name
found matching filespec. If no match was found, blank is returned.

If no argument is given, the previous filespec is used to find the
next matching file. If no more matching file names are found, blank is
returned.

DIR( differs from DIRF( in that DIR( requires the user to specify the
pathname unless the search is to be confined to the current directory.
DIRF( (see below) is usually preferable since it searches the directory as
which a current FILES structure points for the file name specified.  See
DIRF(.

Examples:

? DIR('c:\path\*.bak')

locates and displays the name of the first file with extension BAK in the
subdirectory \PATH, while

? DIR('*.bak')

locates and displays the name of the first file with extension BAK in the
current directory.

If a file is found with Form 1, entering DIR() with no parameters will
locate the next file meeting the filespec.  This will continue until the
response is a blank, indicating there are no more files meeting the

filespec.

Once a file is identified with DIR(, the DIRX( function may be used to
obtain additional information from the DOS directory in a form suitable for
use in a program.

DIRF(


Get file information from disk directory.

 DIRF(filespec)
 DIRF()

 Option:

filespec  a string or string expression containing a file name
                 (or skeleton using ? and/or * wildcards), with
                 optional drive and/or path specification (enclosed
                 in single quotes)

Type: character

Searches for specific files specified by the filename and the path
supplied from the FILES structure (see FILES...ENDFILES), and provides
specific information on files found.

If an argument is given (form 1), it must be a string or string
expression naming a file, with * and ? wildcards optional). Returns the
first file name found matching filespec. If no match was found, blank is
returned.   If a disk name is supplied, the path supplied by the FILES
structure is ignored.

If no argument is given (Form 2), the previous filespec is used to
find the next matching file. If no more matching file names are found, blank
is returned.

DIR( differs from DIRF( in that DIR( requires the user to specify the
pathname unless the search is to be confined to the current directory.  See
DIR(.

Examples, assuming the following FILES structure is in effect:

FILES
*.prg,c:\shark\prg
*.frm,c:\shark\prg
*.bak,c:\shark\prg
*.db*,c:\shark\data
*.ntx,c:\shark\ntx
*.cpl,c:\shark\cpl
ENDFILES
DIRF('*.prg')

locates the first file with extension PRG in the subdirectory C:\SHARK\PRG.

DIRF('*.bak')

locates the first file with extension BAK in the subdirectory C:\SHARK\PRG.

NOTE that the above instruction only locates the file and doesn't display
any result.  To display the found file, you must type:

? DIRF('*.bak')


DIRF('*.dbt')

locates the first file with extension DBT in the subdirectory C:\SHARK\DATA.

DIRF('*.txt')

locates the first file with extension TXT in the current directory, since
there was no matching filename pattern in the FILES structure.

If a file is found with Form 1, entering DIRF() with no parameters will
locate the next file meeting the filespec.  This will continue until the
response is a blank, indicating there are no more files meeting the
filespec.

Once a file is identified with DIRF(, the DIRX( function may be used to
obtain additional information from the DOS directory in a form suitable for
use in a program.

DIRX(

Obtain additional information about file located with the DIR( or DIRF(
function.
 DIRX(type)

 type    the name or number of the information required about a file

 Type: character/numeric

Once a file is identified with DIR( or DIRF( additional information can
be obtained from the DOS directory in a form suitable for use in a program.

The type can be given in either of two forms, a name or number (numeric
expression) as follows:

Type           Explanation                                    Result
1 or Name      last file name found with DIR(                 string
2 or Size      size in bytes of last name found with DIR(     integer
3 or Attribute DOS file attribute as follows                  integer
                    1 - directory
                    2 - system
                    3 - hidden
                    4 - read only
                    5 - normal
4 or Time      time file created or last updated              string
5 or Date      date file created or last updated              string
6              directory
7              sub-directory

Shortcut: When specifying type by name, only the first character is required.

These functions have many uses. Use them to write a program that backs up
recently modified files, a program that lists files so the user can pick one,
etc.

Examples:

DIRX(n) returns the filename
DIRX(a) returns 4 if the file is read only

EOF


Gives the end-of-file flag for the currently selected data file.

 EOF

 Type: logical

If the current record pointer is on the last record of the file in use
and a SKIP is issued, EOF returns T (true); otherwise it is F (false).
Since SKIP n is treated as n SKIP commands, EOF returns true if SKIP n goes
past the last record.  Also, if a LOCATE or CONTINUE command is unsuccessful,
or if NEAREST does not find an index key equal to or greater than the FIND
string, EOF returns T.

Examples:

1>USE employee
1>GO 4
1>SKIP 2
1>? #
      6.00
1>? EOF
F
1>SKIP
1>? EOF
T
1>GO 4
1>SKIP 3
1>? #
      6.00
1>? EOF
T

EOF(


Gives the end-of-file flag for a specified data file.

 EOF(filenum)


 Option:

 filenum    the number of the data file to be checked

 Type: logical

For the data file number specified, if the current record pointer is on
the last record and a SKIP is issued, EOF( returns T (true); otherwise it is F
(false).  Since SKIP n is treated as n SKIP commands, EOF( returns true if
SKIP n goes past the last record.

Also, if a LOCATE or CONTINUE command is unsuccessful, or if NEAREST
does not find an index key equal to or greater than the FIND string, EOF(
returns T.

If no filenum is specified, the current file is assumed.

An alternate form of the function - EOF - works only on the currently
selected data file, since it takes no parameter.  See EOF.

Examples:

1>USE employee
1>GO 4
1>SKIP 2
1>? #
      6.00
1>? EOF()
F
1>SELECT 2
2>SKIP
2>? EOF()
T
2>GO BOTTOM
2>SKIP
2>? #
      6.00
2>SELECT 1
1>? EOF(2)
T

FIELD(


Get the number of the Get Table entry corresponding to a variable or field
name.
  
 FIELD(<name>)                                

 <name>   =the name of field or variable in a Get Table        

 Type: numeric

While in full-screen editing mode (with READ, BROWSE, EDIT, etc.), each
input variable and field is put into a Get Table that can be controlled with
an ON FIELD structure.

FIELD( returns the number from 1 to 64 of any editing field on screens
created with @ GET and TEXT macros.  This function is usually used on an ON
FIELD structure to redirect the sequence of data entry.

See READ and ON FIELD in the Command Reference section.

Example in a program:

ON FIELD
FIELD qty
   IF qty<0
      @ 22,0 say CEN('Quantity cannot be negative. Press any key',80)
      cc=INKEY()
      ERASE 22,22
      :FIELD=FIELD(qty)
   ENDIF
ENDON

See also System Variable :FIELD

FILE(


Verifies whether a file exists.

 FILE(str exp)

 str exp   = a file name                  

 Type: logical                               

This function looks up the file whose name is given by str exp; if the
file is found, the function returns T, otherwise it returns F.

If no extension is given in the file name, DBF is assumed (a data file is
looked for).

Examples:

1>? FILE('employee')
T
1>? FILE('a:read.me')
T
1>mfile='read.me'
1>? FILE(mfile)
F
1>? FILE('a:'+mfile)
T

FLD(


Get information about a field in a data file.
  
 FLD(type,<fieldnum> [,filenum])          
                                              
 type       one of the four attributes of a field            
 <fieldnum>  = the number of the field to be checked

 Option:

 filenum    the number of the data file to be checked

 Type: character/numeric

Each field in a data file has four attributes as shown with the LIST
STRUCTURE command: name, type, width and (for numeric variables) number of
decimal places.  The FLD() function is often used in conjunction with the DBF()
function.

These attributes can be retrieved in a form suitable for use in a program
with the FLD() function.

The type can be given in either of two forms, a name or number (numeric
expression) as follows:

Type           Explanation                              Result
1 or Name      string containing field name             string
2 or Type      string containing field type             string
3 or Width     number containing width of field         integer
4 or Decimals  number of decimal places in field        integer

Shortcut: When specifying type by name, only the first character is required.

Example in a program:

REPEAT DBF(records) TIMES varying fldnum
   REPEAT 4 times VARYING type
      ?? FLD(type,fldnum)
   ENDREPEAT
   ?
ENDREPEAT

GET(


Gets a string from a DOS file.

 GET(str var,<width num exp>[,filenum])

str var     stores the string
<width num exp>   = the width of the string requested (must be in range 1 to 254)

 Option:

 filenum            the DOS file number (between 1 and 4)

 Type: logical

This function imports a string of  characters from a DOS
file opened with the ROPEN( function; the character number pointer is normally
positioned with the SEEK( function.

If successful in getting all the bytes requested, GET( returns T (true)
and sets str var to the string imported from the file.  If str var does
not exist, GET( will create it.

If the function is unsuccessful, it returns F (false).  This will be the
result if the GET( function tries to get data beyond the end of the file.
Note, however, that even if GET( returns F, one of more characters may still
have been imported from the file; it is wise to check the value and width of
str var to ensure part of a file is not lost.

If filenum is not given, filenum=1 is assumed.

GET( READ(, IN(, and WRAP( are the only functions that change the
contents of the memory variable used as an argument.

See also the functions ROPEN(, WOPEN(, CLOSE(, SEEK(, and PUT(.

Example in a program:

IF ROPEN('test',3)
   DO WHILE GET(string,80,3)
      ? string
   ENDDO
ENDIF
ok=CLOSE(3)

IFF(


Allows inline IF...THEN logic in expressions.

 IFF(cond,<exptrue>,)

 cond       a logical expression
 <exptrue>    the expression to be returned if cond is TRUE
 <expfalse>   the expression to be returned if cond is FALSE

 Type: character/numeric/logical

This function returns  if cond is true,  otherwise.
The type of the value returned is the same as the expression selected by the
condition.  IFF( is very useful in the FIELDS line of reports or in commands
such as SUM, AVERAGE, REPLACE, or LIST.

Examples:

1>? IFF(married,'Married','Single ')
1>SUM IFF(quant>500, quant*price, 0),IFF(state='NY',1,0)

The first command prints "Married" or "Single" according to the value of
a logical field named MARRIED. The second 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.

Caution: do not use expressions of different types or widths in reports,
since this may cause the REPORT command to fail.

IN(


Inputs a single character from a sequential file.

 IN(str var[,filenum])

 str var      stores the character

 Option:

 filenum      the DOS file number (between 1 and 4)

 Type: logical

This function reads the next character of the DOS file (opened with the
ROPEN() function into the string variable str var; if str var does not
exist, it will be created.  str var cannot be a matrix variable.

If filenum is not given, filenum=1 is assumed.  IN( returns T if
successful, F otherwise.

This function is especially useful to communicate over the standard COM1,
COM2 devices, for conversion of Word Star or other non-standard files to
standard ASCII files, to encrypt/decrypt a file through a translation table.

IN(, GET(, READ(, and WRAP( are the only functions that change the
contents of the memory variable used as an argument.

See the functions OUT(, ROPEN(, WOPEN(, SEEK(, SSEEK(, and CLOSE(.

IFKEY(


Tests if a character is waiting in the keyboard buffer.

 IFKEY()

 Type: logical

It is often useful to test whether a key has been pressed on the keyboard
without waiting indefinitely if a key is not pressed.

The IFKEY( function returns T (true) if a keystroke is waiting in the
keyboard buffer, F (false) if not.  The keyboard buffer is not affected.

Example in a program,

to create a timing loop that ends as soon as any key is pressed:

start=VAL(TIME(seconds))
DO WHILE VAL(TIME(seconds))-start<3
   IF IFKEY()
      BREAK
   ENDIF
ENDDO

INKEY(


Waits and gets numeric value of keyboard entry.

 INKEY()

 Type: numeric

This function suspends program execution until a key is pressed.  It
returns a number identifying the key.  Nothing is displayed on the screen.
Any key can be read (except Alt, Ctrl, and shift which merely affect the
characters produced by other keys) including all function keys, editing
keys, and alternate keys.  (Function keys F11 and F12 are not recognized
by many computers' BIOS programs, and are ignored by Shark.)

Standard keys are identified with their ASCII number.  Other keys
return values between 256 and 511.
Examples:
             Key                     INKEY()
             Ctrl-C                    3
             A                        65
             Alt-A                   285
             <F1>                    315
             Shift-<F1>              340
             Ctrl-<F1>               350
             Alt-<F1>                360

To find out the number identifying a key, give the command:

1>? INKEY()

and press <ENTER>, then the key; the character's number will be displayed.

Using INKEY() the user can program his own EDIT, set up cursor controlled
menus, and so on.

INSERT(


Overwrites a string at a given position with another string.

 INSERT(str expover,str exp,num exp)

 str expover    the string expression to overwrite
 str exp          the string expression to overwrite with
 num exp        the position

 Type: character

This function takes the string in  str expover  and overwrites the string
with str exp starting at position num exp.

Examples:

1>line='                              '
1>customer='John Smith'
1>ponumber='32109'
1>amount='910.56'
1>line=INSERT(line,customer,1)
1>? line
John Smith
1>line=INSERT(line,ponumber,15)
1>? line
John Smith    32109
1>line=INSERT(line,amount,25)
1>? line
John Smith    32109     910.56
1>line='            c                 '
1>newline=INSERT(line,customer,@('c',line))
1>? newline
            John Smith

Note: The last example shows the use of INSERT( with "templates".  The
line variable is the template.  The character "c" in it designates the place
where the customer has to be inserted.  Such templates are useful in report
generators or for creating screen displays.

LEFT(


Gets the left part of a string.

 LEFT(str exp, num exp)

 str exp   the string from which the new string is formed
 num exp   the number of characters to place in the new string

 Type: character

This function takes the first num exp characters from the string
str exp.  It is equivalent to, but more efficient than, $(str exp, 1,
num exp).

If num exp is greater than the width of str exp, this function
returns all of str exp.

Wherever an expression calls for a substring starting at the beginning,
use LEFT instead of $( or SUBSTR(.

Example:

1>a='David Bark'
1>? LEFT(a,5)
David
1>? LEFT(a,50)
David Bark

LEN(


Gets the width (length) of a string.

 LEN(str exp)

 str exp      the string

 Type: numeric

This function returns the width (including trailing blanks) of the string str exp.

Examples:

1>name='David Barberr'
1>? LEN(name)
    13.00
1>? LEN(name+' is a nice boy')
    27.00

Note that the width of a string is at least 1!

LOC(
Gets the current byte position in a file opened with ROPEN( or WOPEN(.

 LOC(filenum)

 Option:

 filenum    the number of the sequential or random file, 1 to 4
                (default 1)

 Type: numeric

Whenever a file is opened with the ROPEN( or WOPEN( function,
Shark maintains a pointer at a current position, which is where any
PUT( or GET( function would take effect.  The position pointer is set with the
SEEK( and SSEEK( functions, and reset every time the IN(, OUT, READ(, WRITE(,
PUT(, and GET( function is used.

If filenum is not given, filenum=1 is assumed.

A common use of LOC( is to get the current position before a SEEK( so
that the pointer can be reset to the original position after some operation.

LOWER(


Converts a string to lower case.

 LOWER(str exp)

 str exp        the text to be converted to lower case

 Type: character

All upper-case letters in the str exp are converted into lower case by
the LOWER( function.  See also the !( and UPPER( functions.

Examples:

1>a='Aa12b'
1>? LOWER(a)
aa12b
1>? LOWER('David!')
david!

Note that only the upper-case letters, A-Z, are changed (to a-z).  No
other characters are affected.

LTRIM(


Trims blanks from the left-hand side of a string.

 LTRIM(str exp)

 str exp        the string to be trimmed

 Type: character

This function gets rid of the blanks on the left of a string.  See also TRIM(.

Examples:

1>a='    David     '
1>? a
    David
1>? LEN(a)
    14.00
1>? LTRIM(a)+' is trimmed on the left'
David      is trimmed on the left
1>? LEN(LTRIM(a))
     9.00
1>blank='     '
1>? LEN(LTRIM(blank))
     1.00

Note: LTRIM(blank) is a single blank.


MATHEMATICAL FUNCTIONS


EXP(num exp) (e-th power)

e to the power num exp

LOG(num exp) (natural logarithmic function)

natural logarithm of num exp

LOG10(num exp) (base 10 logarithmic function)

base 10 logarithm of num exp

POW(num exp) (power)

num exp1 to the power num exp2

SQRT(num exp) (square root)

square root of num exp

SIN(num exp) (sine)

sine of num exp in radians

COS(num exp) (cosine)

cosine of num exp in radians

TAN(num exp) (tangent)

tangent of num exp in radians

ASIN(num exp) (arc sine)

arc sine of num exp; returns a value in radians between -pi/2 and pi/2

ACOS(num exp) (arc cosine)

arc cosine of num exp; returns a value in radians between 0 and pi

ATAN(num exp) (arc tangent)

arc tangent of num exp; returns a value in radians between -pi/2 and pi/2

SINH(num exp) (hyperbolic sine)

hyperbolic sine of num exp

COSH(num exp) (hyperbolic cosine)

hyperbolic cosine of num exp

TANH(num exp) (hyperbolic tangent)

hyperbolic tangent of num exp

CEIL(num exp) (ceiling integer)

ceiling integer: the integer equal to or just above num exp

FLOOR(num exp)

floor integer: the integer equal to or just below num exp

INT(num exp) (floor integer)

the integer part of num exp (the fractional part is discarded) Note that for positive numbers, INT( and FLOOR return the same result, but for negative numbers, INT( and CEIL( produce the same result. This is because discarding the decimal part of a real number reduces its distance from zero

ABS(num exp) (absolute value)

absolute value of num exp

MOD(num exp1,num exp2) (modulo)

num exp1 modulo num exp1: returns 0 if  num exp2 is 0;
returns the value num with  the same sign as num exp1, less than
num exp2, satisfying

num exp1=i*num exp2+num

for some integer i.

Example:

This function returns the remainder after dividing num exp1 by
num exp2:

1>? MOD(7,4)
3.00

1>? MOD(21,6)
3.00


Examples:
1>:PICTURE='999.999999'
1>? EXP(1)
  2.718282                 this is the value of e
1>? LOG(3)
  1.098612
1>? LOG10(3)
  0.477121
1>? POW(2,4)
 16.000000
1>? POW(2,.5)
  1.414214
1>? SQRT(4)
  2.000000
1>? SQRT(2)
  1.414214
1>? SIN(2)               2 is in radians
  0.909297
1>? ASIN(1)
  1.570796
1>? 2*ASIN(1)
  3.141593               this is, of course, pi; store this to a variable if you need pi
1>? CEIL(3.14)
  4.000000
1>? FLOOR(3.14)
  3.000000
1>? INT(23.45)
 23.000000
1>? INT(-23.45)
-23.000000
1>x=23.45
1>? INT(10*x)
234.000000
1>x=23.999
1>? INT(x)
 23.000000
1>? INT(3.14)
  3.000000
1>? FLOOR(-3.14)
 -4.000000
1>? INT(-3.14)                  note that for negative numbers, INT(
 -3.000000                         and FLOOR( give different values
1>? MOD(5,2)                    this is the remainder of 5
  1.000000                         divided by 2
1>? MOD(-3.14, .7)
 -0.340000
1>? ABS(-3.14)
  3.140000
1>:PICTURE='9999999.99'
1>x=15.689
1>? INT(x*100+.5)/100      Note: this is how to round to the nerest penny
15.69
1>x=15.244
1>? INT(x*100+.5)/100
     15.24

MASK(


Manipulates bits in a string based on comparison between 2 strings

 MASK(,string,<mask>)

 operation       a number representing one of the three masking
                        operations supported by SharkBase: AND, OR, and XOR
 string          the string to be modified by the operation
 mask            the string used to modify the bits in string1

 Type: character

Each character in the ASCII character set is identified by an eight-bit
binary number from 0 to 255 inclusive.  Each bit may be either 0 or 1; for
example, the letter A has a decimal value of 65 and a binary value of
01000001, while the letter B has a decimal value of 66 and a binary value of
01000010.

Although SharkBase has functions to set individual bits to 1 or 0 (SET(
and RESET( respectively), MASK( can be used to change any number of bits at
once.

The three MASK( operations are used to return a string that is the
result of bitwise operations between two strings, comparing each bit in one
string with the bit in the same position in the other string.  If the two
bits are both 1 (on or true), AND and OR both produce a 1 in that position,
while XOR (exclusive OR) returns a 0.  If one is a 1 and the other a 0, OR
and XOR both produce a 1 and AND produces a 0.  Finally, if both are 0, all
three produce a 0.

There is one other operator of this type, known as the bitwise NOT, but
it is not implemented through the MASK( function.  Since the primary use of
the bitwise NOT is to create indexes in decending order, this operation is
implemented through the DESCEND( function.  See DESCEND(.

The use of AND, OR and XOR is the same as in C and other low-level
languages that permit access to data at the bit level, and will rarely be
used by most SharkBase programmers.  Those who require these operations
already know how to use them and need no additional instructions for
Sharkbase.

Example in a program:

Given any screen color (See COLOR and SET COLOR), determine the reverse that
SharkBase would use in highlighting input windows during READ operations
(useful in using the same color to highlight messages and other text on the screen):

CLS
DO WHILE t
   INPUT 'Color.... ' to in
   low=mod(in,16)             ;separate the low-order and high-order bits
   hi=int(in/16)
   out=low*16+hi              ;the rest of these operations are too complex
   new=int(in/16)+16*mod(in,16)     ;  to explain...just be asured it works
   part1=mask(and,chr(out),chr(127))
   part2=mask(and,chr(in),chr(128+8))
   rev=mask(mask(or,part1,part2))
   rev=asc(mask(o,mask(a,chr(int(in/16)+16*mod(in,16)),chr(127)),mask(1,chr(in),chr(128+8))))
   :color=in
   ? 'Main Color..',in
   :color=rev
   ? 'Reverse.....',rev
ENDDO

MAX(


Compare two expressions of any type and return the larger.
  
 MAX(exp1,exp2)                           
                                              
 exp1    any expression                     
 exp2    any expression of the same type as 


MENU(


Lightbar menu function; allows point-and-shoot selection from an on-screen
menu.
  
 MENU(/,[,]) 
                                              
choices     the number of choices offered by the menu
hotkeys     one character for each possible option, beginning
                   with zero (normally the exit option)
width       the width of the menu lightbar

 Option:

seconds   exit MENU( after this many seconds; function returns value of 65

Type: numeric

The MENU( function pauses program execution and superimposes a movable
lightbar (reverse-video line) over a menu of selections previously written
to the screen, usually with TEXT.

The menu lightbar is moved up and down with the up arrow and dn arrow keys.  
If you press down arrow while on the bottom, the lightbar cycles automatically to 
the top.  Similarly, pressing up arrow while on the top cycles to the bottom.

The user can select any item by moving the lightbar over it and
pressing Enter, or entering its line number as a one-digit number.  In
either case, the line number selected is returned by the function, and the
key pressed stored in the system variable :KEY.  Both the function value and
:KEY can be tested in a subsequent DO CASE structure to determine the
program's next actions.

If the user presses 0 or , MENU( returns zero, although the first
line covered by the lightbar is 1.  Options over 9 can be accessed only by
the lightbar.

Alternately, you may choose to use the  option for this
function's first argument. Instead of the number of choices, a string may be
supplied. The length of the string determines the number of choices and the
letters in the string math the numbers of the choice.  For example, if if
you supplied a string literal or variable with the value "Qmdn" for
, pressing "Q" or "q" would return zero, "M" or "m" would return 1,
"D" or "d" would return 2, and "N" or "n" would return 3.   may be
caps or lower case; MENU( is not case-sensitive.

If any cursor key except up arrow, dn arrow and  is pressed, MENU( returns
the number of the line highlighted by the lightbar, and :KEY contains the
key number that would be returned by the INKEY( function. (If SET FUNCTION
OFF, all function keys have the same effect as these cursor keys.)

While the MENU( function is active, all other typewriter keys are
ignored.

Note: If an ON KEY structure is in effect, it is ignored while MENU( is
waiting for input.

Examples:

1. This is a program which shows specifically the values returned by
Menu( when any key is pressed:

CLS
@ 19,46 say 'Returns'
@ 19,64 say ':KEY'
DO WHILE t
   CURSOR 5,20
   var=MENU(10,20)
   @ 20,50 say var
   @ 20,65 say :KEY
ENDDO


2. In a real-life program:

ERASE
WINDOW 1,2,23,77 double            ;draw frame around screen
@ 1,3 say DATE(full)
@ 3,3 say CEN(:company,74)
@ 5,3 say CEN('Payroll Menu',74)
WINDOW 8,25,22,75 blank            ;use WINDOW to position TEXT
TEXT paymenu                       ;menu text in external file
WINDOW
CURSOR 10,23
ans=MENU(8,35)
IF ans=0 .or. :key=335
   CHAIN MENU
ENDIF
@ ans+9,23 say CHR(149)             ;• character as bullet
DO CASE
CASE ans=1
   ... etc.


3. Part of the same program using both hotkeys and timeout:

WINDOW 8,25,22,75 blank            ;use WINDOW to position TEXT
TEXT paymenu                       ;menu text in external file
WINDOW
CURSOR 10,23
hotkeys='Qeprsmwgf'                ;hotkeys can be a string variable
*                                  ;  this allows 8 options plus zero (quit)
ans=MENU(hotkeys,35,60)
IF ans=0 .or. :key=335 .or. ans=65 ;return of 65 means program timed-out
   CHAIN MENU
ENDIF
@ ans+9,23 say CHR(149)             ;• character as bullet
DO CASE
CASE ans=1
   ... etc.

MIN(


Compare two expressions of any type and return the smaller.
  
 MIN(exp1,exp2)                           
                                              
 exp1    any character or numeric expression
 exp2    any expression of the same type as exp1           
                  
 type: character/numeric                     
    
Given any two expressions of the same type, MIN( returns the lower
value.  It must be remembered that string comparisons are based on the ASCII
value of the characters in the two strings.  (Comparing two logical
expressions has no meaning.)

You may find that a comparison between a numeric expression and a
numeric field results in an error.  This can be avoided by ensuring both
arguments are an expression, accomplished most easily by adding 0 to a
field.

Examples:

1>? MIN(123,amount+0)         ;adding 0 ensures handling as an expression
    123.00
1>? MIN('Hello','Goodbye')
Goodbye

MONTHS(


Computes date differences in months.

 MONTHS(/num exp)

 <date1>      a string expression containing a valid date

 Options:

 <date2>      a string expression containing a valid date; when
              <date2> is specified, MONTHS( returns number of
              months between the two dates
 num exp      number of months before or after date1; when specified, 
              MONTHS( returns date that many months away

 Type: character/numeric

MONTHS( computes the difference between the two dates in months, or
computes a date a given number of months before or after a specified date.
Fractional parts of months are discarded.

If a computed date is after the last date of the month, the date will be
adjusted to the last day of the month.  For example, MONTHS('013190',1)
results in 022890.

Examples:

1>? MONTHS('04 06 90','04 29 90')
      0.00
1>? MONTHS('01/01/90','02/01/90')
      1.00
1>? MONTHS('02/01/90','01/01/90')
     -1.00
1>? MONTHS('01/01/90','01/01/92')
     24.00
1>? MONTHS('02/01/90',10)
120190
1>? MONTHS('01/01/90',-6)
070189

NDX(


Get information on index files in use.

 NDX(type [,indexnum] [,filenum])

 type       the name or number of the information required

 Options:

    the number of the index being checked (1 to 7);
                default is thge master index
 filenum    the number of the data file to be checked

 Type: character/logical

NDX( is used to primarily in programs to get the information on the
current environment in a form suitable for use in expressions.

The type can be given in either of two forms, a name or number (numeric
expression) as follows:

Type           Explanation                          Result
1 or Name      name of index file                   string
2 or Key       key on which index was created       string
3 or DBF_Name  name of data file on which index
                 was created                        string
4 or Filter    TRUE if filter or FOR clause was
                in effect when index was created    logical

Shortcut: When specifying type by name, only the first character is required.

Examples:

1>? NDX(n),NDX(key),NDX(dbf),NDX(filter)
CUST1.NDX CUSTNUM  CUSTOMER.DBF F

NTX(

This is an obsolete function identical to NDX(, which refers to the 
discontinued Clipper .ntx file type.  The older Clipper NTX indexes are 
no longer used in Shark. 

NUMTOC(

Convert a decimal number to a hexadecimal string.

 NUMTOC(type,number)

 type      the length of the string to be created
 number    the number to be converted

 Type: character

A general conversion function for converting decimal numbers into
hexadecimal values.  Input can be any number, and the returned string length
can be up to eight characters as follows:

The type can be given in either of two forms, a name or number (numeric
expression) as follows:
 Type      Range of Number            String Length Returned
   1      integer 0 to 255                  1 byte
   2      integer -32768 to 32767           2 bytes
   4      integer +/- 2 billion             4 bytes
   8      a floating point number           8 bytes
Shortcut: When specifying type by name, only the first character is required.

Types 1, 2 and 4 return hexadecimal integers.  Any fractional parts are ignored.

 When type is 1, this function is equivalent to CHR(.  Values outside
the range of 0 to 155 return the modulus of 256 for type 1.

The CTONUM(, RANK( and ASC( functions convert strings into numbers.

Do not confuse these function with STR( and VAL(, which convert decimal
numbers into their string representations, and vice versa.

Examples:
1>? NUMTOC(1,97)
a
1>? NUMTOC(2,25185)
ab
1>? NUMTOC(4,6513249)
abc

OUT(


Outputs a single character to a sequential file.
  
 OUT(str var [,filenum])                  
                                              
 str var      contains the character        

 Option:                                      
                                              
filenum  the DOS file number (between 1 and 4)          

 Type: logical                               

This function outputs the character in str var to the sequential file
(opened with the WOPEN( function).

If filenum is not given, filenum=1 is assumed.  OUT( returns T if successful, F otherwise.

This function is especially useful to communicate over the standard COM1,
COM2 devices, for conversion of Word Star or other non-standard files to
standard ASCII files, to encrypt/decrypt a file through a translation table.

See the functions IN(, ROPEN(, WOPEN(, CLOSE(, SEEK(, SSEEK(, READ(, and WRITE(.

PIC(


Formats a number or string.
  
 PIC(exp,format)                          
                                              
 exp                 is the number or string to be formatted 
 format              the format clause, a string expression  

 Type: character

This function returns the exp formatted with the format format.
See the command @ for the description of the format clauses.  PIC( is
especially useful in preparing numeric values for printing.

PIC( always returns a string, even when a number or numeric expression is
being formatted.

Examples:

PIC(


Formats a number or string.
  
 PIC(exp,format)
                                              
 exp                  is the number or string to be formatted 
 format              the format clause      

 Type: character


This function returns the exp formatted with the format clause
format.  See the command @ for the description of the format clauses.
PIC( is especially useful in preparing numeric values for printing.

PIC( always returns a string, even when a number or numeric expression
is being formatted.

Examples:
1>number=1123.89
1>format='9,999.99'
1>? PIC(number,'9,999.99')
1,123.89
1>? PIC(number,format)
1,123.89
1>format='9999'
1>? PIC(number,format)
1123
1>format='$$$,$$$.99'
1>? PIC(number,format)
 $1,123.89
1>format='$$$,$$$.999'
1>? PIC(number,format)
 $1,123.890
1>string='abcd'
1>format='xX9!'
1>? PIC(string,'xx9!')
abcD
1>? PIC(string,format)
abcD
1>format='X-X-X-X'
1>? PIC(string,format)
a-b-c-d
1>SET ZERO ON
1> ? 0,"*",str(0,5,2),"*",pic(0,"99.99"),"*","0"
      0.00 *  0.00 *  0.00 * 0
1>SET ZERO OFF
1> ? 0,"*",str(0,5,2),"*",pic(0,"99.99"),"*","0"
           *  0.00 *       * 0

PRINTER(


Test whether a printer is ready to print.
  
 PRINTER(printernum)                      
                                              

 Option:                                      
                                              
printernum  the number of the LPT port (1 or 2)             

 Type: logical  


Whenever a program has to print, it needs a printer turned on and
on-line. When it is unsuccessful in printing, Shark intercepts the customary
DOS error (the infamous "Abort, Retry, Ignore?") and ends execution.

The PRINTER( function gives programmers a way to ensure the printer is
correctly set up before sending output to the screen.  This makes it possible
to suspend execution under program control, prompt for correction action, or
even SPOOL the output to a disk file instead of the printer.

Examples in programs:

DO WHILE .NOT. PRINTER()
   WINDOW 10,10,15,69 DOUBLE
   @ 12,10 SAY CEN('Turn on printer and press any key . . .',60)
   RING
   CURSOR 13,39
   cc=INKEY()
   WINDOW
ENDDO
IF .NOT. PRINTER(2)                 ;test LPT2
   SPOOL printfil
ENDIF
IF PRINTER()
   SET PRINT ON
ENDIF

PUT(


Puts a string into a DOS file.
  
 PUT(str exp[,filenum])

 str exp         the string to overwrite with                

 Option:

 filenum         the DOS file number (between 1 and 4)       

 Type: logical                               


A DOS file was opened with the WOPEN( function; the character number
pointer was normally positioned with the SEEK( function.  This function
overwrites the file from the character chosen by the character number pointer
with the string str exp.

If filenum is not given, filenum=1 is assumed.  PUT( returns T if  successful, F otherwise.


See also the functions ROPEN(, WOPEN(, CLOSE(, SEEK(, and GET(.

Examples:
1>byte=CHR(13)
1>ok=WOPEN('test',3)
1>ok=SEEK(5221)
1>ok=PUT(byte,3)

RAND(


Gives a random number in the range 0<=n<1.
  
 RAND()                               

 Option:                                      
                                              
 seed    a number used to initiate the random series         

 Type: numeric  

A series of successive calls to the RAND( function will return a uniform
distribution of random numbers.

The first time RAND( is called, <seed> (any numeric expression) may be
specified. All subsequent calls should be without the seed.  If no initial
seed is provided, a random seed is chosen by the program.

RAND( always returns a number equal to or greater than 0 and less than 1.
If you need a random series of integers between zero and 5000, use
5000*RAND().

Note: if you provide the initial seed, every execution of RAND( ) will
return the same series of numbers.

RANK(


Converts a character to its ASCII number.
  
 RANK(str exp)
                                              
 str exp      the first character of this string is converted

 Type: numeric                               

The characters in the character set used by the computer are numbered
from 0 to 255.  For the first character of the string str exp, RANK(
returns the corresponding number. See also the functions ASC(, CHR(,
CTONUM(, and NUMTOC(.

Examples:

1>? RANK('x')
   120.00
1>? RANK('xyz')
   120.00

Note that only the first character of the string matters.

READ(


Reads a line of a sequential file.
  
 READ(str var[,filenum])
                                              
 str var      stores the line read in       

 Option:                                      
                                              
 filenum      the DOS file number (between 1 and 4)          

 Type: logical                               

This function reads the next line of the sequential file (opened with the
ROPEN( function) into the string variable str var.  If str var does not
exist, it will be created;  str var cannot be a matrix variable.

A line is terminated by the carriage return character (ASCII 13).  Since
the line is read into a string variable, it cannot be longer than 254
characters.

If filenum is not given, filenum=1 is assumed.  READ( returns T if
successful, F otherwise.

In Shark programs, READ( normally appears in an IF or DO WHILE command.

READ(, IN(, GET(, and WRAP( are the only functions that change the
contents of the memory variable used as an argument.

See the functions WRITE(, ROPEN(, WOPEN(, CLOSE(, IN(, OUT(, and SSEEK(.

Examples:

1. In Conversational Shark:

1>ok=ROPEN('a:label.prg')
1>ok=READ(line)
1>? line

2. Two programs to print a text file, TEST (in the second version it is
assumed that TEST has no more than 20 lines):
SET WIDTH TO 80
SET PRINT ON
IF ROPEN('test')
   DO WHILE READ(line)
      ? line
   ENDDO
   ok=CLOSE()
ENDIF
DIM CHAR 80 matrix[20]
SET WIDTH TO 80
SET PRINT ON
IF ROPEN('test',1)
   REPEAT 20 times VARYING num
      IF READ(input,1)
         matrix[num]=input,
      ELSE
         BREAK
      ENDIF
   ENDREPEAT
   IF CLOSE(1)
      ? matrix
   ENDIF
ENDIF

RECNO(


Gets the current record number in any open data file.
  
 RECNO(filenum)                           


 Option:                                      
                                              
 filenum    the number of any open data file; default is the selected data file            

 Type: numeric                               

This function returns the record number of the current record of any
specified data file; if no filenum is given, returns the record number the
selected file.  Note that ? RECNO() displays the current record number in the
form specified by the system variable :PICTURE (see Section 2.7).

Shark also has a more limited form of this function, #, which applies
only to the selected data file.

Examples:
1>USE employee
1>USE#2 customer
1>? RECNO(1)
     1.00
1>GO BOTTOM
1>? RECNO(1)
     6.00
1>GO TOP
1>? RECNO()
     1.00
1>SKIP#2 2
1>? RECNO(2)
     3.00

REMLIB(


Removes a library entry.
  
REMLIB(volume)                             
                                              
volume  the number of the library entry to be removed.

 Type: logical  

This function deletes a library entry.  The function accepts the library
volume number you wish to delete as its argument and returns T (true) if the
delete operation was successful, F (false) if not.

Once a library entry (volume) is deleted, its space in the library is
made available for new text.

Libraries are created with the SET LIBRARY TO command.

Example:

1>? REMLIB(50)
T

REPLACE(


Replaces, in a string expression, all occurrences of a string with another
string.
  
 REPLACE(str exp,)     
                                              
 str exp      replace in this string expression              
 str exp      all occurrences of this string
 str exp2    with this string              

 Type: character

This function looks up the first occurrence of str exp.  This occurrence is replaced with .  This process
continues as long as str exp.

Examples:

1. A field contains a number as right justified characters, padded on the
left with blanks.  The following REPLACE( changes these numbers to right
justified numbers padded on the left with zeros.
1>number='     123'
1>number=REPLACE(number,' ','0')
1>? number
00000123

2. In writing checks, dollar amounts may be left padded with dollar signs:

1>number='     123.11'
1>number=REPLACE(number,' ','$')
1>? number
$$$$$123.11

3. Renaming a variable in a program line.  The variable OLDN is renamed FIRSTNUMB.

1>line='newn=oldn+oldn+(oldn/3)'
1>line=REPLACE(line,'oldn','firstnumb')
1>? line
newn=firstnumb+firstnumb+(firstnumb/3)

RESET(


Sets a bit in a string to 0.
  
 RESET(str exp,bit position)
                                              
 str exp       the string or string expression on which the  
                   function is to act         
 bit position  the number of the bit, numbered from the left 
                   starting at 1, which is to be set to zero   

 Type: logical                               

A bit is any of the eight binary digits in a character's ASCII number
representation.  Each bit can have only one of two possible values, 0 and 1.

The SET( and RESET( functions are used to manipulate the bits within a
string or string expression.  SET( makes a bit 1, and RESET( makes a bit 0.
The BIT( function tests the value of a specific bit.

Among the chief uses for these functions is compression of logical
(true/false) data by using just one bit for each data item instead of an
entire byte for a logical field or two bytes for a logical variable.

See the BIT( function for programming examples.

Examples:

1>str='PS'
1>? BIT(str,15)
T
1>str=RESET(str,15)
1>? str,BIT(str,15)
PQ F


Gets the right-hand part of a string.
  
 RIGHT(str exp, num exp)                  

 str exp   the string from which the new string is formed    
 num exp   the number of characters to place in the new string    

 Type: character

This function returns the last (that is, the rightmost) num exp
characters from the string str exp.

If num exp is greater than the width of str exp, this function
returns all of str exp.

Example:
1>a='David Bark'
1>? RIGHT(a,5)
 Bark
1>? RIGHT(a,50)
David Bark

ROPEN(


Opens a DOS file for reading.
  
 ROPEN(str exp [, filenum ])                  
                                              
 str exp   the file name

 Option:                                      
                                              
 filenum   the DOS file number (between 1 and 4)          

 Type: logical                               

This function opens str exp, a DOS file (in particular, a sequential
file or input device, such as COM1), for reading only.  The current position
pointer (see the SEEK( function) is set to the beginning of the file.

If filenum is not given, filenum=1 is assumed.  If no file extension is
given, the extension TXT is used.

ROPEN( returns T if successful, F otherwise.

See the functions WOPEN(, CLOSE(, READ(, WRITE(, IN(, OUT(, GET(, PUT(,SEEK(, and SSEEK(.

Examples:

1>? ROPEN('a:label.prg')
T

In an Shark program, ROPEN( normally appears in an IF command:

IF ROPEN('file',2)
   DO WHILE READ(data,2)
      ? data
   ENDDO
   ok=CLOSE(2)
ENDIF

ROW(


Gets print row position.
  
 ROW()                                        

 Type: numeric                               
This function gives the current row (line) position of the cursor; if the
printer is on, it returns the column position of the printer head.  See the
commands SET PRINT ON and SET FORMAT TO PRINT, and the function COL(.

Example:

@ ROW()+1,COL()+3 SAY 'Hello'
prints 'Hello' starting on the next line three characters to the right of the end 
of the last printing.

SEEK(


Goes to a given character number in a DOS file.
  
 SEEK(num exp [,filenum])                   
                                              
 num exp      the character number          

 Option:                                      
                                              
 filenum      the DOS file number (between 1 and 4)

 Type: logical                               

This function repositions the character number pointer in the DOS file
(opened with the ROPEN( or WOPEN( function) to the value given by num exp.

 If filenum is not given, filenum=1 is assumed.  If no file extension is
given, the extension TXT is used.

If SEEK( is successful, it returns T (true); otherwise F (false).  In a
Shark program, SEEK( normally occurs in an IF or DO WHILE command.

Once the character pointer is properly positioned, use the GET( and PUT(
functions to manipulate the characters.

See the functions SSEEK(, ROPEN(, WOPEN(, CLOSE(, GET(, and PUT(.

Example:

1>ok=ROPEN('a:label.prg',4)
1>ok=SEEK(522,4)

SET(


Sets a bit in a string to 1.
  
 SET(str exp,bit position)                
                                              
 str exp        the string or string expression on which the  
                             function is to act         
 bit position  the number of the bit, numbered from the left 
                             starting at 1, which is to be set to 1      

 Type: logical                               

 A bit is any of the eight binary digits in a character's ASCII number
representation.  Each bit can have only one of two possible values, 0 and 1.

The SET( and RESET( functions are used to manipulate the bits within a
string or string expression.  SET( makes a bit 1, and RESET( makes a bit 0.
The BIT( function tests the value of a specific bit.

Among the chief uses for these functions is compression of logical
(true/false) data by using just one bit for each data item instead of an
entire byte for a logical field or two bytes for a logical variable.

See the BIT( function for programming examples.

Examples:

1>str='PQ'
1>? BIT(str,15)
F
1>str=RESET(str,15)
1>? str,BIT(str,15)
PS T

SPACE(


Gets the amount of space left in the data space.
  
 SPACE()                                      

 Type: numeric 


This function returns the available memory in the 64K data space (see Appendix A).

Example:

1>SPACE()
 27155.00

SSEEK(


Goes to a given line number in a sequential file.
  
 SSEEK(num exp [,filenum)                

 num exp      the line number               

 Option:                                      
                                              
 filenum      the DOS file number (between 1 and 4)          

 Type: logical                               

This function repositions the line number pointer in the sequential file
(opened with the ROPEN( function) to the value given by num exp.

If filenum is not given, filenum=1 is assumed.  If no file extension is
given, the extension TXT is used.

If filenum is not given, filenum=1 is assumed.  If no file extension is
given, the extension TXT is used.

See the functions SEEK(, ROPEN(, WOPEN(, CLOSE(, READ(,  IN(, and OUT(.

Example:

1>ok=ROPEN('a:label.prg',4)
1>line=''
1>ok=SSEEK(5,4)
1>? ok
T
1>ok=READ(line,4)
1>? line
GOTO top
1>ok=SSEEK(900,4)
1>? ok
F

STR(


Converts a number to a string.
  
 STR(num exp,[,])           
                                              
 num exp         the number to be converted 
    the width of the string

 Option:                                      
                                              
  the number of decimals    

 Type: character

This function gets a number by evaluating the num exp, and converts it
into a string of given width.  Optionally, the number of decimals can be
specified (the default is 0).  See also PIC(.

Examples:
1>x=123.456
1>? STR(x,8)
     123
1>? LEN(STR(x,8))
     8.00
1>? STR(x,10)
       123
1>? STR(x,10,1)
     123.1

When combined with the VAL( function, STR( is a convenient way of
rounding decimal numbers with a given precision.  

For example:

1>:PICTURE='9999.99999'
1>a=29.95748
1>? a
  29.95748
1>? VAL(STR(a+.005,10,2))
  29.96000
1>? VAL(STR(a+.00005,10,4))
  29.95750

SUBSTR(


Gets a substring of a string.
  
 SUBSTR(str exp, , )
                                              
 str exp         the string from which the new string is formed   
      the position from which the new string is taken                    
    the number of characters to place in the new string

 Type: character

This function, a synonym for the $( function, takes the string in
str exp from position  (fractions are thrown away); the
number of characters taken is .  (In both numeric
expressions, the fractions are disregarded).

Examples:

1>name='David Barberr'
1>? SUBSTR(name, 7,3)
Bar
1>? SUBSTR(name, 7,12)
Barberr
1>? LEN(SUBSTR(name,7,12))
      7.00

Note that SUBSTR(name,7,12) is of width 7, not 12; there are only 7
letters left in name from position 7.

1>s=3
1>t=1
1>? SUBSTR(name+name,(s+t)/2,1.9)
a

Note that 1.9 was taken as 1.

TEST(


Tests a string whether it is a valid expression.
  
 TEST(str exp)                              
                                              
 str exp the string to be tested 

 Type: logical


This function tests the string in str exp as to whether it is a valid
expression; in particular, all variables must be defined and must be of the
proper type.  It returns T if it is, F otherwise.  If the test is successful,
TYPE( can be used to find the type of the expression.

In an Shark program, use TEST( to find out whether a selection
criteria typed in by the user is correct.  Or use it to ensure that a variable
exists in a subroutine that may be called from several programs.

Examples:

1>? TEST('check=0')
F                                   false because check is not defined
1>check=0
1>? TEST('check=0')
T
1>? TEST('check=0.or.check=1')
T
1>? TEST('check="A".or.check=1')
F                                   false because "A" is of character
                                    type
1>? TEST('num')
F
1>num=5
1>? TEST('num')
T
1>? TEST('num+')                    false because the second operand
                                    is missing
F
IF .NOT. TEST('check')
   check=0
ENDIF

TIME(


Gets the system time.
  
 TIME(type)

 Option:                                      
                                              
 type      one of three types of information requested, as listed below                          

 Type: character


This function returns a string containing the current system time, and
changes the format of the system variable :TIME to this format. (See the
system variable :TIME in Section 2.  Recall that :TIME is initialized when
Shark starts up, but can be reinitialized with a :TIME= command.)

 The type can be given in either of two forms, a name or number (numeric
expression) as follows:

Type                Explanation                                      Example
1 or HMS         Hours,minutes,seconds,hundredths                17:26:36.07
2 or AMPM        Hours,minutes with AM/PM                        5:36 pm
3 or Seconds     Seconds since midnight                          62804.80

Shortcut: When specifying type by name, only the first character is required.
The default parameter is 1, the time in the 24-hour format hh:mm:ss.hh.

Examples:

1>? :TIME
15:45:59
1>? TIME(2)
 3:46 pm
1>:TIME
 3:46 pm
start=VAL(TIME(seconds))
program lines
finish=VAL(TIME(seconds))
? 'Program execution took',start-finish,'seconds.'

This displays how long the running of <program lines> took, in seconds.

TRIM(


Trims blanks from the right-hand side of a string.
  
 TRIM(str exp)                              
                                              
 str exp        the string to be trimmed    

 Type: character

Shark stores strings in fields padded on the right with blanks. In actual use, 
these blanks may get in the way.  TRIM( gets rid of the blanks on the right 
of a string.  TRIM( can be used in the key of an index.  See also LTRIM( .

Examples:
1>a='Vancouver     '
1>b='BC'
1>? a+','+b
Vancouver     ,BC
1>? LEN(a)
    14.00
1>? trim(a)+','+b
Vancouver,BC
1>? LEN(TRIM(a))
     9.00
1>blank='     '
1>? LEN(TRIM(blank))
     1.00

Note: TRIM(blank) is a single blank.



TYPE(


Gets the type of an expression.

 TYPE(exp)

 exp          =  any expression              

 Type: character

For an expression, exp, this function returns the type of the
expression as a one character string:
C    for character
L    for logical
N    for numeric
M    for memo 
F    for float      ;a type used by other xBase languages; treated as N internally
D    for date       ;a type used by other xBase languages; treated as C internally
U    Undefined      ;created by GLOBAL or VARIABLES command, but not yet given
                     a value or type

To test whether a string is a valid expression, use the TEST( function.

Examples:
1>a='name'
1>? TYPE(a)
C
1>? TYPE(a+a)
C
1>n=12
1>? TYPE(a+n)
1. Invalid variable type found when executing an expression.
1>? TYPE(a<a)
L
1>? TYPE(a<a .OR. n<5)
L
1>? TYPE(note)
M
1>? TYPE(date)
D
1>TYPE(n+5/10)
N

UPPER(


Converts a string to upper case.
  
 UPPER(str exp)                             
                                              
 str exp    the text to be converted to upper case           

 Type: character

All lower-case letters in the str exp are converted into upper case by
the UPPER( function, which is a synonym for the !( function.  See also the
LOWER( function.

Examples:

1>a='Aa12b'
1>? UPPER(a)
AA12B
1>? UPPER('David!')
DAVID!
Note that only the lower-case letters are changed.

VAL(


Converts a string to its numeric value.
  
 VAL(str exp)
                                              
 str exp      the string to be evaluated    

 Type: numeric                               

This function takes the string str exp which is a number, and returns
it as a number.  If the whole string cannot be interpreted as a number, it
takes as much of the front part as it can.

Examples:

1>a='123.23'
1>? VAL(a)
   123.23
1>? VAL(123.23)
1. Invalid variable type found when executing an expression.
1>? VAL('a12')
     0.00
1>? VAL('12a')
    12.00
1>? VAL(DATE(2))
yields the current month as a number.

WOPEN(


Opens a DOS file for writing.
  
 WOPEN(str exp[,filenum])                 
                                              
 str exp      the file name

 Option:                                      
                                              
 filenum      the DOS file number (between 1 and 4)          

 Type: logical                               

This function opens the DOS file, and in particular, the sequential file
str exp (or output device, such as COM1:) for writing; if the file does not
exist, it will be created.  If filenum is not given, filenum=1 is assumed.  If
no file extension is given, the extension TXT is used.  It returns T if
successful, F otherwise.

See the functions ROPEN(, CLOSE(, GET(, PUT(, SEEK(, SSEEK(, WRITE(,
READ(, IN(, OUT(.

Example:
1>ok=WOPEN('a:label.prg')
1>? ok
T

In an Shark program, WOPEN( normally appears in an IF command:

IF WOPEN('file',2)

2. Two programs to print a text file, TEST (in the second version it is
assumed that TEST has no more than 20 lines):

SET WIDTH TO 80
SET PRINT ON
IF ROPEN('test')
   DO WHILE READ(line)
      ? line
   ENDDO
   ok=CLOSE()
ENDIF

WRAP(


Wraps text for output.

 WRAP(str var, num exp)                   
                                              
 str exp        the string to be wrapped    
 num exp        the line width              

 Type: character

This function returns one line of text with word wrapping from the string
in str var; str var now contains what is left of the string.  In other
words, the string returned will contain as many words as will fit in a line
(the line width is given by num exp).  If the whole contents of str var is
one line, str var becomes the blank string (of length 1)

WRAP(, IN(, GET(, and READ( are the only functions that change the
contents of the memory variable used as an argument.

Examples:
1>text='This text line is going to be wrapped in a printed line of width 30.'
1>? text
This text line is going to be wrapped in a printed line of width 30.
1>temp=text
1>WRAP(temp,30)
This text line is going to be
1>? temp
wrapped in a printed line of width 30.
1>WRAP(temp,30)
wrapped in a printed line of
1>? temp
width 30.
1>WRAP(temp,30)
width 30.
1>? temp
1>? LEN(temp)
     1.00

WRITE(


Writes a new line into the sequential file.
  
 WRITE(str var[,filenum])                 

 str var   the line to be written        

 Option:
                                              
 filenum      the DOS file number (between 1 and 4)          

 Type: logical                               

     This function writes (appends) the contents of the string variable
str var to the end of a sequential file opened with the WOPEN( function.
     If filenum is not given, filenum=1 is assumed.  WRITE( returns T if
successful, F otherwise.
     See the functions ROPEN(, WOPEN(, READ(, IN(, OUT(, GET(, PUT(, and CLOSE(.

Example:


1>ok=WOPEN('customer.frm',2)
1>ok=WRITE('FIELDS - cust,orderno,amount',2)
1>ok=CLOSE(2)
creates the CUSTOMER.FRM report form file:
FIELDS - cust,orderno,amount
     Now the command REPORT CUSTOMER will run the report.  This example
illustrates how a program can be written that creates a report form file.
     In an Shark program, WRITE( normally appears in an IF command:
IF WRITE('file',2)

EXPRESSIONS


Expressions can be formed from constants and variables using operations,
relations, and functions.  There are three types of expressions: numeric,
string, and logical.

Numeric expressions are built up from numeric constants, numeric
variables, and from functions that give results of numeric type; they are
formed with the operations: +, -, *, /, and the parentheses: ( and ).

String expressions are formed from string constants, string variables,
and from functions that give results of character type; they use the
operation + and the parentheses: ( and ).

Logical expressions (also called conditions) are formed from logical
constants, logical variables, functions that give results of logical type, and
the results of relations; they use the logical operations: .AND., .OR., .NOT.,
and the parentheses: ( and ).

Examples:


In these examples, str1, str2 are string variables, num1, num2
are numeric variables, log1, log2 are logical variables:

String expressions:

str1
str1+str2
str1+TRIM(str2)
str1+STR(num1+num2,10,2)+'Bach'

Numeric expressions:
num1
num1+5
(num1+5)/5
num1+(num2*VAL(str1))
LEN(str1)+LEN(TRIM(str2))+2

Conditions (logical expressions):
num1 < num2
num1+num2+LEN(str1) <> 15 .AND. .NOT. EOF
(str1='Boston') .AND. (num1 <> LEN(str1)).AND.log1.AND.(.NOT.log2)

Variables are expressions which are used to represent changeable
information. The values they contain can be easily changed by using Shark's
many commands and functions.

A variable can stand for many different values; you can use the name
of a variable in place of all the specific values you want or expect it to
represent.

In Shark there are three main kinds of variables: fields,
memory variables, and system variables.

FIELD VARIABLES
MEMORY VARIABLES
SYSTEM VARIABLES

FIELD VARIABLES


Fields are storage places for data in data files.  Fields make up each
record in a data file.  Each item in a record (e.g., name, address, amount)
is one field.

Fields are a special type of variable; their value reflects the content
of the current record of a data file.  The value changes as the record
pointer moves from one record to another.


MEMORY VARIABLES



Memory variables are temporary storage places cleared when you quit
Shark (unless you write them to disk with the SAVE command).

Create a memory variable by assigning a string, number, or logical value
to a name of 1 to 10 characters with the = or STORE command.  Memory
variables' data types are Character, Numeric, or Logical.  Text surrounded
by quotes creates a character variable.  A number with no quotes creates a
numeric variable.  Logical values (T,t,F,f, etc.) create logical variables.

You can use 128 memory variables at a time. Arrays, or matrix variables,
(defined with the DIM command) can contain many values per individual
variable.  Use the LIST MEMORY command to see all currently defined memory
variables.

Memory variable names are 1 to 10 characters in length, with the first
character a letter; remaining characters can be letters, numbers, colons
(:), or underlines (_).

These commands use memory variables:

    Command    Stores
    ---------  --------------------------------------------------
    =          Any string or value
    @...GET    User input (using READ)
    ACCEPT     String input
    AVERAGE    Average of numbers
    COUNT      No. of records
    INPUT      Any user input
    REPEAT...  Count passes in loop (with VARYING)
    SUM        Sum of numbers
    STORE      Any string or value
    WAIT TO    User input

All of the above commands except @...GET will create a memory variable
if it does not already exist.  Some DOS file-handling functions also create
and use memory variables. These include IN(), GET(), and READ().

RELEASE clears some or all (with the ALL clause) memory variables and
makes room for others. CLEAR closes all memory variables and all open data
files (it's a combination of RELEASE ALL and CLOSE ALL).

RELEASE ALL is automatically invoked when you use CHAIN to call a new
command file from within another.  Transfer memory variables from one command
file to another, chained command file, use the GLOBAL command.

SAVE TO saves the current memory variables and their current values to a
disk file (default extension MEM).

RESTORE recalls memory variables stored in a specified memory variable file.

PRECEDENCE


In an expression such as

2+3*4

Shark has to decide whether to perform the + first (result: 20) or
the * first (result: 23).  The Rules of Precedence decide such questions.
Functions have the highest precedence.

Arithmetic operations have the second highest precedence; among
themselves:

*, /
then
+, -

Relations are next; among themselves they all have the same precedence.
Logical operations come last; among themselves:

.NOT.
then
.AND., .OR.

When two or more of the above have the same precedence, they are
performed from left to right.

The parentheses: ( and ) have higher precedence than functions,
operations, or relations.  Thus you can set the precedence explicitly using
parentheses.

This means that you do not have to get involved in familiarizing yourself
with the Rules of Precedence.  If you want + first, write

(2+3)*4
If you want * first, write:
2+(3*4)

The parentheses tell Shark how you want the operations performed.  Since Shark
throws away the parentheses when the expression is compiled, you gain
readability by using parentheses - and lose nothing.

COMMENT (*)


Place comments -- notes -- in programs.
  
 * string                                 

 Option:                                      

 string   any text line: the comment        
     
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.

Example:

In a program:
********************************************************************
* This is the start of the payroll computation module
* Programmer: David Simco
* Date: 1999/08/26
********************************************************************
USE employee INDEX employee  ;opening EMPLOYEE ordered by name

= (equals)


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

 memvar=exp
 filenum 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 macros (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'

Comment: = is the only Shark command verb that does not appear
at the start of the command line. All of the following are identical in effect:

1>employee[1]='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 third and eighth command lines make one print line.

@

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]

 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

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).  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.

 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 line1var 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 (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.  On the 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.

See manual for more on Get Tables, formats and examples.

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 matrix variables.

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; use
anywhere else is 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


Edit fields in many records.

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

 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

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

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                             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                             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 toward the beginning of
                                   the file and redisplays the BROWSE screen

Alt-X                              skips one screenful of record 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 key.

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

SharkBase offers two options that allow users to format their BROWSE
screens to their specific requirements.

BROWSE OFF suppresses the standard BROWSE 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>BROWSE OFF

It should be noted that the GET Table for BROWSE OFF is always erased
immediately after the command is executed, in contrast to both EDIT OFF and
READ which retain their GET Tables.  THerefore, if using BROWSE OFF in a
loop, be sure to recreate the screen and its associated ON FIELD structure
for each iteration, either by redrawing the TEXT and executing the ON FIELD,
or by saving and restoring gets as required (see SAVE).

BROWSE 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>BROWSE TEXT add_empl

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

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  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, Sub Rosa International Inc.
;
;This routine replaces the first five characters in a passed string with the characters SHARK
;
;  Assemble with 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 to go into Shark (option 9), show the
Shark prompt.  Option 8 exits to the operating system.

CASE

The switch in the DO CASE program structure.

CASE cond

cond  if this condition is satisfied, the following program
segment 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 

    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  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 ; to use them, the  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:

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 is radically different.
To clear the screen, use the CLS 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


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:
1>CLS
1>CLS 2,4
1>CLS 12,12

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

Every character displayed on the screen has an attribute byte that
determines how the character is displayed.  For monochrome monitors, the
character may be bold, underlined, reverse, and so on.  For color monitors,
both the background and the character has color.  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:

BACKGROUND     ========CHARACTERS=========  BLINKING        BRIGHTNESS
(color only)   (color)     (monochrome)
------------   ----------  ---------------  --------------  ------------
  0 - black     0 - black     0 - normal       0 - no blink  0 - normal
 16 - blue      1 - blue      1 - underline  128 - blink     8 - bright
 32 - green     2 - green   112 - reverse
 48 - cyan      3 - cyan
 64 - red       4 - red
 80 - magenta   5 - magenta
 96 - brown     6 - brown
112 - white     7 - white

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.

1>COLOR 20,2,0,12,79
sets background blue and foreground red in lines 2 to 12.

2.

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.

1>COLOR 17,2,10,4,12
underlines the text in a small box three lines deep and 3 characters wide on a
monochrome monitor.

4. The following program illustrates the use of the COLOR command on a
color monitor:

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

5. 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.

6. 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

COMPILE

Compile an Shark program.

 COMPILE file [LINK]

 file  the name of the program file

 Option:

 LINK    If SET DO OFF, causes COMPILE to work as if SET DO ON 

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 you wish to compile many programs in one step, create a program (call
it, say, PROJ.PRG) as follows:

COMPILE prog1
COMPILE prog2
COMPILE prog3

Then

1>DO proj
will compile PROG1, PROG2, PROG3.  Such a program should not use any memory
variables, since a CLEAR is executed before every COMPILE command.
     SET ECHO ON to have all program lines displayed as they are compiled.

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

     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]

 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.

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

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:
 or Ctrl-S        moves the cursor back one character
 or Ctrl-D       moves the cursor forward one character
Ctrl-             moves to the beginning of the editing field
Ctrl-            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
             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 SR-Info and up to
500 fields in VP-Info Professional and Shark.  Allows unlimited number of
records in Shark.  Not compatible with dBASE or early VP-Info and SR-Info
versions.

Type 1 - Compatible with VP-Info and MAX Type 1 files.  (MAX is an earlier
versions of SR-Info and VP-Info Professional); Type 1 files can have up
to 256 fields in SR-Info and up to 500 fields in VP-Info Pro and 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 SR-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).

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

Example:

1>CREATE custfile
shows the following screen after all the fields have been entered:

Sunday, August 12, 1990
                              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

 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)


Define an array as a matrix.

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

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

 Option:

    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

                     These are not options -----+
                                                |
                                                V
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]

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]
(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]
(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).  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

DIR



Directory listing.

 DIR file specification

 Options:

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

DIRF

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

DIRF file specification
Options:

file specification  a file name, with optional DOS windcards;
                          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.

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

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 level of nesting is 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 exiting 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; 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. 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).
*  (C) 1990 Sub Rosa Publishing Inc.  (Author: Sidney L. Bursten)

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
* In the following TEXT, note the way the double carats (^^) are used to force
* one carat to print on the screen.
TEXT

REC:  prev PgUp  next   PgDn                       DELETE RECORD ^^U
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



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
      SOUND 11
      GOTO top
   CASE #<1            ;backed up past beginning of file; start again at bottom
      SOUND 11
      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



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 (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
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


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       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>                                
                                              
          SHARK.SET file only                 
                                              
 num const  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  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, although 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  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  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
of PROG2:

GLOBAL transact,process,custrange,type,trdate
and of PROG3:
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.

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:

1.
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.

2. 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

3. 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.

4.   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



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 selction; only records for which cond is true are   
               included in the index.         
     

The INDEX 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, 


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: SCOPE and LIMIT  are synonyms

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.

SCOPE is a synonym for LIMIT

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 file
as appropriate, see Section 1.

LOCATE


Search for a record that satisfies the condition.

LOCATE scope FOR cond                  

Option:  scope   search only within the scope (default scope: 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 time 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 scope in Shark, however, 
LOCATE does not require anything other than the keyword to make the scope 
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 SET NETWORK 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=                              
          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:
     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:
1.   Do not use MODIFY in a program
2.   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


NOEFFECTS



Suppress special effects.


NOEFFECTS

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
IF cust=mcust ;the start of the processing for the current customer

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
   
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; it is equivalent
to CASE t (true).

See 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


[NOTE: Printer control codes don't have any effect when "printing" to a
file such as when you are working with Windows 7/8 or Linux]

Send a printer-control string to the printer or another device under DOS.

PSTRING 

  a list of characters, in a special format, to be
                output to the printer or the printer file

With the enormous variety of printers, combined with their often-obtuse
control languages, more powerful commands to pass control characters to
printers has become necessary.

SharkBase offers a flexible way to specify characters in any form you
wish.

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

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.
  
 REMARK ['']

 Option:
                                              
 ''       the text line to be displayed             
     
     Same as the command ?.   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 [,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

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: Printer control codes don't have any effect when "printing" to a file such as when you are working with Windows 7/8 or Linux] 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: Printer control codes don't have any effect when "printing" to a file such as when you are working with Windows 7/8 or Linux] 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. 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. Look at the examples of report form files given in the Reference Guide. 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. A * 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:

Form one 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 Appendix A.)

The default file extension is MEM.

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 destoyed, 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. Without the NOEFFECTS keyword in the SHARK.SET file, RING uses one of the
sound effects from its effect library, and does not send anything to the
screen.
2. With the NOEFFECTS keyword in the SHARK.SET file), RING sends character 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).

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 and 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.  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 no option is given, MEMORY is the default.  That is, SAVE TO TEST 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.

If your computer has a ram disk, it is best to save and restore screens
and gets to it rather than a hard disk.

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 num exp
 SCOPE key exp
 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

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 Shark, the visual impact of these transfers can be enhanced by using
any of seven special effects, each accompanied by a characteristic sound
effect.  The seven special 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.

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:
SCREEN 2          ;direct output to background screen
        ;draw the background screen
SCREEN 1          ;make the visible screen active
SCREEN TEAR       ;use effect to move Screen 2 to 1 -- with NOEFFECTS,
                  ;  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.
1>SCROLL 2,5
1>SCROLL 5,2

2. Scrolling demo.  Needs two data files: CUST, with fields CUSTN
(customer number), NAME (customer name), ADD:1 (address); INVEN 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   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


Select 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>SELECT 1
1>USE invoice
1>USE#2 customer
1>LIST

The LIST command will list from the invoice file and the customer file
will be opened as file 2.

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 controls)


Set up environmental controls.

 SET  ON/OFF

    is chosen from the list:

               ADD, ALTERNATE, ANSI, BELL, CARRY, CONFIRM,
               CONSOLE, DEBUG, DELETED, DELIMITER, DISPLAY,
               DIVZERO, DO, ECHO, EJECT, END, ERROR, ESCAPE,
               EXACT, EXECUTION, FUNCTION, GET, HEADING,
               INTENSITY, KEEP, LINE, LOCK, MENU, MONO, NETWORK,
               PRINT, PROMPT, RAW, SAVE, SCREEN, SNOW,
               STEP, TALK, TEXT, TRIM, UPPER, ZERO

 Switch:
 ON or OFF

SETS (miscellaneous)


Shark comes with some of these features ON, and some OFF; an
asterisk marks the default.

     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 versions. It has
                         no effect.
                *OFF     SET ANSI has no effect in Shark.

     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.
                 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.)

     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.

     DO         *ON      Subroutines are compiled as overlays to the
                         calling program (see DO command).
                 OFF     Subroutines are not compiled in the calling
                         program. Instead, the compile produces files
                         containing the compiled environment for the
                         subroutines (with the extension ENV).  May be
                         useful in developing and debugging very complex
                         applications.

     ECHO        ON      When compiling an Shark program
                         (including the compiling done on-the-fly before
                         running an uncompiled program), the program
                         lines are shown on the screen as they are
                         compiled; it has no effect while programs are
                         actually being executed.
                *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.
                 OFF     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.
                 OFF     An active ON ERROR structure is ignored and
                         Shark reacts as though the structure
                         did not exist.

     ESCAPE     *ON      Hitting  aborts program execution, or if an
                         ON ESCAPE structure is in effect, program
                         execution jumps to the start of the structure.
                 OFF      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').
     EXECUTION   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
                         pressed.
                 OFF     Disable the usual functions of the function keys
                         .  Pressing a function key will
                         produce a Ctrl-W (or a carriage return/line
                         feed if SET END OFF); the number of the
                         function key pressed is available to the
                         programmer in the :KEY system variable.

     GET         ON      A Get Table 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.)
                *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.
                 OFF     Editing fields are shown in normal video.

     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.
                 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.
                         Not required unless both monochrome and color
                         adapters are present in your computer; put the
                         appropriate command in your CNF file.)
                 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
                         TO command).
                *OFF     facilities are not turned on (Shark
                         Netywork Edition Only.
						 
     PRINT       ON      Output produced such by relative display commands
                         as LIST, DISPLAY, ?, and ?? is sent to a
                         printer (or to a text file if SPOOL is in
                         effect).  In the interactive mode, the effect
                         of SET PRINT ON is turned off when the prompt
                         appears, so that the commands will not be
                         printed.  Shark will continue
                         printing the results of the commands.
                *OFF     The output is sent to the screen.  This flag is
                         always set OFF when  is pressed or an
                         error is encountered while running a program.
						 
	                 [NOTE: "SET PRINT ON" DOESN'T WORK IN WINDOWS 7/8 or
		          LINUX WHEN USING A DOS EMULATOR.  "SET PRINT ON" MUST 
			      BE COMBINED WITH "SPOOL" TO DIRECT OUTPUT TO A FILE.  
			      EXAMPLE:
						 
					 SPOOL TEST.TXT
					                                                                                                                                                                                                                                                                                                                                                                           SET PRINT ON
						 
			     PRINTER SPOOLING TO A FILE IS ENDED WITH THE SIMPLE
		         "SPOOL" COMMAND:
						 
					 SET PRINT OFF
					 SPOOL
						 
			     NOTE THAT THE PRINT INSTRUCTION IS ENCLOSED BY THE 
		          TWO SPOOL COMMANDS!]

     PROMPT      ON      A dot prompt, as in dBASE.
                *OFF     The n> prompt, 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.
                 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, Shark may cause screen
                         flicker called "snow".
                 OFF     Snow is suppressed, 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.
                 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.
                *OFF     Execute Shark programs continuously.

     TALK       *ON      Shark messages from commands are
                         displayed.  This flag is always set when 
                         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 IBM monochrome and color monitors.

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+blink+brightness) from the following tables:


BACKGROUND ========CHARACTERS========= BLINKING BRIGHTNESS
(color only) (color) (monochrome)
---------- ---------- ---------------- ---------------- ----------------
0 - black 0 - black 0 - normal 0 - no blink 0 - normal
16 - blue 1 - blue 1 - underline 128 - blink 8 - bright
32 - green 2 - green 112 - reverse
48 - cyan 3 - cyan
64 - red 4 - red
80 - magenta 5 - magenta
96 - brown 6 - brown
112 - white 7 - white

Color Examples:

SET COLOR TO 20 Sets default attribute to red on blue (4+16)
COLOR=31 Sets DEFAULT attribute to bright white on blue (15+16)
COLOR 36,2,0,12,79 Changes rows 2-12 to red on green (4+32)

SET DATE


Set the default form for dates.

 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/1991' as follows:
     'mmddyy'                             123191
     'ddmmyy'                             312191
     'yymmdd'                             911231
     'mmddyyyy'                           12311991
     'ddmmyyyy'                           31121991
     'yyyymmdd'                           19911231
     These are the six available options.

SET DEFAULT


Set the drive letter of the default disk drive for data and index files.

 SET DEFAULT TO drive letter

 drive letter  the drive letter of the default drive

This command sets the drive letter of the default drive for data and
index files.  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, 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.

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:.

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 command 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  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 for the printer when the printer does not support a standard
formfeed control character.

 SET LENGTH TO num exp

 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

If SET LINK is used, SET RELATION should be avoided.

SET MARGIN


Specify text margin for 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 MEMORY


An obsolete command retained in the language for compatibility with earlier
versions of VP-Info.

 SET MEMORY TO num const

 num const   the amount of memory reserved for high memory

     This command is ignored in Shark. In Shark, its role is taken by the
MEMORY= command in the SHARK.SET file.

SET NETWORK


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 RELATION


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.

 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.

 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.

 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.

Examples:

1>SOUND 3

A program to demonstrate all 13 effects:

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

SPOOL


Redirect printer output to disk file, or send disk file to printer.

 Four forms:
 1.  SPOOL 
 2.  SPOOL
 3.  SPOOL  TO  [PAGE num exp]
 4.  SPOOL/T


 Options:

 Form 1:      Create file  and direct print output to
              that file; default extension TXT
 Form 2:      Close any open spool file and stop redirection
 Form 3:      Do background printing of  on , usually PRN
              but can be any DOS device PAGE num exp start printing on
              page num exp
 Form 4:      Stop background printint started with Firm 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 four forms as follows:

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 both filename and device name,  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) prinnting starts with the top of that page
number.

4.   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 can spool to a different directory, but it cannot spool to a different drive.

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:

Give the commands:
1>number=21
1>name='David'
1>USE sales INDEX sales,part,date
1>STATUS

The 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 in letter quality mode on the Epson LQ-1500 printer:

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

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( for a better method of doing menus

WINDOW


Defines the active window, that part of the screen to which relative output
can be sent.

WINDOW
WINDOW ,]
WINDOW col1,col2 [COLOR ,] [BLANK/DOUBLE]

 col1    the coordinates of the top-left corner of the window
 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/.volume [OFF]

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

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.

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 WRITE's editing screen:  

                           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 a help screen

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

REPORT KEYWORDS


Keywords that take no arguments are described under REPORT command.

Others:

FIELDS Keyword
FILE Keyword
HEADING Keyword
INDEX Keyword
LENGTH Keyword
MESSAGE Keyword
PICTURE Keyword
RELATION Keyword
SELECT Keyword
SETUP Keyword
SPOOL Keyword
SUBTOTAL Keyword
TITLE Keyword

TITLE KEYWORD


TITLE - string/str exp

This keyword is followed by the title of the report; the title appears
centered as the third line of the report.  If no title is specified in the
text file, then the string in the system variable :TITLE (if any) is used
for the title.

If a str exp is used, it will be evaluated, and used as the title.
If an invalid expression is used, it will be printed as a literal.

Shark looks at the TITLE line; what appears to the right of the
hyphen is evaluated as an expression.  If it is valid, then it is used as
an expression.  If it is not, then it is printed "as is".

So to get Annual Report as the title, simply use the line

TITLE - Annual Report (No quotation marks are needed)

*The TITLE keyword may be used twice:

TITLE - string1
TITLE - string2
Then the title is in two lines, both centered.

If ASOF is a variable containing the date of the last
accounts-receivable aging in the standard format, then
TITLE - 'Accounts receivable as of '+DATE(FULL,asof) will display

Accounts receivable as of Thursday, September 19, 1998

FILE KEYWORD


FILE - data file [INDEX index file]

This keyword opens the data file (as file 1, if there was a file open
as file 1, it is first closed) and, optionally, the index file.

This keyword may occur a number of times.  The second time it opens
file 2, then file 3, and so on.  Since the reporting is done on the first
data file opened by FILE, more than one file should be opened only if
relations are used.

If there is no FILE line, REPORT uses the current data file.  If none
is open, an error message (usually: 2. Variable not found.) is given.

INDEX KEYWORD


INDEX - exp TO index file name [FOR cond]

This keyword will index the last data file opened with the FILE keyword
on the expression exp to the specified index file.  If this is only a
temporary index, then you should specify a name such as TEMP.  A condition
can be specified to limit the index to only those records matching the
condition; this is almost always faster than using SELECT or a FOR clause
on the REPORT command.  (Note: It is faster to index a file using the
INDEX ON command outside REPORT, whether a condition is specified or not.)

Example:
FILE - inventry
INDEX - inven:no TO temp1 FOR type='G'
FILE - supplier
INDEX - suppl:code TO temp2
opens up the data files: INVENTRY as file 1 and SUPPLIER as file 2, and indexes
both, limiting the primary index and the report to those for which type='G'.

FIELDS KEYWORD



FIELDS - exp1,exp2,...

This is the expression list; these expressions fill the columns of the
report.  Often, these expressions are just field names, though they may be
arbitrary expression including fields (from various data files), variables,
and constants.

If all the expressions do not fit on one line, then leave a comma at the
end of the line and continue on the next line.

HEADING KEYWORD


HEADING - string1,string2,...

These are the column headings for each expression in FIELDS line.
Separate the strings with commas.  The spacing of each column is done by the
program based on the largest of the following: the length of the heading, the
width of the field, and the picture clause in the PICTURE line.  Blanks on the
left and on the right of a heading are counted in the width.

To move a column to the right, put spaces in front of the column heading.
To make a column wider, put spaces at the end of the column heading.  To move
the column heading of a numeric field to the left, put spaces at the end of
the column heading.

If no heading is required for a column, it may be omitted, but its comma
is required if any later columns are to have a heading; no trailing commas are
permitted, since they would be understood as continuation characters merging
the next keyword to the HEADING line..

If the strings in the HEADING line do not fit on one line, then leave a
comma at the end of the line and continue on the next line.  Do not break a
heading with a comma.

Multi-line headings.  In the HEADING line, a semicolon (;) breaks the
heading into more than one line.  At most three lines are permitted.

For instance,
HEADING - Last Name;=========,First Name;==========,Department;==========,Salary;======
produces the headings:

Last Name       First Name Department         Salary
=========       ========== ==========         ======

Note the use of the comma (,) at the end of the first line as a
continuation character.

PICTURE KEYWORD


PICTURE - format list

The PICTURE keyword is used to indicate which expressions (in the FIELDS
line) are to be totaled.  The PICTURE line also shows how the expressions and
totals (and subtotals) are to be displayed.

A format is some 9s and, optionally, a decimal point or other special
characters used in the format clause for numbers (see the command @).

Examples:

999
999999.99
9.9999
999999.99-
999999.99>

A format list is a number of formats separated by commas.  Some formats
may be missing, but the commas have to be there as long as formats are required
to reach the last field requiring accumulation.  No trailing commas are
permitted, since they would be understood as continuation characters merging
the next keyword to the picture line.

Negative values can be displayed in any of three ways.  The default is to
use a leading minus sign.  It is possible to surround negative values with
pointed brackets, or to use trailing minus signs as follows:

     Indicator for Negatives    Example       Value        Displays
     None                       9999999.99    -19876.87     -19876.87
     Trailing minus sign        9999999.99-   -19876.87      19876.87-
     None                       9999999.99>   -19876.87     <19876.87>

If a format includes a comma, that format must be enclosed in quotes.

The following will all total the fourth and the fifth columns out of the
eight (or more) specified in the FIELDS line:

PICTURE - ,,,999.99,999999
PICTURE - ,,,999.99,'999,999'
PICTURE - ,,,999.99,'$$$,$$9.99'
PICTURE - ,,,999.99-,'999,999-'
PICTURE - ,,,999.99>,'$$$,$$9.99>'
     There can be no format for character fields in the PICTURE line, since no
strings are carried from record lines to total lines.  To format a character
field, use PIC( or other functions.

SUBTOTAL KEYWORD


SUBTOTAL - exp

This keyword causes subtotals to be printed when the expression exp
changes.  Subtotaling is done only for numeric expressions that are specified
in the PICTURE line.

Two levels of subtotaling - If there are two SUBTOTAL lines:

SUBTOTAL - exp1              "inside level"
MESSAGE - string1              message for the "inside level", footer
SUBTOTAL - exp2              "outside level"
MESSAGE - string2              message for the "outside level", header

two levels of subtotaling is done.  exp1 is the "inside" level (the sub-
subtotal) and exp2 is the "outside" level (the grand subtotal).

Subtotaling produces erratic result if the data file is not sorted or indexed 
in a way to group all the items with the same exp in one group.  The command 
REPORT works whether or not this is the case.

MESSAGE KEYWORD


MESSAGE - str exp

This keyword introduces the message to be displayed on the report lines
at the start of a subtotaled group; e.g., 'Salesman - '+salesm.

When two levels of subtotaling are specified, the message for the outside
level appears as a header; the message of the inside level appears with the
sub-subtotal.  String1 is printed from the start of the line.  Make sure that
there is enough room for string1 before the start of the first totaled column.

For instance, if the file is indexed on salesman+style, then salesman is
exp2, the outside level, and salesman+style is exp1, the inside level.  Thus
one obtains a sales report grouped by salesman (outside level), and within
salesman by style (inside level):

SUBTOTAL - salesman+style
MESSAGE - 'Style '+style
SUBTOTAL - salesman
MESSAGE - 'Salesman '+salesman

Note that the inside subtotal expression in on salesman+style instead of
by style alone; this is done because the last record for one salesman might be
the same as the first record for the next salesman, thus giving confusing
results.  Both subtotal expressions should be some leftmost part of the index
expression, with the inside expression longer than the outside expression.

RELATION KEYWORD


RELATION - str exp TO file number

This keyword sets a relation between file 1 and the file file number.
It is equivalent to the commands:

1>SELECT 1
1>SET RELATION ON str exp TO file number

Example:

RELATION - inven:no TO 2.

There can be a number of these lines.  File 1 can be in relations to
file 2, file 3, and so on.  The relations are always between file 1 and
another file.  To set up chaining relations (1 to 2 to 3, for example, set
up the files are relations in the program before executing REPORT.

SETUP KEYWORD


SETUP - setup string

SETUP establishes a string of control characters to be sent to the
printer when printing begins.  It should not be used if neither printing
nor spooling is in effect.

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.

Example:

SETUP - 27,W,1Bh,41h,3h

SPOOL KEYWORD


SPOOL - file name
This is an alternative to the PRINT keyword and SET PRINT ON, and should
not appear if either of the others is present.  It sends the report to the
file file name (default extension TXT).

Spool a report if you want to pretty it up with your word processor, or
include it in a document, or print it some other time.  The Shark
command SPOOL finename TO PRN or the operating system command PRINT can later
print the report in the background mode from this file.

Note that if file name already exists, the report will be added at its
end; it will not be overwritten.  (Do not confuse the SPOOL keyword with the
SPOOL command, which does overwrite existing files.)

SELECT KEYWORD


SELECT - cond

Select by condition cond; the same as a FOR clause in the REPORT
command.  If a FOR clause is used in the REPORT command, it overrides the
selection of the SELECT line.  If a FILTER is in effect, only records which
match both the filter and the select condition are included in the report.
Caution:  Do not use SELECT or SET FILTER when running a report with a
SUBTOTAL; create a special index with the required records instead.

Note that NODETAIL can be used only when SUBTOTAL is also used.
NODETAIL modifies a report with subtotaling: only the totals and subtotals
are shown.  The expressions from the FIELDS line and the column headings
from the HEADING line are not displayed.

LENGTH KEYWORD


              LENGTH - num exp
     This sets the number of printed lines per page.  For instance,
LENGTH - 40
will set the page length at 40.

MEMO FIELDS


Memo fields may be specified in the structure of any data file of any
type.  This may be done in either CREATE or MODIFY.  The field width is
automatically 10 characters, but what you see when the field is displayed or
edited is either "memo" if the memo has been attached to the record, or
"MEMO" if a memo is present.

All memos associated with a data file are stored in a file of the same
name, but with a DBT extension (standing for data base text).

Since memo fields were originated in dBASE III, many database programs
still use its standard format, which is not compatible with dBASE IV.  Shark
handles either format when a DBT file is created externally, but all DBT
files created by Shark itself use the same format as dBASE IV version 1.1.
This format has the advantage of reusing space that becomes available inside
the DBT file, in much the same way as Shark's libraries have always done;
the original dBase memo files grew endlessly.

1. Writing & Editing Memos.
Memos may be written and edited in two ways:

WITH THE WRITE COMMAND:

Whenever a data file with one or more memo fields is open, you may
create or edit a memo attached to any memo field in the current record by
entering WRITE with the name of the field, preceded with the letter M and a
period.  For example, WRITE M.COMMENT will open the memo associated with the
field COMMENT and allow you to edit it.  If it does not already exist, it
will be created.

INSIDE FULL-SCREEN EDITING

You are in full-screen editing whenever you are executing READ, EDIT,
BROWSE or APPEND commands.  If a memo field is on the screen, you may move
your cursor to the memo field and press Alt-W to enter WRITE in read/write
mode, or Alt-R to enter WRITE in read-only mode (no changes are saved).
Again, if no memo already exists, it will be created.

Memos may be copied to or from DOS files and library entries inside
WRITE.  For example, to write M.COMMENT out to disk, merely change its name
before storing it for a valid DOS name, such as COMMENT.DAT.

2. Displaying Memos.

Memos are displayed with the TEXT command.  Just as you can display a
DOS file or library entry by naming it after the TEXT command

Examples:

TEXT comment.dat or TEXT .123), you may name a memo field using the same
"M." convention used by WRITE (example: TEXT m.comment).

TEXT's margins and width are controlled by the SET MARGIN and SET WIDTH
commands.  When writing to the screen, positioning may also be controlled by
setting a WINDOW, with or without a border.

Be aware when printing to the screen that TEXT stops the display when
it reaches the last line of the window, or of the current screen if no
window is in effect.  It waits for a keystroke before proceeding, but no
prompt is displayed.  Pressing  is not recommended.

Example programs:

1. Using a DO WHILE loop to control movement between records, memo
fields are successively displayed:

USE memodemo                   ;a data file with memo fields
WINDOW                         ;these two lines initialize the screen
CLS
DO WHILE t                     ;do endlessly, or until  is pressed
   WINDOW 1,2,9,77             ;single-line window in top half of screen
   TEXT
   NOTE_NUM #NOTE_NUM
   NOTE_NOTE #NOTE_NOTE
   press a key:
     - (minus) for previous memo
      to exit
     any other key for next memo
   ENDTEXT
   WINDOW 12,2,23,77           ;window over botton half to display text
   TEXT m.note
   dummy=inkey()               ;wait for a keystroke
   IF dummy=asc('-')           ;compare to minus sign...if it is, skip back
      IF #>1                   ;skip -1 only if we're past top of file
         SKIP -1
      ENDIF
   ELSE
      SKIP                     ;otherwise, skip forward
   ENDIF
ENDDO

2. Use EDIT OFF with an ON FIELD structure to control display of
memo fields and allow memos to be created and edited.
USE memodemo                    ;same file as in previous example
SET text on                     ;we want non-editable display to update
recnum=#                        ;variable to show record number
WINDOW                          ;initialize screen
CLS
WINDOW 2,2,9,77                 ;window for top half of screen
TEXT
.. recnum,9999
                                            Record #recnum

         NOTE_NUM.... @NOTE_NUM
    Use the standard EDIT keys, including PgUp and PgDn between records.
    To edit MEMO, place cursor in this field and press Alt-W: @note

         NOTE_NOTE... @NOTE_NOTE
ENDTEXT
SCREEN 1,2                      ;save screen as it is to screen 2
ON FIELD                        ;set up ON FIELD
FIELD 0                         ;on entry to record...
   recnum=#                     ;get current record number
   SCREEN 2,1                   ;restore original screen and window
   WINDOW 12,2,23,77            ;new screen to put TEXT into
   TEXT m.note
FIELD note                      ;when leaving memo field
   WINDOW 12,2,23,77            ;display memo again to ensure changes shown
   TEXT m.note
ENDON
EDIT off                        ;edit the records
WINDOW                          ;cancel the window
CLS                             ;erase the screen

Configuration


The Shark environment is managed by two configuration files:

SHARK.SET or SHARKNET.SET
SHARK.CNF or SHARKNET.CNF

SHARK.SET file:

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

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  is 32.  Example: BINSPACE=32 allocates 32K.

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.

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.  The limits for FIELDS= are 128 and 1000, with a default 
of 320 files. See FIELDS=.

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.

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  files. The
PC=MOS operating system manages files internally and no FILES statement is required.

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.

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.

NOEFFECTS
    
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.  NOEFFECTS must be used in network installations to avoid 
unwanted effects appearing on remote workstations.

Example of contents of SHARK.SET file:

BINSPACE=32
NOEFFECTS
FIELDS=480


SHARKNET.CNF file:
NOTE: The files extgension "cnf" is a Windows config file extension and most Windows editors
will not see or open a file with this extrension.  The file may appear in the file listing
NOT as "SHARKNET.CNF" BUT SIMPLY AS "SHARKNET". You may have to use a programmer's editor to
access this file.

Example:

SET NETWORK ON                      turns NETBIOS instructions on
SET APRICOT OFF                     undocumented instruction to permit escaping to Shark prompt
                                    if APRICOT is set ON, Shark escapes to DOS prompt only   
SET DATE TO 'YYYYMMDD'              sets global calendar date format
CLS                                 clears screen on sign-on
:USER=99                            User number identifies each local workstation
:color=31                           default color = blue with white text
:RETRY=15000                        on file lock, default setting tries to open file for 15000 times until
                                    admitting defeat with an error message
:UNDOC=PIC(DATE(8),"XXXX.XX.XX")    store today's global formatted calender date in this location
:TITLE='DEBUG=Y'                    store global debug flag in this location

FILES                               Sets the location of working files for this workstation; note DBF files are in
                                    a common parallel shared folder while LOC,MEM,GET,SCR,STO files are 
                                    local to each workstation. Shark won't direct working files like LOC,MEM,GET 
                                    to a shared parallel folder, but will send working files to a local sub-folder 
                                    as shown (be sure to set up the sub-folders beforehand).

*.TXT,C:\SHARK\TXT (local sub-folder)
*.LOC,C:\SHARK\LOC (local sub-folder)
*.MEM,C:\SHARK\MEM (local sub-folder)
*.FRM,C:\SHARK\FRM (local sub-folder)
*.GET,C:\SHARK\GET (local sub-folder)
*.SCR,C:\SHARK\SCR (local sub-folder)
*.STO,C:\SHARK\STO (local sub-folder)
*.PRG,C:\PRG (shared parallel folder)
*.DTA,C:\DTA (shared parallel folder)
*.MNU,C:\CPL (shared parallel folder)
*.CPL,C:\CPL (shared parallel folder)
*.DBF,C:\DBF (shared parallel folder)
*.NDX,C:\NDX (shared parallel folder)
ENDFILES
SET EXECUTE OFF                     ON FIELD is not executed at one time; it's executed line by line
set end off
:F1=" "                             Contents of function keys f1 - f10 are set here
:F2=" "
:F3=" "
:F4=" "
:F5=" "
:F6=" "
:F7=" "
:F8=" "
:F9=" "
:F10=" "

Some CNF locations can store quite a bit of global information.  Subsets can be accessed using 
the $( substring function.  The size limits of each global variable have not been measured yet, but it's
likely to be 256 bytes.

Example:


? :UNDOC
1998.03.27
? $(:UNDOC,1 4)
1998   

Error Messages


1. Invalid variable type found when executing an expression.
2. Variable not found.
3. Illegal expression.
4. Missing the second operand in an expression.
5. File not found.
6. Index file not found.
7. Record specified is out of range.
8. Error in reading file.
9. Index file is not functioning.
10. Missing 'TO' in command.
11. 128 memory variables have been used.
12. Missing or mismatched string delimiter.
13. No space is left in a control stack.
14. No valid command was found.
15. Invalid nesting of DO WHILE or IF statements.
16. File pointers must be between 1 and 10.
17. Strings cannot be larger than 256 characters.
18. Missing parenthesis ')' or '(' in expression.
19. Invalid CASE construction. (Problem may be in PROCEDURE or DO module.)
20. Must be numeric argument.
21. Invalid variable or constant.
22. Program not found or too many files open.
23. Program is too large for memory.
24. Invalid nesting of DO or RETURN statements. (Problem may be in DO module.)
25. The PROCEDURE must be defined in this module if it is to be PERFORMed.
26. Disk full or error in writing data to disk.
27. File must be indexed for this command.
28. Missing WITH in REPLACE command.
29. Only 10 expressions can be used in the SUM command.
30. Missing FOR clause of LOCATE or CONTINUE command.
31. Insufficient space to do the sort.
32. Improper syntax for dimension variables.
33. Internal macro space has been exceeded.
34. Not enough memory for a buffer to be made.
35. No more than 32 external memory variables are allowed.
36. This program must be re-compiled.
37. This program exceeds the available program memory.
38. A data file must be in USE for this command.
39. Missing 'ON' in this command.
40. CREATE must be followed by a file name.
41. Two coordinates must be specified.
42. Screen coordinates are out of range.
43. This command is not authorized for use by end users.
44. This matrix variable is already defined.
45. Not enough memory for this matrix to be defined.
46. Index is outside the range of a buffer or matrix.
47. Sequential file numbers must be between 1 and 4.
48. The index expression cannot exceed 60 characters.
49. Date format cannot exceed 8 characters in length.
50. Indexes for file vectors must be 1 to number of fields in file.
51. Illegal use of macro.
52. Maximum number of fields must in range 128 to 1000.
53. The index file switched to is not open.
54. Screens can be defined from 1-4.
55. Invalid window coordinates.
56. Screen library is not open.
57. Missing = sign.
58. Bit position parameter is out of range.
59. Invalid field or :field reference %s in ON FIELD; check TEXT.
60. Command not found or not enough space to execute. (See: MEMORY=)
61. Network must use DOS 3.1 or greater.
62. Read-only files cannot be changed.
63. %s file locked.
64. Record locked in file %s.
65. Index error. Reduce the key size to index this file.
66. Format lines in a TEXT command exceeded 64 (clear with CLEAR GETS).
67. Only 30 fields can be used in the REPORT command.
68. Invalid file operation due to sharing violation.
69. Memory variable space exceeds limit.
70. Expression is too complex; requires too many temporary variables.
71. Invalid nesting; ENDDO implies a DO WHILE.
72. Invalid nesting; ENDCASE implies a DO CASE.
73. Invalid nesting; ENDIF implies an IF.
74. Invalid nesting; ENDPROC implies a PROCEDURE.
75. Invalid nesting; ENDREPEAT implies a REPEAT.
76. Invalid nesting; ENDON implies a ON ESCAPE, ON ERROR, or ON FIELD.
77. Expecting ENDTEXT command.
78. Expecting ENDFILE command.
79. CASE or OTHERWISE encountered with no corresponding DO CASE command.
80. ELSE command encountered with no corresponding IF command.
81. FIELD command encountered with no corresponding ON FIELD command.
82. LOOP or BREAK encountered with no DO WHILE or REPEAT command.
83. Not enough memory for REPORT (try calling from a DO module).
84. Unable to create or rename a file.
85. Compiled expression too long to save. Simplify.
86. Missing file name in command
87. Division by zero. Permitted only if SET DIVZERO ON (default).
88. Index reference by number must be in range 1 to number of active indexes.
89. Minimum window is 50 characters wide and 5 lines deep for EDIT or APPEND.
90. Too many fields requested. Exit SharkBase, increase FIELDS= in .SET file.
91. Function number invalid (file sharing loaded).
92. File not found.
93. Path not found (of file does not exist).
94. No file handle available; check "FILES=n" in CONFIG.SYS and .SET.
95. Access denied.
96. DO nesting level exceeds limit.
97. SharkBase workspace full. (Try breaking program into modules.)
98. Keyword following ON not recognized.
99. SYSTEM ERROR, file access code invalid.
100. SET BIN request cannot be greater than 64K.
101. Unable to satisfy SET BIN request.
102. LOAD failed!  Unable to open BIN file.
103. Cannot LOAD BIN blocks larger than 32K.
104. BIN high memory cannot satisfy LOAD request.
105. A maximum of eight BIN files can be LOADED at once.
106. SET BIN must be run before using LOAD or CALL commands.
107. CALL failed! Memory variable not recognized.
108. CALL failed! Command not recognized.
109. Drive not ready.
110. Attempt to write on protected diskette.
111. FAT error - disk may not be formatted.
112. DOS reports critical error number %d. 
113. To ZAP, PACK, or REINDEX on a network files must be opened LOCK.
114. Current record not found in master index.

System Variables (Global Variables)



:F1=" "
:F2=" "
:F3=" "
:F4=" "
:F5=" "
:F6=" "
:F7=" "
:F8=" "
:F9=" "
:F10=" "
:USER=99
:COLOR=31
:RETRY=15000
:DATE=DATE(8)
:UNDOC=PIC(DATE(8),"XXXX.XX.XX")
:TITLE='DEBUG=N'
:TIME="22:53:43"                           
:DATE=DATE(8)
:VERSION="710 "                               
:SERIAL="710020194A"                         
:COMPANY="ABC Inc                           " 
:PICTURE="9999999.99"                         
:TITLE=" "                                                         
:KEY="0"                                  
:AVAIL="0"                                  
:FIELD="0"                                  
:ERROR="0"                                  
:MESSAGE="2. Variable not found."                                                                      
:DIR="C:\"                                
:NEAR="0"                                  
:ROLL="ROLL.$$R"                           


See also the command LIST SYSTEM

These system variables are built into Shark. They include the contents of
the function keys (F1 - F10), the date and time (from DOS), various default
values, and other information.

A system variable is distinguished from other variables by having a
colon as the first character of its name -- e.g., :TIME.

To see the contents of a particular system variable, give the ? command
followed by the system variable name.  To see all system variables, type

LIST SYSTEM.

Like memory variables, the values of most system variables, including the
function keys, are changeable using the = (equal sign) or STORE...TO commands.

Each of the function keys contains a pre-defined string (shown with LIST
SYSTEM).  Using the = command, you can redefine any function key (e.g.,
:F2="SET DEFAULT TO b:" assigns the string "SET DEFAULT TO b:" to F2).
Function keys can be defined as commands or as frequently repeated entries
for use in full-screen editing.

A semicolon (;) in a function key definition indicates a press of the
ENTER key. A function key definition that contains a semicolon will be
executed when you press the function key.

A quick way to redefine function keys is to type the string to be stored,
then press ALT key along with the function key to store the string to that key.  To
capture a line of text to move in WRITE, place the cursor at the beginning
of the line, then press ALT and the function key to store the text; then
move to the new position and press the function key to insert it.

These processes redefine function keys only during the current
Shark session.

To save changes to function keys  or other system variables enter the new
definitions in the CNF configuration file.

In addition to the function keys, there are a number of other system
variables which can be viewed by typing LIST SYSTEM:

:AVAIL contains the number of the next available volume in the current library
     file.  See SET LIBRARY command.

:COLOR The current value of the color attribute written into the screen memory
     for every byte of screen display; set with SET COLOR TO or :COLOR=
     command.

:COMPANY contains the company name.  This is used by the REPORT command.  (It
     can be changed to the name of the company you are reporting on.)

:DATE. Contains a string of the date as formatted the last time the DATE()
     function was used.  DATE(Full) is used with the system date when
     Shark is started up.

:DIR. The user's current drive letter and directory.

:ERROR. The current value of Shark's internal error variable. Shows
     why execution of the last command failed.

:FIELD contains the number of the Get Table entry currently being processed.
     See ON FIELD command.

:KEY is a numeric variable.  It contains the number generated by the last
     keystroke used to exit a process or execute a command.  See the function
     INKEY( for the definition of this number.  :KEY is used in Shark
     programming to find out which key was pressed to abort or interrupt a
     procedure.

:MESSAGE. The message from the MSG file associated with the error number
     contained in :ERROR

:NEAR The number of the record containing a key equal to or greater than the
     last FIND's FIND string.  See FIND command.

:PICTURE. The :PICTURE system variable is a format for numbers (see Formatting
     numbers under the @ command).  This formats the display of all numeric
     memory variables and numeric expressions.  This format can be overridden
     by a format clause in TEXT or an @ command, or with the PIC( function.

:RETRY. Controls what happens during network operations under Shark
     Network Edition; has no meaning under other versions.

:SERIAL may contain the serial number.  Once Shark is loaded, you may
     use this as a variable that survives a CLEAR command.

:TIME. Contains a string of the time of the last use of the TIME() function
     in the format last used by that function.  TIME(1) is used with the
     system time when Shark is started up.  When :TIME is set with STORE
     or = commands, the system time is set to the same time.

:TITLE is the default title of a report.  See the REPORT command.

:UNDOC - Contains data used internally by Shark; not to be changed by user.

:USER. A number between 1 and 999 assigned to each user on a network under
     Shark Network Edition.

:VERSION contains the current version number of Shark.