home *** CD-ROM | disk | FTP | other *** search
/ High Voltage Shareware / high1.zip / high1 / DIR4 / ZWDOS.ZIP / ZAPI.DOC < prev    next >
Text File  |  1993-03-05  |  9KB  |  261 lines
  1.  
  2. How to write programs to take advantage of ZWDOS's 
  3. Application Program Interface (ZAPI).
  4.  
  5. (C) Copyright Ya-Gui Wei 1993. All Rights Reserved.
  6.  
  7.  
  8.  Table of Contents
  9.  
  10.   I. Why Might You Want to Use ZAPI 
  11.  II. The ZAPI Function calls
  12.      Function 0: Query ZWDOS
  13.      Function 1: Get ZWDOS Version Number
  14.      Function 2: Set Chinese Compatible Mode
  15.      Function 3: Set ASCII Mode
  16.      Function 4: Display Chinese Character On Screen
  17.      Function 5: Display ASCII Character On Screen
  18.      Function 6: Soft Flush Display Buffer
  19.      Function 7: Hard Flush Display Buffer
  20.      Function 8: Get ZWDOS Mode
  21.      Function 9: Restore Auto-Switch
  22.      Function 0Ah: Get Bitmap Font for Chinese Character
  23.      Function 0Bh: Get Chinese Printing Configuration
  24.      Function 0Ch: Set Chinese Printing Configuration
  25. III. How to Print Chinese Characters from Your Program
  26.  
  27.  
  28.  *****************
  29.  
  30.  I. Why Might You Want to Use ZAPI 
  31.  
  32.     If you know how to write a DOS text mode program, you already know
  33.     how to write a Chinese program running under ZWDOS: You simply
  34.     prints an HZ-Chinese message to screen, and ZWDOS will display
  35.     them as Chinese for you. Why, then, might you need ZAPI?
  36.  
  37.     Currently, ZAPI offers these features that you may want to take 
  38.     advantage of:
  39.  
  40.     (1) The ability to switch ZWDOS to Chinese-Compatible or ASCII-only
  41.         modes from software;
  42.     (2) The ability to display Chinese character on screen without
  43.         having to use the HZ escape sequences.
  44.     (3) The ability to control ZWDOS's screen updating;
  45.     (4) The ability to obtain the bitmap font of a Chinese character;
  46.     (5) The ability to control how Chinese characters are printed;
  47.         etc.
  48.  
  49.     If any of the above features are useful for you, you may want to
  50.     use ZAPI in your programs.
  51.  
  52.  
  53.  II. The ZAPI Function calls
  54.  
  55.     The ZWDOS Application Interface is accessed through the MS-DOS
  56.     Multiplex Interrupt, by loading register AX with E6A7h (hex E6A7),
  57.     BX with a function number, other registers whenever neccessary,
  58.     the call interrupt 2Fh.
  59.  
  60.  
  61.     Function 0: Query ZWDOS
  62.  
  63.     At Entry:  AX = E6A7h
  64.                BX = 0000h
  65.            DX = 7A57h
  66.     On Return: AX = 7A57h if ZWDOS was loaded
  67.                otherwise ZWDOS was not loaded
  68.     Note: Make sure ZWDOS is loaded before calling any other ZWDOS 
  69.           functions.
  70.  
  71.  
  72.     Function 1: Get ZWDOS Version Number
  73.  
  74.     At Entry:  AX = E6A7h
  75.                BX = 0001h
  76.     On Return: AX = Version number in BCD Format.
  77.     Note: For exaple, for version 2.20, AX returns 0220h.
  78.  
  79.  
  80.     Function 2: Set Chinese Compatible Mode
  81.  
  82.     At Entry:  AX = E6A7h
  83.                BX = 0002h
  84.     On Return: Screen is switched to Chinese compatible mode.
  85.     Note: functions 4, 5, 6, 7, and 0Ah should be called
  86.           only when the screen is in Chinese Compatible mode.
  87.     Note: The automatic screen switching (between CC mode and
  88.       ASCII mode) is disabled after this call.
  89.  
  90.  
  91.     Function 3: Set ASCII Mode
  92.  
  93.     At Entry:  AX = E6A7h
  94.                BX = 0003h
  95.     On Return: Screen is switched to ASCII mode.
  96.     Note: The automatic screen switching (between CC mode and
  97.       ASCII mode) is disabled after this call.
  98.  
  99.  
  100.     Function 4: Display Chinese Character On Screen
  101.  
  102.     At Entry:  AX = E6A7h
  103.                BX = 0004h
  104.            CH = Row Number on Screen (0-24)
  105.            CL = Column Number on Screen (0-78)
  106.            DH = First Byte of 7-Bit Chinese Code (HZ)
  107.            DL = Second Byte of 7-Bit Chinese Code (HZ)
  108.            SI (low byte) = Attribute of Character
  109.     On Return: Character is queued for writing to requested 
  110.            screen position.
  111.     Note: Attribute is as text mode character attributes, with
  112.       the lower 4 bit representing foreground color and
  113.       higher 4 bit representing background character. 
  114.       High intensity background is not allowed.
  115.     Note: You can also display Chinese characters by writing
  116.           HZ codes to screen through DOS, BIOS or direct 
  117.       access to video memory. But the ZAPI function call
  118.       will allow you to write Chinese characters without
  119.       using the HZ escape sequences.
  120.  
  121.  
  122.     Function 5: Display ASCII Character On Screen
  123.  
  124.     At Entry:  AX = E6A7h
  125.                BX = 0005h
  126.            CH = Row Number on Screen (0-24)
  127.            CL = Column Number on Screen (0-78)
  128.            DH = Attribute of Character.
  129.            DL = ASCII character (8 bit) to write to screen
  130.     On Return: Character is queued for writing to requested 
  131.            screen position.
  132.     Note: Attribute is as text mode character attributes.
  133.       High intensity background is not allowed.
  134.  
  135.     
  136.     Function 6: Soft Flush Display Buffer
  137.  
  138.     At Entry:  AX = E6A7h
  139.                BX = 0006h
  140.     On Return: ASCII characters are flushed to screen. Chinese
  141.            characters for which font exists in font cache
  142.            are flushed to screen.
  143.     Note: this function is normally called from the timer interrupt
  144.           about 5 times a second.
  145.  
  146.  
  147.     Function 7: Hard Flush Display Buffer
  148.  
  149.     At Entry:  AX = E6A7h
  150.                BX = 0007h
  151.     On Return: If the font for a Chinese character does not exist
  152.                in the font cache, it is read from the disk font
  153.            library into the font cache, and the character image
  154.            is written to the display.
  155.     Note: this function is normally called from the DOS idle interrupt.
  156.           Do not call this from inside TSRs unless DOS re-entrancy
  157.       problem is watched for.
  158.  
  159.  
  160.     Function 8: Get ZWDOS Mode
  161.  
  162.     At Entry:  AX = E6A7h
  163.                BX = 0008h
  164.     On Return: AX = 1 if Screen is in Chinese Compatible Mode
  165.                AX = 0 if Screen is in ASCII Mode
  166.  
  167.     
  168.     Function 9: Restore Auto-Switch
  169.  
  170.     At Entry:  AX = E6A7h
  171.                BX = 0009h
  172.     On Return: If the Auto-Switch mode is on (manual mode is off)
  173.                before any calls to functions 2 and 3, this call
  174.            restores the auto-switch.
  175.     Note: If your program used functions 2 and 3, call this 
  176.           function before you exit.
  177.  
  178.  
  179.     Function 0Ah: Get Bitmap Font for Chinese Character
  180.  
  181.     At Entry:  AX = E6A7h
  182.                BX = 000Ah
  183.            DX = Chinese Character (DH=First Byte)
  184.            ES:DI = pointer to 32-byte buffer
  185.     On Return: if AX=1, buffer is filled with bitmap font.
  186.                if AX=0, font for character is not found in font cache.
  187.     Note: if the requested character font is not found in the cache,
  188.           it is queued for reading from the disk font library (along
  189.       with other read requests from the screen updating and 
  190.       printing routines), and the font is read when a Hard Flush
  191.       is either explicitly or implicitly called. A second call
  192.       to this function after a Hard Flush may be successful. If,
  193.       however, if fails after a Hard Flush, the character may be
  194.       a bad code or for which the bitmap font is not defined.
  195.     Note 2: the size of the above read queue is guaranteed to be
  196.           more than 200 entries. Repeated requests with the same
  197.       character result in repeated entries in the queue. The
  198.       font cache is guranteed to hold fonts for 256 characters,
  199.       and usually holds much more.
  200.  
  201.  
  202.     Function 0Bh: Get Chinese Printing Configuration
  203.  
  204.     At Entry:  None
  205.     On Return: AL = Printer Type
  206.             0: No Printer
  207.             1: 9 Pin Dot Matrix Printer
  208.             2: 24 Pin Dot Matrix Printer
  209.             3: HP LaserJet
  210.             4-FFh: Reserved
  211.            AH = Dot Matrix Printer Type
  212.                 0: IBM ProPrinter Compatible
  213.             1: Epson Compatible
  214.             2-FFh: Reserved
  215.            BL = Printer Resolution (LaserJet Only)
  216.             0: Low Resolution (100 dpi on LaserJet)
  217.             1: Medium Resolution (150 dpi on LaserJet)
  218.             2: High Resolution (300 dpi on LaserJet)
  219.             3-FFh: Reserved
  220.            BH = Printer Port to Use for Chinese Printing
  221.                 0: LPT1
  222.             1: LPT2
  223.             2-FFh: Undefined
  224.            DL = Print Vertical
  225.                 0: Chinese text printed horizontally
  226.             1: Chinese text printed with 90 degree rotation
  227.             2-FFh: Undefined
  228.            DH = Print Blank
  229.                 0: HZ and zW escape sequences not printed at all
  230.             1: Escape sequences printed as two ASCII spaces
  231.             2-FFh: Undefined
  232.  
  233.  
  234.     Function 0Ch: Set Chinese Printing Configuration
  235.  
  236.     At Entry:  Registers set up with printing configuration info
  237.                as described for Function 0Bh.
  238.     On Return: None
  239.     Note: Do not change printer config while printing is going on.
  240.           Do not use undefined or reserved values.
  241.  
  242.  
  243.  
  244. III. How to Print Chinese Characters from Your Program
  245.  
  246.     To print Chinese characters, you simply send the Characters in
  247.     their HZ coded format to the printer device through relevant
  248.     DOS or BIOS calls, or through their high level language 
  249.     implementations, as you normally would with ASCII applications. 
  250.     The output will be printed as Chinese characters if the screen
  251.     has been switched to Chinese compatible mode.
  252.  
  253.     You should use ZAPI Functions 0Bh to check the Chinese printing
  254.     configurations, particularly the "Print Blank" set-up, which
  255.     governs whether the HZ/zW escape sequences are printed as
  256.     blanks or not printed at all.
  257.  
  258.  
  259.     March 4, 1993
  260.     [End of Document.]
  261.