tcxl.doc

就一个字强.很不错,希望大家能喜欢.这是我朋友发给我的

                                    T C X L
                    An Extended Function Library for Turbo C
                                  Version 3.3
                                 by Mike Smedley
                       (c) 1987, 1988  All Rights Reserved

    This library is intended to be a supplement to the Turbo C function
library.  It contains over 170 functions designed for use with the tiny and
small memory models.  Libraries for the other models are provided with
registration.  This library was compiled with Turbo C 1.5, however, you do not
need TC 1.5 to use this library.  The following files should be included in
this archive:

                TCXL.DOC      - the library documentation
                TCXL.H        - header file for all functions
                TCXL.LIB      - the object code library
                TCXLDEF.H     - header file for miscellaneous functions
                TCXLDEMO.C    - the demonstration program source code
                TCXLDEMO.EXE  - the demonstration program
                TCXLDEMO.MAK  - the make file used for compiling the demo
                TCXLDEMO.PRJ  - project file used for compiling the demo
                TCXLDSK.H     - header file for disk functions
                TCXLEMS.H     - header file for EMS functions
                TCXLHIST.DOC  - history of changes
                TCXLKEY.H     - header file for keyboard functions
                TCXLMOU.H     - header file for mouse functions
                TCXLPRN.H     - header file for printer functions
                TCXLQREF.DOC  - quick reference for TCXL functions
                TCXLSTR.H     - header file for string functions
                TCXLVID.H     - header file for video functions
                TCXLWIN.H     - header file for windowing functions


Features of the TCXL Function Library.

            -   Windowing with multiple windows
            -   Lotus/Intel/Microsoft EMS memory usage
            -   EGA 43-line and VGA 50-line modes
            -   Mouse functions for Microsoft compatible mice
            -   Direct screen writing for fast screen writes
            -   Screen/window swapping to memory or disk
            -   DESQview window compatibility
            -   Advanced string manipulation
            -   String Pattern matching
            -   Data encryption
            -   Multi-field keyboard input from within windows
            -   Bar-selection/pull-down menus
            -   Formatted keyboard input
            -   Equipment detection
            -   Printing functions
            -   Sound function
            -   and more!







                                      1    



Registration Information.

    You are free to copy and distribute this library freely, however, if you
find this library of use to you, you are encouraged to register your copy.  The
registration cost is $20.  Included in this registration cost is technical
support; libraries for the Medium, Compact, Large, and Huge memory models;
low-cost upgrades to future revisions; and best of all, the complete library
source code!  This library may not be used in commercial applications without
registration.  To register, please send payment and current version number to:

                    Mike Smedley
                    2441 N.E. Loop 410 #1505
                    San Antonio, TX 78217

    Or, for more information, I can be reached at one of the following points
of contact:

        Telephone       -   [phone]  (no collect calls, please)
        CompuServe      -   User ID:  71331,2244
        GEnie           -   Mail address:  M.SMEDLEY
        Abbey Road BBS  -   [phone]  1200/2400/9600 8-N-1
        Telstar BBS     -   [phone]  1200/2400 8-N-1



DISCLAIMER:  The author claims no responsibility for any damages caused by the
use or misuse of this library.  This product is distributed "as is" with no
warranty expressed or implied.


Trademarks Used:

    CompuServe is a registered trademark of CompuServe Incorporated.
    DESQview is a trademark of Quarterdeck Office Systems.
    Epson is a registered trademark of Seiko Epson Corporation.
    IBM is a registered trademark of International Business Machines.
    LIM and EMS are trademarks of Lotus, Intel, and Microsoft Corporations.
    Microsoft is a registered trademark of Microsoft Corporation.
    Turbo C is a registered trademark of Borland International.

















                                      2    





Calling TCXL Functions from Turbo C.


    To call these functions from Turbo C, you will need to have a line in your
source code file including the appropriate TCXL header file.  Example:

        #include "tcxlwin.h"

    You will also need to link in the TCXL.LIB file when you link your program.
You can do this in one of three ways:

        1.  Compile & link from the environment.  Your project (.PRJ) file
            must contain 'TCXL.LIB' in it.  It should look like:

                myfile tcxl.lib

        2.  Compile & link from the command line.  Type:

                tcc myfile tcxl.lib

        3.  Command line link only.  Type:

                tlink c0s myfile,myfile,,tcxl emu maths cs /c/x































                                      3    


Calling TCXL Functions from Assembly Language.


    Most of TCXL's functions (excluding macro-functions) can be called by
assembly language.  Some functions will require the Turbo C CS.LIB library to
be linked in also.  Any TCXL function which calls the Turbo C malloc() function
cannot be called by an assembly program because malloc() needs information from
the C0S.OBJ startup code.  Functions that use malloc() include some string
functions, screen save/restore functions, and windowing functions.
  
    Turbo C passes its arguments to a function via the stack.  Arguments are
pushed onto the stack in reverse order.  Turbo C places the underscore symbol
preceeding the function name, so to call the getns() function, you must call it
by _getns.  After the call to the function, you must readjust the stack.  For
every push on the stack, the stack pointer needs to be incremented by 2.  The
return value (if any) will be in the AX register.  Functions that return 16-bit
values will have the high value in DX and the low value in AX.  Here's an
example for the getns() function:

            EXTRN   _getns:NEAR         ; so assembler won't flag an error
            mov     ax,30               ; maximum length of input string
            push    ax                  ; push it onto the stack
            mov     ax,OFFSET straddr   ; address of string to receive input
            push    ax                  ; push it onto the stack
            call    _getns              ; call the function
            add     sp,4                ; adjust stack 2 for every argument
            or      ax,ax               ; is return value = 0?
            jnz     exitprog            ; no, Esc was pressed, exit program
            (rest of program)

    Here's how to assemble and link your assembly language program with the
