Shark is designed to run in stand-alone or network mode on any Windows system after Windows 3.x. The Windows NT architecture influences everything from its API to its performance. In the late 1980s, Microsoft charged NT's developers with creating a new operating system, and the company mandated a hefty list of requirements to make NT the world's dominant desktop and enterprise-level operating system. NT's developers faced the constraints of supporting backward compatibility with DOS and Windows 3.x, as well as supporting a laundry list of capabilities intended to ensure NT's long-term success. What NT's developers produced was an operating system that made use of 1990s cutting-edge technologies but had roots in earlier operating systems. NT met Microsoft's broad requirement list, and that fact positioned NT to become widely adopted, no matter which of the popular operating system API sets, processor types, or network interfaces won market dominance.

Networking with Windows Emulators:

Modern emulators such as vDos and DOSBox-X, and even PC-MOS/386, have built-in all the necessary elements of these earlier networking systems in order to facilitate trouble-free multi-user networking setups using later languages such as SharkBase. This section covers a variety of aspects of network programming, including recommendations on strategies. Implementing a network system is far from a trivial task and, although there is often a variety of ways to accomplish your task, clear thinking and a thorough understanding of this section will help you implement the optimal system. SharkBase has been installed in mission-critical industrial, scientific, engineering, commercial and medical systems, with up to 100 users due to careful system design and implementation. Whether running as a stand-alone, single-user setup or a multi-user setup, the language is the same. The only difference is in opening and closing datafiles and indexes, which is explained here.

1.1. PREPARATION

The use of a network compatible with DOS 3.1 and above is required. This is enabled by using one of the modern Windows emulators, all of which are a simple download & setup. SHARE or a similar network utility must be run (on vDos or DOSbox-X, for example) before loading SharkBase Network Edition. Learning networking is assisted by the ability of these emulators to setup a simple virtual network on a single PC. Each node is a separate Windows folder running SharkBase as a separate work-station. Each setup can be easily identified by displaying the :USER number at the top of each display. You can also use a different default background color to eliminate confusion!

Each node on the system should have a SHARKN.CNF textfile containing the following two lines in order to tell Shark that there's more than one system reading and writing data files. This simple textfile in the SharkBase directory will get you started:

SET NETWORK ON   ;or SET NETWORK TO 1 
:USER=n          ; in which n is a number unique to the local computer

1.2. SPECIFYING FILE ACCESS

During network operations (that is, when Shark is run with "SET NETWORK ON" as explained above), all files are opened with one of four modes in which access is set as follows for the user (the person executing the USE or other open command) and any other person on the network:

The WRITE keyword is the usual mode in which files should be opened if changes are to be made to records. When no changes have to be made, use the READ access mode. The syntax is as follows:

USE customer WRITE
or
USE customer INDEX custnum,custname READ

The LOCK access mode should only (and always) be used when the contents of the file or indexes are to be destroyed: PACK. ZIP, INDEX, REINDEX, etc.

With WRITE, any user can safely have full access to any file on the network withdut interrupting the ability of other users to reference data in those files. If SHARE is not used on the network, there is no need to lock either data files or index files at any time.

The SHARE keyword provides the ability to have two or more users write to the same files at the same time. This may be necessary in some cases, but should be avoided if possible. Extra program overhead to ensure the integrity of files (especially index files) slows performance compared to other options.

If indexed data files must be SHARED, try to avoid appending any records or changing the contents on any field that is part of the index key.

EXAMPLE:

Suppose a number of operators are using computers connected to a network and selling concert tickets. The available seats would be added to the file while locked, and the index would be created on the date, section, row and seat. Then each operator would select the seats to be sold, lock their records with the LOCK command, change their status to reserved or sold, and then unlock them again.

If contents of the key field must be changed, or records appended, use LOCK INDEX to protect the integrity of the index.

A better way of programming this kind of application is to USE a temporary file for each user with the LOCK keyword. There are several ways in which users could update the primary data files:

A. Periodically or at the end of each day, each user would open (in WRITE mode) the main data file with all its indexes, APPEND from the temporary file, close the main data file, reopen the temporary file, ZAP its records, and continue data entry or any other task.

B. Open the primary data file in SHARE mode. When a record is found that is to be changed, it is either LOCKed or has a specific field marked in some way to indicate to other users that the record is in use. We recommend the second option, since it eliminates the possibility of other users encountering difficulties reading, reporting or scanning records because of a DOS-implemented lock.

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:

USE customer INDEX custnum,custname SHARE 
USE#2 personal LOCK          ;FILES...ENDFILES gives each user separate file 
SET FUNCTION OFF 
DO WHILE t                   ;infinite loop 
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 
DO CASE 
CASE :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 
CASE :key=335                ;<end> means get out of infinite loop 
BREAK 
ENDCASE 
ENDDO 

