Category : Databases and related files
Archive   : BCHWTCH.ZIP
Filename : BTRWATCH.DOC

 
Output of file : BTRWATCH.DOC contained in archive : BCHWTCH.ZIP


BTR WATCH

A memory resident Btrieve Debugger

Version 1.0



By David Smith
(c) 1991 Informative Technologies
1718 M Street NW, Suite 292
Washington, D.C. 20036
Voice (202) 675-4528
FAX (202) 675-4529
CompuServe 71311,2334


What is Btr Watch?

Btrieve is Novell's record-manager system designed to aid PC
programmers in the development of applications. Btrieve handles
all of the tasks associated with managing indexed records. Btrieve
is loaded as a TSR and applications make calls to Btrieve to access
indexed files.
Btr Watch is a memory resident Btrieve debugger. Btr Watch can
trace all Btrieve file accesses and log them to an ASCII file.
Btr Watch is loaded after Btrieve, but before the Btrieve application
program. Btr Watch can be used with any DOS application that uses
Btrieve.
Btr Watch is a set of two programs. The first program is a TSR
that loads into memory between Btrieve and the application program.
This program is BTRWATCH.EXE. This program intercepts Btrieve calls
and logs them to a file. The second part of Btr Watch is a program to
view the log file and to set the options of Btr Watch. This program
is not a TSR and is called WATCHBTR.EXE.

Some of the features and uses of Btr Watch:

o Btr Watch helps in debugging applications. Load Btr Watch
to make sure the correct sequence of Btrieve calls occur.
Test applications by tracing Btrieve file operations.

o Btr Watch can log all Btrieve file accesses or just when
certain status codes occur.

o Btr Watch can show all of the Btrieve file operations
that affect a file. Btr Watch can be loaded at all
times and will only log file operations when certain
status codes occur. Btr Watch stores in memory a list
of the last 100 file operations. When a designated
status code occurs, Btr Watch will log up to 100
Btrieve operations that happened just before the
designated status code.

o Btr Watch works independently of the application.

o Btr Watch works with BTRIEVE.EXE or BREQUEST.EXE and
is network compatible. Btr Watch can trace file
accesses from multiple stations.

o Btr Watch catches files that have been opened multiple
times without closing them or attempts to access files
that are not open.

o If one of 10 different status codes occur, Btr Watch
can automatically retry an operation. The number of
retries and the delays between them is configurable.

o Btr Watch can log how long each Btrieve access takes.

o Btr Watch logs the date and time a Btrieve operation
occurs. This lets you know exactly when file
operations occur.

o Btr Watch can make a beep signal whenever a 'BAD' status
code occurs so an operator can be alerted to take action
immediately.

QUICK START

Here's how to use Btr Watch:

Load Btrieve before Btr Watch is loaded. An example batch file is
provided that loads Btrieve 5.X and Btr Watch in the correct order.
This file is call "WATCH.BAT". If you will be using BREQUEST.EXE
with Btr Watch, see the section on setting the 'file handle offset'
before you load BTRWATCH.EXE.
A log file will be created in the same directory as WATCHBTR.EXE.
Also, Btr Watch will create a configuration file called BTRWATCH.CFG
in the same directory as WATCHBTR.EXE when WATCHBTR.EXE is run for
the first time. All program settings are stored in this file.

----------------------------------------------
Example: To load Btrieve 5.X and Btr Watch.

BTRIEVE/M:64/P:4096/T:BTRIEVE.TRN
BTRWATCH
----------------------------------------------

OR

----------------------------------------------
Example: To load Btrieve 4.X and Btr Watch.

BTRIEVE/P:4096/T:BTRIEVE.TRN
BTRWATCH
----------------------------------------------

OR

----------------------------------------------
Example: To load Brequest and Btr Watch.

BREQUEST/D:54000
BTRWATCH
----------------------------------------------

Load a Btrieve application and use it normally. Every time
the application accesses a Btrieve file, an entry is placed in
a file called BTRWATCH.LOG. The application will run slower
because of the additional time needed to log the Btrieve
information.
Next, exit out of the application and return to the DOS
prompt. Run the program called "WATCHBTR.EXE". This program
will allow you to view the log file. Select 'V' from the
main menu to display the log file. All Btrieve operations
will be listed in the file.

BASIC OPTIONS

This menu selection allows you to set various options for Btr Watch.

Log all Btrieve accesses

If this option is set to YES, all Btrieve file
accesses are logged. If this option is set to NO,
file access are only logged only if one of the status
codes from the status code list occurs.

