install_hk(hk_list, service, stack_size, lock_mask);

int hk_list[] : {KEY_W + MASK_LEFT_SHIFT +
                MASK_LEFT_CTRL,
              KEY_T + MASK_LEFT_ALT + MASK_RIGHT_ALT,
              0};

The second argument is a pointer to the dispatching function which will be called whenever a key in the hk_list[] is pressed. The function service() must be of type void and must receive the scan code of the actual keypress as its argument. The service() function is supplied by the application but usually follows a standard sequence of operation. First, service() checks the current video mode and changes the mode if neccessary. Next, service() dispatches the actual function associated with the hot-key. After returning, service() checks the stack to determine how much has been used. Last, if TSR removal has been requested (perhaps by a hot-key), then service() calls uninstall() to remove itself.

The third argument to install_hk() is the local stack size for this invocation of the TSR. The stack size is in bytes and must always be an even number. The local stack is allocated from the global stack area designated in the call to stay_resident() which established this TSR. If the TSR is to be reentrant, then the sum of the local stack sizes from all execution threads must be less than the size of the global stack area.

The final argument specifies the reentry control mask. This mask allows you to selectively disable reentrancy due to keyboard or scheduler interrupts. For example, you may want to prevent the user from popping up your TSR via a hot-key if it is still processing the previous hot-key request. The actual reentrancy check is a semaphore which must be clear prior to calling the service() function.

Since the install_hk() function may be invoked only once per TSR, some additional hot-key management functions are needed after the code becomes resident. The _hk_add() and _hk_remove() functions allow hot-keys to be added and removed at any time. The _hk_used() function tells whether a given hot-key is in the current active list. Last, the _hkey_again variable is true if the same hot-key was hit twice in a row.

CodeRunneR is initially shipped with the BCD library precision of 16 digits. After users register the product, the company mails 3 new copies of the library configured for 12, 24 and 248 digits of precision. The new library provides the following operator functions: add, subtract, multiply, divide, square-root, divide-by-2, compare, round, and truncate. It does not provide trigonometric or exponential functions. MSI claims that the entire BCD library adds less than 1K to the size of your application.

Using CodeRunneR requires giving up nearly all of the functions supplied with your compiler's runtime library. Only functions which do not access code or data in the startup module may be used. (CodeRunneR requires that you use its startup module, which is incompatible with most of the compiler's runtime library.) Unfortunately, this means runtime library functions involving file I/O, console I/O, memory allocation and floating point may not be used. Using any of these functions results in unresolved externals at link time.

Scheduler support must be installed in the initialization section of your application. The Master scheduler is initialized via the install_sch() function. A sample invocation might be:

install_sch(service, stack_size, lock_mask);

struct event_rec {
   int link;                /*  pointer to next event */
   unsigned long tick_cnt;  /*  number of ticks before event */
   };

The last argument is the reentry control mask. This argument also acts identically to its counterpart in the install_hk() function mentioned earlier. A lock_mask value of 01h prevents another event from becoming due and reentering the service function before it is finished with the current event. If an event is locked-out because of the reentry control mask, it will try again on each subsequent clock tick until it is successful.

The library provides a number of event-management functions to allow dynamic manipulation of the event list. The add_event() function accepts a pointer to an event record and sorts the event list. The del_event() function allows any event record to be deleted. The _transfer_time() function suspends the scheduler so the event list can be manipulated directly by the application. The _prep_nx_event() function resumes the scheduler after being suspended by _transfer_time(). The no_event variable is always updated to indicate the number of events remaining in the list.

Disposable data is defined as global variables that are only referenced during program initialization. Data which is not disposable is referred to as permanent data. Uses of disposable data include sign-on screens, error messages and keyword lists for parsing command lines. All disposable data must be physically grouped into modules containing only this type of data.

The PDK#1 serial I/O support allows interrupt-driven or polled communication at speeds up to 115K baud. Low-level service routines may be defined for all four of the 8250 and 16550 UART interrupts: Modem Status, Transmit Ready, Received Byte and Receive Error. Other serial I/O functions allow you to compute CRCs against buffers, emulate VT-100 terminals (ANSI) directly, and manage hardware and software flow control.

The EMS support in PDK#1 provides several services. First, the move_to_lim() function provides your TSR with a single-step operation to install its code and/or data into EMS memory. When a TSR is installed in EMS memory, as little as 1K of resident code in DOS memory is required. TSR programs which require far heap allocation, interrupt-driven communication or re-vectoring software interrupts cannot be loaded into EMS memory. Second, the EMS functions enable you to allocate, deallocate and manipulate 16K EMS pages and page mappings. The PDK#1 documentation for these functions assumes that you are already familiar with EMS addressing schemes.

Last, PDK#1 provides a registration copy-protection scheme for applications that you develop. This set of functions allows you to create a shareware application that may be partially or wholly crippled until registered by the end-user. The registration process can encode the user's name and company right into your executable. A checksum and debugger detection mechanism can prevent users or viruses from modifying your executable.

Since the PDK#3 package was still in Beta testing during this evaluation, I will remark on its contents only briefly. PDK#3 introduces several ways to swap out either the TSR or foreground application. These programs may be swapped out to EMS or disk to make room for spawning other DOS applications. After the spawned application exits, the TSR or foreground program swaps itself back into DOS memory. The other major feature in PDK#3 is the ability to save and restore graphics displays. You can save and restore the mouse status as well.