TCXL function library:

        1.  Assemble your assembly source code file with the case-sensitive
            switch on:

                masm /mx myfile ;

        2.  Link your object file specifying TCXL as a library:

                link myfile,,,tcxl cs

        3.  Convert to a .COM file if applicable:

                exe2bin myfile myfile.com












                                      4    


Using TCXL's Windowing Functions.


    TCXL has a a powerful windowing system that can be very useful in an
application program.  All windowing functions are prefixed with a 'w'.  The
windowing is controlled by TCXL's window manager which is called by every
windowing function.  The window manager keeps track of which window is active;
each window's position, cursor location, attributes, etc.; how many windows are
open; and other information.  All windowing functions set the _werrno global
variable before returning.  The literal value of this variable can be viewed
by calling the werrmsg() function.

    You may open as many windows as memory permits.  Once a window is opened,
it immediately becomes the active window.  TCXL's windowing functions can only
be performed on the active window.  If you want to perform a function on a
inactive window, you must activate it first.  See the supplied TCXLDEMO.C
program for a complete example of how to use the windowing system.


    Example:

        int w1,w2;                              /*  window handles  */
        w1=wopen(0,0,10,40,0,LCYAN|_BLUE);      /*  open 1st window  */
        if(!w1) error_routine();                /*  check for error  */
        waitkey();                              /*  wait for keypress  */
        wputs("Hello, ");
        waitkey();                              /*  wait for keypress  */
        w2=wopen(7,20,18,60,2,LRED|_MAGENTA);   /*  open 2nd window  */
        if(!w2) error_routine();                /*  check for error  */
        wputs("Hello, ");
        waitkey();                              /*  wait for keypress  */
        if(wactiv(w1)) error_routine();         /*  activate 1st window  */
        wputs("there");
        waitkey();                              /*  wait for keypress  */
        if(wactiv(w2)) error_routine();         /*  activate 2nd window  */
        wputs("there");
        waitkey();                              /*  wait for keypress  */
        wclose();                               /*  close 2nd window  */
        waitkey();                              /*  wait for keypress  */
        wclose();                               /*  close 1st window  */

















                                      5    


Using TCXL's Expanded Memory Specification (EMS) Functions.


    TCXL contains several functions for simple management of expanded memory.
All of TCXL's EMS functions are prefixed with 'ems'.  For those not familiar
with expanded memory, I will briefly explain it.

    The 8088 microprocessor is only able to address 1 Megabyte of memory.  When
applications started needing more memory, Lotus, Intel, and Microsoft developed
the Expanded Memory Specification.  This specification allows access to more
than 1 Megabyte of memory by mapping 16K 'windows' of memory on an expanded
memory board in and out of an unused area of DOS memory.  The Expanded Memory
Manager (EMM) is a software driver that controls the mapping.

    Physical pages are 16K blocks of memory which are located in an unused area
of DOS memory.  There are typically 4 physical pages comprising a 64K
contiguous area of mappable DOS memory.  The EMS page frame base address points
to the beginning of the first physical page. Logical pages are 16K blocks of
memory on the expanded memory board.  There can be as many logical pages as the
expanded memory board has, up to 8 Megabytes.

    Every program that uses expanded memory must do the following:

        1.  determine if the EMM device driver is loaded
        2.  determine if there are enough free pages for its application
        3.  allocate pages of expanded memory
        4.  find out what the EMS page frame base address is
        5.  map logical pages onto physical pages
        6.  deallocate pages when finished with them

    Here's an example of using TCXL's EMS functions to perform these
procedures:

        int handle1,handle2;
        char buf[14];
        if(!emsexist()) {                   /* check for the EMM driver      */
            printf("EMM not loaded\n");
            exit(1);
        }
        handle1=emsalloc(2);                /* request 2 pages of EMS memory */
        handle2=emsalloc(2);                /* request 2 more pages          */
        if((!emsh1)||(!emsh2)) {            /* test for allocation error     */
            printf("EMS allocation error\n");
            exit(1);
        }
        emsmap(handle1,0,0);                /* map logical page 0 of handle 1
                                               to physical page 0            */
        emswrite("Hello, world",0,13);      /* write a string at offset 0,
                                               automatically determines what
                                               the page frame address is     */
        emsmap(emsh2,0,0);                  /* map logical page 0 of handle 2
                                               to physical page 0            */
        emswrite("How are you?",0,13);      /* write a string at offset 0    */
        emsmap(handle1,0,0);                /* map logical page 0 of handle 1
                                               to physical page 0            */


                                      6    
        emsread(buf,0,13);                  /* read 13 bytes from offset 0
                                               into buffer                   */
        printf("buf = %s\n",buf);           /* display buffer contents       */
        emsmap(handle2,0,0);                /* map logical page 0 of handle 2
                                               to physical page 0            */
        emsread(buf,0,13);                  /* read 13 bytes from offset 0
                                               into buffer                   */
        printf("buf = %s\n",buf);           /* display buffer contents       */
        emsdealloc(handle2);                /* deallocate pages belonging to
                                               handle 2                      */
        emsdealloc(handle1);                /* deallocate pages belonging to
                                               handle 1                      */