Beep for all accesses

If this option is set to YES, a beep will sound for
every Btrieve operation. If this option is set to NO,
beeps will not sound for every Btrieve operation.

Beep for status code list

If this option is set to YES, Btr Watch will beep
when one of the status codes from the status code list
occurs. If this option is NO, Btr Watch will not
beep when a status code from the status code list
occurs.

Log the time

If this option is set to YES, the time will be
logged with each log entry. If this option is NO,
the time will not be logged.

Log the date

If this option is set to YES, the date will be
logged with each log entry. If this option
is 'NO', the date will not be logged.

Log file name

This is the name of the file Btr Watch will log the
Btrieve operations. If several stations are
logging to this file, make sure you put the full
file path to be sure all stations are using the
same file.

Beep tone

This is the hertz frequency of the beep sound made by
Btr Watch. The best values for this are between
1000 and 4000.

Beep duration

This is the length of the beep sound Btr Watch makes
in milliseconds.

ADVANCED OPTIONS

This selection allows you to set the advanced options for Btr Watch.

Log length

If this option is set to YES, the length of time a
Btrieve call lasts is logged. If this option is NO,
the time is not logged. The duration of the calls are
recorded in clock ticks. Each tick is 1/18 of a
second or about 55 milliseconds.

Check for open

If this option is set to YES, Btr Watch logs a
message if files were open when a RESET or STOP
operation occurs. If this option is NO, a message
is not logged.

Ignore stop

If this option is set to YES, Btr Watch does not allow an
application to unload Btr Watch from memory when it executes
a (25) STOP command. The Stop Command is also not passed to
Btrieve. The only way to unload Btr Watch and Btrieve from
your application when this option is set to YES is to set the
key number parameter to -1 when the STOP command is executed.
You are still able to unload Btr Watch and Btrieve with the
'Unload Btr Watch' menu option. If this option is set to NO
both Btr Watch and Btrieve are unloaded when the application
sends the (25) STOP command.

Check for multiple opens

If this option is set to YES, Btr Watch logs a message to the
log file when a file gets opened more than once at a time.
If this option is NO, a message is not logged.

Log the station name

If this option is set to YES, Btr Watch logs the station name.
If this option is NO, the station name is not logged.

Station name

This is a string describing the station where Btr Watch
is load. If you are using Btr Watch on more than
one station at a time, create different .CFG files for
each station. The path and name of the log file should
be the same for each of the different .CFG files. Each
station name should be different. Entering a different
name for each station allows you to follow the Btrieve
accesses from several stations.

File handle offset

This is the offset into the position block Btrieve is
supplied for each call. At this offset is a file
handle (integer) that is used by Btrieve and Btr Watch.
The handle is used to tell the difference between
different Btrieve files that may be open at the same
time. BTRIEVE.EXE and BREQUEST.EXE have different
offsets. These offsets may also change in the future.

Currently BTRIEVE.EXE uses 90 as the offset and
BREQUEST.EXE uses 126 as the offset.

STATUS CODE LIST

This is a list of status codes returned from Btrieve that Btr Watch
should monitor. If any of these status codes occur, Btr Watch can
be configured to beep and/or log up to 100 of the Btrieve operations
that occured before the specified status code. See the
'Basic Options' section to select how you want Btr Watch to react
to these status codes.

RETRY OPTIONS

Btrieve sometimes returns status codes indicating problems that can
be corrected by retrying the operation again. If an application
is trying to lock a record or file when the record or file is
locked, these status codes could be returned: (85) FILE IN USE and
(84) RECORD IN USE. Sometimes (2) I/O ERROR is returned and when it
is retried, it is successful. If the error is still returned after
several tries, it may indicate a real error and retrying will not
help. There are possibly other status codes that can be resolved by
retrying them and you can add them to the default list. Btr Watch
makes a note in the log file whenever it retries an operation. Up
to 10 different status codes can be monitored and the operations
can be retried if these status codes occur. The delay between
retries and the number of retries can be configured.

Retry status codes

This is a list of Btrieve status codes. If any of these codes
are returned by Btrieve, Btr Watch will call Btrieve again using
the same parameters 'Retries' number of times with a delay
between each retries.

Retries

This is the number of times Btr Watch should call Btrieve when a
status code from the Retry Status Codes list is returned. If 5
is entered in this field, the operation will be retried 5 times.
If 0 is entered, the operation will not be retried.

Delay between retries

This is the amount of time to wait in between retries of the
call to Btrieve. This value is in milliseconds.
1000 = 1 Second.

SAVE SETTINGS