Most data files used in business applications are only needed for reference and may be opened with READ most of the time. For example, an order-entry application may require READ access to the CUSTOMER, INVEN, and PRICES data files, but updating their records can be left in most cases to a nightly posting run when either the network is inactive or all files may be locked.

1.3. :USER AND :RETRY.

SharkBase Network Edition provides two system variables of particular application to network operations.

:USER is a special number that should be set in the CNF file to ensure that every user has a separate number between 1 and 999. This number is used a number of way by SharkBase in implementing locks and creating unique, non-conflicting file names for temporary files used in the indexing process.

There are three separate strategies for assigning user numbers to individual users:

A. On a network, each user enters SharkBase from a separate computer, and therefore has a separate "home" directory. Insert the command USER=n, where n is a unique number from 2 to 999, into the CNF file on each computer. (Since the default user number is 1, we recommend you use numbers of 2 and up; this allows the program to check that a valid user number has been set deliberately.)

B. On multi-user and multi-tasking systems have all users working from the same computer, but again, it is usually possible to ensure that every user starts from a separate directory with a separate CNF file.

C. On either type of system, it is possible to have every user enter SharkBase from the same subdirectory. A simple CNF file might be:

CLS 
ACCEPT 'Enter your name code... to name 
name=l(name) ;capitalize input to make comparisons easier 
DO CASE 
CASE name='JOE' :USER=1 
CASE name='MIKE' :USER=2 
CASE name='ALICIA' :USER=3 
CASE name='SAM' :USER=4 
CASE name='ALFIE' :USER=5 
OTHERWISE 
QUIT ;if not one of authorized users, get out 
ENDCASE 

:RETRY is referenced by the system to determine how many time to try to open a locked file before giving up and reporting a file-locked error. :RETRY may be set in the range of 1 to 65,000, but the way it is implemented depends on whether or not it is set at more than 10,000. When set at or under 10,000 and a lock condition is encountered, the program puts the message "RECORD LOCKED" on the top line of the screen and keeps trying until that number is reached. If the lock is not removed by another user within that time, SharkBase drops out of the program with an error message, unless an ON ERROR structure provides an alternate procedure. When set at more than 10,000, SharkBase automatically reduces the number of retries by 10,000 and attempts the operation for that reduced number of times. The difference is in what happens when the number of retries is exhausted: instead of falling out with an error message, SharkBase puts the message "PRESS A KEY" on the top line of the screen and waits for any key to be pressed. If the user presses the spacebar, the retry procedure is tried again; otherwise, program execution ends with an error message, unless an ON ERROR structure provides an alternate procedure. (Note that the command SET ERROR OFF can be used to disable an ON ERROR structure temporarily. When SET ERROR OFF, the program reacts as though no ON ERROR exists.)

1.4. NOTES:

A. Never LOCK a record or an index in SHARE mode unless absolutely necessary, and then only for the moment actually required to update the file.

B. Do not FLUSH a file in SHARE mode. The command UNLOCK automatically flushes the file, so FLUSH is both redundant and wasteful.

C. When running an automatic process such as the REPORT command that can encounter a locked record for a moment, set :RETRY to 65000 or another large number to avoid having to respond to a RECORD LOCKED error message. While the user is actually at the keyboard, :RETRY should be set relatively low; experiment with times on your own network. Remember that 11,000 is the same as 1,000 except that it allows the user to try again by pressing the spacebar instead of falling out of the program with an error message.

D. Avoid commands like ZAP, PACK, MODIFY, INDEX, REINDEX, REPLACE ALL and other commands with global scope that change data files or their indexes unless all such files are locked.

E. Make appropriate use of :RETRY, ON ESCAPE, ON ERROR, and SET ERROR commands to handle RECORD LOCKED and FILE LOCKED errors.

F. The default access mode for all data and index files is LOCK, unless the default is set to another mode in a FILES ... ENDFILES structure.

G. All files are created in locked mode, including those created by WRITE, CREATE, MODIFY, COPY, TOTAL, SORT, INDEX, etc.

H. Some networks allow a user the option of loading the network software or not, as they prefer. When the network is not loaded, SHARE or its equivalent may not be loaded, or may only be partially loaded. Users must be aware that SET NETWORK ON should be executed only when the network is fully installed. In addition, some networks do not allow the user to operate safely with SET NETWORK OFF, even when no other user is on the network. The best approach is to experiment; if you get unsatisfactory results one way, try another.

I. Certain networks are prone to leave file locked when the user accessing it turns off or reboots the computer. If the network does not have a command to unlock the file at the DOS level, you may have to power down the server on which the file is stored to free the file. All users should be warned not to turn off or reboot any network station while not at the DOS prompt.