CD Shareware Masterblend/cdsharewaremasterblend.iso/bus-apps/zip-code/zprog.doc

Text File | 1990-10-15 | 32KB | 791 lines

PROGRAMMATIC INTERFACE DOCUMENT


This file is intended for computer programmers who wish to access
ZIPKEY directly from within their programs.  If you are not a
computer programmer, you may ignore this file.


The ZIPKEY Interrupt

When ZIPKEY is installed as a memory-resident program (using the
ZIPKEY 4 command), it takes over one of the 8086's interrupts,
INT 179 (decimal; it's B3 in hexadecimal).  This interrupt serves
two functions: first, it is the method by which ZIPKEY detects if
it has already been installed.  Second, it provides the interface
by which computer programs can call ZIPKEY directly, to obtain
zipcode-related services.

I conducted a survey of numerous computers before selecting INT
179 to be used by ZIPKEY.  I found no computers or peripherals
that use this interrupt, and I am hopeful that there are none.
If your computer does use INT 179, then ZIPKEY and the device or
program using INT 179 will interfere with each other.  You can
change the interrupt number ZIPKEY uses by modifying the ZIPKEY
program itself: the number 179 is stored in the fourth byte of
the ZIPKEY program code, immediately beyond the three-byte JMP
instruction that begins the program.  This JMP occurs at the very
start of the ZIPKEY.COM file, or immediately beyond the 512-byte
header of the ZIPKEY.EXE file.  You can use a debugger or a hex
editor to modify the byte to an unused interrupt number.


Testing for ZIPKEY's Presence

Before you program attempts to call ZIPKEY, it may wish to verify
that ZIPKEY has been installed, and report an error if it isn't.
Otherwise, you program may crash when it tries to call code that
isn't there.

You can test for ZIPKEY's presence by examining the INT 179
handler, whose doubleword pointer is stored at offset 179*4 (=716
=02CCH) within segment 0 of the 8086 memory space.  If ZIPKEY is
installed, the doubleword points to its code segment.  Location
075H within that code segment contains the signature string
ZIPKEY.  Thus, the following code sequence will check for
ZIPKEY's presence:
                                                              P-2

OUR_ZIPKEY:                ; our copy of the template
  DB 'ZIPKEY'

CHECK_FOR_ZIPKEY:
  PUSH DS                  ; save register value
  SUB AX,AX                ; load zero
  MOV DS,AX                ; point DS to 0 -- 8086 interrupts
  MOV DS,WORD PTR 02CEH    ; fetch the segment part of INT 179
  MOV SI,075H              ; point to signature in segment
  PUSH CS                  ; push our code segment
  POP ES                   ; set ES to our code segment
  MOV DI,OFFSET OUR_ZIPKEY ; now ES:DI points to 'ZIPKEY'
  MOV CX,3                 ; there are 3 words in 'ZIPKEY'
  REPE CMPSW               ; does DS:75H point to 'ZIPKEY'?
  POP DS                   ; restore register before jumping
  JZ ZIPKEY_INSTALLED      ; jump if it does match
ZIPKEY_NOT_INSTALLED:      ; it does not match

Following the ZIPKEY signature, at offset 07BH within the ZIPKEY
code segment, is a single byte that is zero in the initial
version of ZIPKEY, but will increment each time I release a
ZIPKEY with new features or any other changes to the programmatic
interface.  That way, if you program needs ZIPKEY to be of a
sufficiently recent version, it can ensure that it is.  (You can
also use the version number returned by the ZK_VERSION function
described shortly.)


ZIPKEY Calling Conventions

ZIPKEY's interface works similarly to that of the MS-DOS
operating system, or the LIM-EMS specification.  The interface is
specified in 8086 assembly language.  You load a function number
into the AH register, and possibly other input parameters into
other registers, then you execute an INT instruction with an
appropriate interrupt number -- in ZIPKEY's case, the INT 179
instruction.

When ZIPKEY has completed the function, it returns control to
your program at the instruction following the INT 179.  The
success of the call is indicated by the Carry flag: NoCarry (flag
= 0) indicates success; Carry (flag = 1) indicates failure.  If
the Carry flag is set, AL is usually set to an error code (the
exceptions are those functions which, as mentioned in their
following descriptions, return the state code for a suggested
city).  Here are the possible error codes:

0FDH is returned if ZIPKEY is busy. You will get this error only
     if the program calling ZIPKEY had interrupted another
     program which also happened to be in the middle of a ZIPKEY
     call.  ZIPKEY is not reentrant, so it must refuse calls in
     this situation.  If you think this interrupted-programming
     scenario is possible, you should check for this possibility.
     If ZIPKEY is busy, you should give the interrupted code a
     chance to complete the ZIPKEY call, and try your call again
     later.
                                                              P-3

0FEH is returned if you provided an illegal function number in
     the AH register.

0FFH is returned if the searching function requested failed to
     find a valid entry, or even a suggested value.

Here are ZIPKEY's register-preserving conventions:  The AX
register is clobbered by an INT 179 call; but all other 8086
machine registers are preserved unless they are specifically
named as having return values.  If a function returns an error,
such return registers may be clobbered even if they contain no
values in the return case.  For example, the ZK_STCITY_ZIP
function returns values in BH, CX, and DX.  Except for AX, all
other registers not mentioned are preserved (SI,DI,BP,DS,ES).
The BH, CX, and DX registers may be clobbered even if the search
fails (and Carry is returned).


The ZIPKEY Functions

Following are the functions available to you when ZIPKEY is
installed. For each function, you load the input registers with
the values indicated, then invoke INT 179.

The names of the functions (ZK_VERSION, ZK_ABBR_ST, etc.) have no
significance to ZIPKEY-- I present them merely as suggested names
if you wish to implement a library of calls; and also so that I
can refer to the functions by name.

ZK_VERSION:   returns ZIPKEY version information.

  In: AH = 070H

 Out: AX = The ZIPKEY program version number, as shown when
         ZIPKEY is invoked or the ZIPKEY window is popped up.  AH
         is the major version number (to the left of the decimal
         point) and AL is the minor version number (to the right
         of the decimal point).  For example, for V1.0 the return
         AX value would be hex 100.

      CL = The number of states, (and territories, etc.) in the
         current database.  Each state is assigned an internal
         numeric code by ZIPKEY, that is used by many of the
         functions of ZIPKEY's programmatic interface.  These
         codes range from 0 to CL-1.

      DX = The date of the current ZIPKEY.OVL database.  DL is
         the month, ranging from 1 for January to 12 for
         December.  DH is the year minus 1900; e.g., decimal 89
         for 1989.
                                                              P-4

ZK_ABBR_ST:   converts a two-letter abbreviation into a state
              code.

 In:  AH = 071H

      BX = The 2-letter ASCII abbreviation for the state, in
         either upper- or lower-case.  BL is the first letter and
         BH is the second letter.

Out:  AL = The ZIPKEY state code, suitable for input to other
         ZIPKEY functions in this chapter.

         AL = 0FFH with the Carry flag set if not found.


ZK_ST_ABBR:   converts a state code into a two-letter
              abbreviation.

 In:  AH = 072H

      BL = The ZIPKEY state code, ranging from 0 through CL-1,
         where CL is returned by ZK_VERSION.

Out:  AX = The 2-letter ASCII abbreviation, upper case.  AL is
      the first letter and AH is the second letter.

      The Carry flag is set if the input state code BL was
      invalid.


ZK_ST_NAME:   converts a state code into a full state name.

 In:  AH = 073H

      BL = The ZIPKEY state