Shark Networking:
One of the most attractive features of SharkBase is that networking functions are built in. There is nothing extra to supply to a user, and there are no royalty or license fees to pay with each copy that is distributed. You create the application, you own it, and you give it to the users that you want to have it.
With the proper network configuration and a SharkBase application written with multiuser situations and network security in mind, operators can perform day-to-day tasks with the application without giving much thought to the fact that they are sharing resources with other users. A program designed for data entry can be running simultaneously many times on the network so that several operators can be using the same application to enter records into the same database at the same time. All of the file and record handling done in a SharkBase application strictly adheres to standards introduced with MS-DOS. SharkBase does not make any nonstandard hardware calls. All of SharkBase’s file and record locking activities are done with calls to Windows. Any network that is compatible with MS-DOS V3.1/NT file and record locking calls - and most are - provides the proper environment for running your SharkBase applications. To maintain full compatibility with SharkBase, all of your work stations must be running under vDOS on Windows, which ensures that your network is running under the original MS-DOS V3.1/NT specification.
Essentially record-locking is not done by vDOS itself, but by the OS managing the drive on which the files are stored, in this case, Windows. That OS is the ONLY ONE that can keep track of what file regions are effectively locked. It is not something that is recorded on the disk itself. The role of vDOS in record-locking is rather modest: It will check that record-locking is indeed supported for a DOS/vDOS drive letter, take care of timeouts, but mainly pass on the record-locking request to Windows. That will then forward the request to the OS managing the drive. As said in the FAQs, record-locking as used by (the database engine of) a DOS program is more complex. For instance the program will not lock the actual record since that would of course put all other instances of that program in need of the same record on hold. Simple gaming emulators such as DOSBox create problems for business users because they cache logical pages of database files in local buffers at the workstations where they are vulnerable to being accidentally over-written.
Shark is designed to run in stand-alone or network mode on any Windows system after Windows 3. 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.
Record Locking under vDOS:
File locking is not done by vDOS itself, but by the operating system managing the drive on which the files are stored (usually Windows). That OS is the ONLY ONE that can keep track of what file regions are effectively locked. It is not something that is recorded on the disk itself. The role of vDOS in managing record locks is rather modest: It will check that locking is indeed supported for a DOS/vDOS drive letter, take care of timeouts, but mainly pass on the record lock request to Windows. That will then forward the request to the OS managing the drive (Windows or Linux, for example). Record Locking as used by SharkBase is more complex. For instance, Shark does not lock the actual record since that would put all other instances of that program in need of the same record on hold. Older emulators (such as DOSbox) have a problem in that logical pages of database files are cached in local buffers at the workstations, making the cached files vulnerable to something going wrong. This is OK for multi-player games, but not for business applications. Without modern locking where the O/S (vDOS on Windows) and the application (SharkBase) are working together, index pages are especially vulnerable due to their complex structure/logic and compactness.
1.1. PREPARATION (Windows Network)
Any recent Windows (10/11) system will do! To start the networking exercise, our objective will be to set up two separate Windows stations (nodes), each running an instance of SharkBase on vDOS, and able to communicate with each other with Windows Networking. Learning networking is assisted by the ability of these emulators to communicate with each other and relay simple network messages and commands back and forth to each other. 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!
Mapping one Windows computer to another
"Mapping one Windows computer to another" means creating a network connection where you can access files and folders on one computer directly from the other, essentially treating a shared folder on the remote computer as a "mapped drive" on your local machine, allowing you to browse and manage files as if they were on your own hard drive; this is typically done by using the "Map Network Drive" feature in Windows File Explorer:
Map the Drive:
In Windows: 1. Open File Explorer on your local computer. 2. Go to "This PC" and select "Map network drive". or: In vDOS: 1. Start vDOS on a local computer to be used as a Shark work-station; 2. You should see "C:\>" 3. Then enter USE <vDOS drive letter:> <Windows path>, for example, at the C:\> prompt, type "USE D: D:" 4. You should see: "C:\> USE D: D:"; press <Enter> 5. Then type D:, you should see "D:=> \\DESKTOP - IIIWXYZ\Shark\" 6. In the "Drive" field, choose an available drive letter, or the name of the host computer 7. In the "Folder" field, type the network path to the shared folder (e.g., \\computername\sharename). 8. Check "Reconnect at sign-in" if you want the mapped drive to automatically connect when you log in. 9. Click "Finish".
Each Windows node on the system should have a SHARKNET.CNF textfile containing the following two lines in order to tell Shark that there's more than one system reading and writing data files:
SET NETWORK ON ;or SET NETWORK TO 1 :USER=x ; this can be any number, but each node's USER # should be unique
Thus, each instance of Shark will have its own SHARKNET.CNF file in its own directory. This simple textfile, SHARKNET.CNF, in each SharkBase directory will get you started:
The main computer with all the data files will have these two lines in its respective SHARKNET.CNF file:
SET NETWORK ON ;or SET NETWORK TO 1
:USER=2 ; this can be any number, but each node's USER # should be unique. The default number
is "1", so it's better to use "2" to make it obvious what is being done (i.e. that it's
not an accidental node)
The REMOTE computer wishing to access the data files will have these two lines in its own SHARKNET.CNF file:
SET NETWORK ON ;or SET NETWORK TO 1 :USER=3 ; this can be any number, but each node's USER # should be unique
The remainder of the CNF files, file folders, calendar dates, etc, can be the same on both computers. The networked computers can be connected or disconnected at any time simply by editing the respective SHARKNET.CNF files.
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 without 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.
EXAMPLES:
Only ONE user on the network:
It's possible to have a network on which only ONE user is accessing files. There may be two work-stations accessing data on one of the work-stations, but only one person who moves back and forth from one to the other. In this case, there is no worry about another user accessing your file and over-writing your file. This is the very minimalist setup, and in this case there is no need to manage access to your files.
MORE THAN ONE user on the network:
In this example we'll look at the other extreme: a SharkBase network with any number greater than one user. SharkBase can theoretically host up to 999 users, but there is no difference beteen 2 users and 999 users. Only one user at a time can write data to the main data file. Writing the data may take only a millionth of a second, but the file must be LOCKed while this happens.
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. Locking and unlocking happens so fast that the other work-stations don't even notice!
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 ;function keys are not needed * DO WHILE t ;start infinite do 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 wait=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 ;end infinite do loop
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 those 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 in 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 only used in a program (prg) file. It is referenced by the system as the program runs to determine how many times 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. The basic :RETRY syntax is as follows:
USE#1 ORDERS WRIT BREAK :RETRY=15000
When :RETRY is 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. Some networks are prone to leave a locked file in a locked condition 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.