Selecting this option causes the program settings for Btr Watch to
be saved to the file BTRWATCH.CFG. The next time BTRWATCH.EXE is
run or WATCHBTR.EXE is run, the settings are read out of this file.
Btr Watch must be unloaded from memory and reloaded before the new
settings take effect. A configuration file can be specified on
the command line if you want to load or save to a file with a name
other than BTRWATCH.CFG. If a configuration file is not given,
BTRWATCH.CFG is used as the configuration file.

VIEWING THE LOG FILE

The log file can be displayed using program WATCHBTR.EXE. Select
'V' from the main menu to display the log file. If you receive an
error when you try to display the log file either, there is not
a log file or the path to the log file is not correct. There will
not be a log file until BTRWATCH.EXE is run for the first time.
The path and file name of the log file can be set on the basic
options screen. The log file can be deleted while you are viewing
it by pressing 'D'. The log file can also be printed by pressing
'P' while it is being displayed. For more information on the keys
available while viewing a log file, see the LOG VIEWING KEYS
section.

LOG FILE FORMAT

The log file is stored in ASCII format and can be viewed with any
text editor. The format of the log file is as follows:

DATE TIME STATION LENGTH FILE KEY-NUMBER OPERATION RESULT

For example:

10 Aug 91 09:41:21 ==========[ BTRWATCH Loaded ]=========
10 Aug 91 09:41:35 0 0 Open
10 Aug 91 09:41:36 0 NWSPAPER.BTR 0 Get First
10 Aug 91 09:41:36 1 NWSPAPER.BTR 0 Get Next (9) END OF FILE
³ ³ ³ ³ ³ ³ ³
³ ³ ³ ³ ³ ³ ÀÄÄ Result
³ ³ ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄ Operation
³ ³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Key Number
³ ³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ File
³ ³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Length
³ ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Time
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Date

Some of these fields may not be present in your log file depending
on the program options that are set.

LOG FILE MESSAGES

The following is a list of messages you may find in the log file.

10 Aug 91 12:00:00 =========[ BTRWATCH Loaded ]=========

This message is logged whenever Btr Watch is loaded
into memory.

10 Aug 91 12:00:00 =========[ BTRWATCH Unloaded ]=========

This message is logged whenever Btr Watch is unloaded
from memory.

Some Btrieve calls are missing before the next entry.

Btr Watch's internal queue of Btrieve calls has overflowed
and some of the calls were removed from the queue and not
put in the log file.

More than 100 files are open.

Btr Watch keeps a list of all open files in memory. Btr Watch
can not keep track of more than 100 files open at once.

File EXAMPLE1.BTR was still open when a 'RESET' occured.

Btrieve was reset when a file was still open.

File EXAMPLE2.BTR was still open when a 'STOP' occured.

Btrieve was removed from memory when a file was still open.

File DATABASE.BTR was already open.

A Btrieve file was opened a second time without it first
being closed from the first time it was opened.

Status Code = (85) FILE IN USE, Retrying operation 'Open' again...

Btr Watch is retrying an operation after Btrieve returned a
status code from the retry list.

UNLOADING BTR WATCH

This menu option unloads Btr Watch and Btrieve from memory if they
are loaded. It also closes any open Btrieve files and aborts any
transactions.
When the 'Ignore Stop' option on the 'Advanced Options'
screen is set to 'YES', Btr Watch (TSR) passes the STOP command to
Btrieve only if the key value is set to -1. This allows WATCHBTR.EXE
to unload BTRWATCH.EXE (It sets the key value to -1.) but
Btr Watch (TSR) filters out STOP commands from applications.

COMMAND LINE ARGUMENTS

All command line arguments are optional.

WATCHBTR -SWITCHES

BTRWATCH

SWITCHES

-b Use BIOS for video writes. If your computer has
trouble displaying some of the windows on your
screen, use this switch. This assists with
incompatibility in the display.

-m Disables color. Runs the program in monochrome.

CONFIG FILE

The file contains all of the program options used by
WATCHBTR and BTRWATCH. A configuration file can be
specified on the command line if you want to load or
save to a file with a name other than BTRWATCH.CFG.
If a configuration file is not given, BTRWATCH.CFG
is used as the configuration file.

LIST OF FILES

