BlackBook v1.00c for OS/2

by Viêt-Tâm Luu

User's Guide

Copyright © 1996 Viêt-Tâm Luu.

This document may be freely distributed, but it may not
be modified (with the exception of conversion to other
formats) without the expressed consent of the author.

This document was created for viewing with IBM WebExplorer 1.03 or later. It will still be readable using other HTML viewers, but some parts may appear missing or formatted incorrectly.

Appendix A: About BlackBook

Build Notes and Remarks

BlackBook is written in C++ using IBM's Visual Builder tool. Source code consists of about 20 C++ files, totalling about about 3300 lines of hand-written code, along with about 9000 lines of code generated by Visual Builder. It is implemented using IBM's OpenClass class library (hence the rather bloated size of BlackBook.exe). The executable is compiled using IBM VisualAge C++ 3.0 (fix level 304) for OS/2.

Despite the tremendous amount of extra functionality that OpenClass offers, it is way too bloated and buggy for my liking. I might eventually re-write BlackBook in C or with a proprietary ``thin wrapper'' class library to improve performance and reliability. Eventually.

BlackBook Notify is written in C, and consists of one C source file with about 1200 lines of hand-written code. The executable is compiled using IBM VisualAge C++ 3.0 (fix level 304) for OS/2.

BlackBook Installation is written in C, and consists of one C source file with about 900 lines of hand-written code. The executable is compiled using IBM VisualAge C++ 3.0 (fix level 304) for OS/2.

Source files were edited using EPM 6.03b for OS/2 and Watcom vi for OS/2. Bitmaps and icons were drawn using the standard OS/2 Icon Editor.

BlackBook was written over a period of about two and a half months, starting in May 1996. From this, the author estimates that this project has taken between two and three hundred hours of work (after hours and on weekends).

The author would like to thank the following individuals:

Matthew ``Hell's'' Bells for his continuing input and feedback.
Nick Knight of Secant Technologies for his collaboration in adding support for BlackBook in MR/2 ICE.
David Auerbach for finding bugs and patiently trying out fixes.
Manon Lessard for her friendship and support.

Known Bugs and Limitations

Pushbuttons can't be activated using the spacebar. Similarly, checkboxes can be toggled using the spacebar but no actions are triggered by doing so, leading to possibly strange results (e.g. in the Configuration dialog). Appears to be an OpenClass bug.
Notebooks ignore NumLock state when in Read-Only mode (e.g. typing in ``9'' on the keypad acts as PgUp). (Bug? Feature?)
Can't use alt + keypad to type in some special characters (those with ``3'' and ``9'' as digits in their codes) within notebooks. PM notebook control limitation/bug.
``Ghost'' windows sometimes left after closing BlackBook. Utilities such as Process Manager (PROCMAN.EXE) and Lotus SmartCenter list a BlackBook window (most commonly BlackBook Record Name) when none exists (BlackBook is not running). Making most of the BlackBook windows non-modal has largely but not entirely alleviated this problem. The only way to get rid of these seems to be by rebooting. No critical side effects as far as I can tell, but those non-windows can accumulate and look annoying if using SmartCenter. Possibly a bug in PM or OpenClass.
Some people have reported errors when trying to activate MR/2 ICE from BlackBook. The screen goes info full-screen text mode, reverts to graphics mode, and MR/2 ICE fails to load. I have been unable to reproduce the problem, though it is symptomatic of MR/2 not being able to find its DLL's, though the correct directory is switched to before executing an external mailer, so I can't see why this is happening.
BlackBook may require TCP/IP to be installed (be it in the form of the TCP/IP support in Warp Connect, or the Internet kit on the OS/2 BonusPack), even if its Internet features (e.g., mailer) are not used; if TCP/IP is not installed, OS/2 will report ``SYS1804: The system cannot find the file SO32DLL.'' The user who reported this was using the Merlin beta build 18, so I'm not sure if this is a Merlin-specific problem.

If you think you've found a bug: Can you reproduce it (i.e. can you cause the error to occur more than once)? Is it not in the ``Known Bugs'' list (above)? Is it not fixed in the latest version of BlackBook (go to the BlackBook Home Page for the latest information and updates)? Is it not otherwise documented? Are you using the program within what could be considered ``normal'' parameters?

If you answered ``yes'' to all the above questions, or if you think you may have information that could shed more light upon the nature and cause of the bug, then please let the author know about it via E-mail, and he will be glad to look into the problem.

Check out the BlackBook Home Page for more information, as well as a troubleshooting tips and frequently-asked questions.

Revision History

BlackBook v1.00

First public release (96/07/19).

BlackBook v1.00c

First maintenance release (96/07/27): no changes to BlackBook, bug fixes to BlackBook Birthday Notification, documentation updates.
Assertion failure (harmless) when specifying a non-existent or invalid file to BlackBook Notify. (fixed)
On certain video cards and/or drivers, the list in BlackBook Notify appeared in incorrect colours (black on black). The ``Hardwired colours'' option has been added to address this problem. (fixed)
BlackBook Notify did not update the list (days until birthdays) when notification was disabled. (fixed)
BlackBook Notify failed to notify if the ``no notification before'' time was anything other than midnight. (fixed)
BlackBook Notify failed to recalculate days until birthdays under certain conditions. (fixed)
BlackBook Notify now notifies, regardless of the ``no notification before'' time, when notification for all records is enabled.
Version number updated in Product Information window.
Documentation updates.

BlackBook Birthday Notification v1.00b

Released as an upgrade to Notify only, not as a whole package. Fixes to BlackBook Notify for users with display problems (notably with Cirrus Logic cards and drivers).
Certain details were missed in implementing the ``Hardwired colours'' fix/workaround for those with display problems, and so it may or may not have worked at all. (fixed)

BlackBook v1.00c

Second maintenance release (96/08/04): bug fixes in BlackBook, minor feature added to BlackBook and Notify, documentation updates.
BlackBook saved the filenames of photo files incorrectly if they were added to the database when it was first created (i.e. before the database was saved and re-opened). This prevented the photos from displaying correctly, and prevented the user from re-specifying the photo files. (fixed)
As a consequence of the above fix, BlackBook now recalculates any ``relative paths'' to photo files whenever the database file is saved. If the photo can be found with the same sub-path relative to the database's new directory, the relative path is unchanged. Otherwise, the photo's path is set to its old location, relative to the new one if possible.
New feature: you can know enter an illegal or zero year for a person's birthdate, in case you don't know the year of a person's birth; this results in ?? being displayed for the year of birth, both in BlackBook and in Notify.