An introductory section entitled "Hints for Efficient C Programming" is a jumble of general C programming techniques and specific hints for writing CodeRunneR applications. Some of the hints amount to a quixotic indictment of the efficiency of C compilers. For example, hint #24 admonishes the reader that modular, readable, structured and object-oriented coding practices are a rich source of inefficiency.

The CodeRunneR manual is written for seasoned MS-DOS programmers. For example, if you don't understand the structure of the Program Segment Prefix (PSP), this book won't explain it for you. You will need a reference book, such as Ray Duncan's Advanced MS-DOS (2nd Ed.), which details the parameters of every BIOS and DOS interrupt. The text makes frequent references to operating system calls, such as "See BIOS INT 10h" and "See DOS INT 21h, function 3Eh". The "File I/O" function descriptions are especially terse, often mentioning little more than the INT 21h function code.

In addition to the highly technical treatment, the lack of illustration adds to the complexity. Not a single graphic illustration appears in the entire text. Illustrations would make the text less dense and make abstractions, such as the memory map and scheduler operations, easier to comprehend.

The documentation is accurate for the most part, but does contain numerous typographical errors and has some problems with the example code fragments. Many function descriptions advise you to turn to a different page number for an example. However, in many cases, the example code fragment referenced does not include a call to the function in question. For instance, each of the six function descriptions in the "Software Interrupt" section advise you to see page 4-142 for an example. Contrary to this statement, there are examples for only two out of the six functions in this section.

There is also some confusion involved with the descriptions of the BCD library. Page 1-3 states that the BCD package has "variable precision to 248 digits". Later in the same paragraph, it states the BCD package has "248 bits of precision". These are not the same thing when base-10 or BCD arithmetic is considered. This kind of ambiguity occurs on page 1-7. It is finally made clear in on page 5-1, stating that there are 248 digits of precision rather than 248 bits of precision.

Each PDK is sold as a separate product and comes with its own set of documentation. The documentation for the PDK #1 extensions consists of a 100-page spiral-bound book. Unlike the CodeRunneR manual, the PDK #1 book does not have an index. The PDK #3 extensions are still in beta testing so its documentation will not be considered. If you were using all of the PDK extensions with CodeRunner, you might have some difficulty locating the reference for a particular function. (There is not a master index across all of the books.)

MSI provides support through two different channels. First, they offer a customer support hot-line and fax, which is available during business hours. This support is available for an unlimited time after registering the software. Second, the company offers support through its own Bulletin Board System (BBS).

MSI has one of the best BBS support lines I have seen yet. The BBS runs 22 hours/day with eleven phone lines; eight of these support up to 2,400 baud and three support 9,600 baud and 14,400 baud. Registered users of MSI products have unlimited download privileges and are allowed up to three hours per day on the BBS. Most importantly, all new releases and beta versions of MSI software are posted immediately on the BBS. During the course of my review, I took advantage of this and upgraded from CodeRunner v1.05 to v1.06. Users without a modem can upgrade to the latest version of CodeRunneR by having a diskette mailed to them for a $10 service charge. In addition to the very latest versions of MSI products, the BBS also has approximately 1,000 megabytes of public domain software online via CD-ROM. The response time to the questions I posted on the BBS was excellent. The questions I called in on a Saturday morning were answered before noon on the same day.

For lack of a better method, I began the porting process by first building the program template provided in the CodeRunneR examples directory. Next, I broke up my source code to provide a hot-key pop-up entry point besides the initialization entry point in main(). Then I replaced the initialization and pop-up functions in the template program with those from my own application. The remainder of my effort was spent reconciling the CodeRunneR library with the MSC 5.1 runtime library.

The first incompatibility I came across was the handling of the main() function in the startup module. Unlike the standard runtime startup module, the CodeRunneR startup module does not pass argc and argv to the main() function. Instead, the program arguments are left in an externally defined null-terminated string called cmd_line. If your program relies on argc and argv, then you will have to parse the command line and initialize them yourself.

The next compatibility hurdle was dealing with the file I/O functions. Coderunner provides some substitute functions which can be enabled by including the SIO.H file. However, these are only stub functions for the DOS INT 21h, file access calls. This means that only block I/O file functions (open (), read(), etc.) are supported and stream I/O functions are not. Luckily, my application used only one significant stream I/O function, fgets (), which I then had to rewrite for myself. The CodeRunneR I/O functions do not match the standard naming conventions. Instead, the block I/O functions are named like the stream I/O functions (fopen(), fread(), etc.) are supposed to be.

The CodeRunneR product excels in its TSR capabilities, coexistance with other DOS applications and technical support. If you are an experienced MS-DOS developer, then you should consider CodeRunneR for your TSR needs.

References

Davidson, Mark. "TSR Libraries: Pop-up Programming". Computer Language, May 1990. pp. 127-136. (A round-up of four TSR building libraries, including CodeRunneR).

Volkman, Victor R. "Multitasking with the DESQview API Library". The C Users Journal, July 1990, pp. 99-109. (Another application developed using the DESQview API library).

QEMM and DESQview are registered trademarks of Quarderdeck Office Systems, Inc.

386-to-the-MAX is a registered trademark of Qualitas, Inc.

CodeRunneR is a registered trademark of Microsystems Software, Inc.

CodeRunneR

Micro Systems Software, Inc.

600 Worcester Rd.

Framingham, MA 01701

(508) 626-8511