BTRWATCH.EXE TSR Btrieve Debugger
WATCHBTR.EXE Configuration and Log File Viewer
WATCHBTR.HLP Help file for WATCHBTR.EXE
WATCH.BAT Batch file with example settings to load
BTRIEVE.EXE and BTRWATCH.EXE.
SITELICE.DOC Site license information.
REGISTER.DOC Registration information and a registration form.
VENDOR.DOC Disk vendor instructions.
SYSOP.DOC BBS operator instructions
README.DOC Installation instructions
BTRWATCH.DOC Btr Watch Documentation
PRODUCTS.DOC List of Informative Technologies' software.

CONTEXT-SENSITIVE HELP

Pressing F1 at any time displays a help screen that relates to the
current context of the program. Use the PgUp/PgDn keys to display
the different pages of help text on the screen. Use the arrow keys
to move between cross-referenced items on the help screen and press
[ENTER] to select another help item.

NOTES
All software or service names mentioned are trademarks, servicemarks
or registered trademarks of their respective holders.

TECHNICAL SUPPORT

There are several ways to contact the author:

1. Send Email on CompuServe to David Smith #71311,2334
2. Send a FAX to (202) 675-4529
3. Leave a message at the Programmers Corner BBS for
David Smith #1082, BBS# (301) 596-1180
4. Leave a voice mail message at (202) 675-4528 for David Smith.
5. By mail to:
David Smith
Informative Technologies Corporation
1718 M Street NW, Suite 292
Washington, DC 20036

Please include all relevant information regarding your
problem including:

1 - A description of the event.
2 - The steps that consistently reproduce the event.
3 - Btrieve version number, type, and command line
parameters. (BTRIEVE, BREQUEST, NLM, VAP)
4 - Hardware information. (Machine Type, Video Adapter)
5 - Command line used to load Btr Watch.
6 - Btr Watch version number.

Feel free to leave comments and suggestions to the
attention of David Smith.

Voice mail messages will probably not be answered until the next
day. Email responses will usually be the fastest, with a response
by the end of the day. If you are outside of the United States and
you need pre or post registration support, please include your
Email address or fax number when you leave a voice mail message
or send a fax.

ÚÄÄÄÄÄÄÄÄÄ¿
ÚÄÄÄÄÄÁÄÄÄ¿ ³ (R)
Äij ³o ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
³ ÚÄÄÄÄÄÁÐÄÄ¿ ³ Association of
³ ³ ³ÄÙ Shareware
ÀÄÄij o ³ Professionals
ÄÄÄÄÄij º ³ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ
ÀÄÄÄÄÐÄÄÄÄÙ MEMBER

The Association of Shareware Professionals (ASP) wants to make sure
that the shareware principle works for you. If you are unable to
resolve a shareware-related problem with an ASP member by contacting
the member directly, ASP may be able to help. The ASP Ombudsman can
help you resolve a dispute or problem with an ASP member, but does
not provide technical support for members' products. Please write
to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442 or send
a Compuserve message via Email to ASP Ombudsman 70007,3536.
The OMB may also be contacted by sending a FAX to the
ASP FAX number: (616)-788-2765. In communication with the OMB,
please include a telephone number and/or FAX number if available.

PROGRAM KEYS

CURSOR MOVEMENT

Arrow Keys Cursor Movement
Ctrl-Left Arrow Word Left
Ctrl-Right Arrow Word Right
Home Beginning of Field
End End of Line/Field
Ctrl-Home Beginning of First Field
Ctrl-End End of Last Field
Tab Next field
Shift-Tab Previous field

INSERTING AND DELETING

Ins Toggle Insert Mode
Del Delete Character at Cursor
Backspace Delete Character Left
Ctrl-Backspace Delete Word Left
Ctrl-T Delete Word Right
Ctrl-U Delete to End of Field
Ctrl-Y Delete to Last Field

OTHER EDITING KEYS

Enter Process Current Field
Ctrl-Enter or F10 Process All Fields
Ctrl-R Restore Field
ESC Abort Data Entry

SPECIAL KEYS

F1 Btr Watch Context-Sensitive Help
Alt+S Shell to DOS.
ESC Quit Btr Watch
Alt+F1 Toggle BIOS Screen Writes

LOG VIEWING KEYS

These keys are available while displaying the log file
with the 'V' View Log File menu option.

P Print the log file
D Delete the log file
H Display the log file help screen
X Exit from viewing the log file
Up Arrow Scroll the log file up one line
Down Arrow Scroll the log file down one line
Ctrl-Left Arrow Page left
Ctrl-Right Arrow Paqe right
PgUp Display previous screen
PgDn Display next screen
Home Go to the beginning of the log
End Go to the end of the log


  3 Responses to “Category : Databases and related files
Archive   : BCHWTCH.ZIP
Filename : BTRWATCH.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/