suplmnt.doc

用C++写的RS232串口异步通讯功能模块

         ===============================================================

                          MCOMM SUPPLEMENTAL FUNCTIONS
                  Mike Dumdei, 6 Holly Lane, Texarkana TX 75503

         ===============================================================

         The functions described in this document are non-async related
         functions provided as part of the MCOMM library.  MCOMM is
         first and foremost a serial I/O library, therefore, much more
         effort went into describing the use of the async functions than
         you will find here.  Also, because MCOMM is a serial library,
         most of the supplemental functions are targeted towards commun-
         ications programs.  The video functions correctly handle all
         ANSI sequences commonly used by BBS systems.  They also support
         windowed output, allowing you to limit the area of the screen
         that will be written to.  For example, you can reserve the
         bottom line of the screen for a status line and no writes, ANSI
         clear screen commands, etc., will be allowed to overwrite or
         erase it.

            ANSI sequences supported are:
               CUP - cursor position
               HVP - horizontal, vertical position
               CUU - cursor up
               CUD - cursor down
               CUF - cursor forward
               CUB - cursor backward
               SCP - save cursor position
               RCP - restore cursor position
               ED  - erase display
               EL  - erase line
               SGR - set graphics rendition (colors)
               FF  - form feed, not really ANSI, clears the screen

         Tabs, newlines, carriage returns, line feeds, backspace, the
         bell character, etc. are supported also.  See the 'Global Video
         Variables' section for information on options available for
         handling control characters, scrolling, etc.

         In addition to the video routines, there are also timeout
         functions, crc functions, string functions, a carrier watchdog
         function, and several others.  On the following pages, the
         video functions are listed first followed by the non-video type
         functions.

         Distribution policy:
            These functions are part of the MCOMM async library and may
         not be distributed without the remaining MCOMM files.  No part
         of the registered version may be distributed or used except as
         stated in the license agreement.






         GLOBAL VIDEO VARIABLES:

         v_seg - segment  address of video RAM, set by initvid()
         v_mode - current video mode, set by initvid()
         v_page - current video page, set by initvid()
         v_color - attribute to use when displaying chars, this variable
            is set directly by ANSI sequences that change the displayed
            attribute and can be set from your C program to change the
            current attribute (def = 7)
         v_snow - snow flag, if 1 chars are written to screen during
            vertical retrace, if 0 chars are written without waiting for
            retrace
         v_cga - a CGA video system was detected
         v_bios - BIOS video flag, if 1 screen writes are performed
            using BIOS INT 10, if 0 screen writes are done directly to
            video RAM
         v_wndsz - current window borders, set by SETWND macro
            (def = 0,0,24,79)
         v_btmrgt, v_rgt, v_btm, v_toplft, v_lft, v_top -
            v_wndsz individual components
         vs_wndsz - limits for d_msgat(), d_nchat(), & d_atrbat()
         vs_btmrgt, vs_toplft  - vs_wndsz individual components
         v_scrlm - scroll mode, if 1 then the window is scrolled when
            the cursor would move off the bottom, if 0 the cursor wraps
            back to the top  (def = 1)
         v_cntrlm - control char handling, if 1 then control chars per-
            form control functions, if 0 control chars are displayed as
            graphic characters (def = 1)
         v_textm - text mode, if 1 newlines are translated to CR/LF
            pairs, if 0 newlines are displayed as LFs (def=1)
         v_ansi - ansi mode, if 1 ANSI sequences are recognized, if 0
            ANSI sequences are not recognized (def = 1)
         v_wrel - if 1 cursor location arguments for functions that are
            limited to the current window are relative to the top left
            of the current window, if 0 cursor locations are absolute
            (def = 0)
         vs_wrel - if 1 cursor location arguments for functions that are
            NOT limited to the current window are relative to the top
            left of the current window, if 0 cursor locations are
            absolute (def = 0)
         v_ansiseq - shows that an ANSI sequence is currently in process
            -- an ESC has been received by the display functions but the
            terminating alpha character has not yet been received. (EX:
            \33[0;36m is an ANSI sequence.  'v_ansiseq' is set to some
            positive value when the ESC character is received and stay
            positive until the sequence terminator is received.  When
            the terminator is received, 'v_ansiseq' is set to a negative
            value.  If the next character displayed after the terminator
            is not the start of another ANSI sequence, 'v_ansiseq' is
            reset to 0 after displaying that character.  This variable
            is useful when stripping ANSI sequences from an incoming
            stream of characters or when it is necessary to interrupt an
            inprocess ANSI sequence.
         v_bksp - if 1, backspace is destructive, if 0 backspace is not
            destructive (def = 1)







         HANDLING OF UNSUPPORTED ANSI SEQUENCES:

         When an unsupported ANSI sequence is displayed, the ESC
         character (a small back arrow), will be displayed followed by
         the unrecognized terminating character.  The characters between
         the ESC and unrecognized terminator are not displayed.


         INTERRUPTING INPROCESS ANSI SEQUENCES:

         This section suggests some possible methods for handling the
         situation where an ANSI sequence is in progress and it is nec-
         essary to display characters that are not part of the sequence
         and then resume the sequence.  An example of where this situa-
         tion is a terminal program that is displaying incoming data
         containing ANSI codes and the user of the program presses a key
         that requires screen output in the middle of one of those
         codes:
                Incoming data:    ESC[0;  (beginning of ANSI code)
                User keypress:     F1     (user wants a help screen)
                More incoming:    36m     (completion of ANSI code)

         The ANSI handler in the video library sees this:
                  ESC[0;+----------------+
                        |  Help Screen   |
                        +----------------+36m
         and since it doesn't know what to to with an ANSI code that
         looks like that you see a small back arrow (for unrecognized
         ANSI code), the help screen, and a 36m.

         To avoid this problem, you can do one of three things.  The
         first is you can ignore the local user input until the
         inprocess ANSI sequence is completed.  The v_ansiseq variable
         described previously can be used to test whether or not an ANSI
         sequence is currently in process.  Example:
            if (KBHIT()) {
               while (v_ansiseq && ((ch = rx_timeout(1)) != TIMED_OUT))
                  d_ch(ch);
               proc_keypress();
            }

         The second method is to use the 'd_msgat' function to display
         local strings.  It automatically save the ANSI sequence status,
         and the present cursor position before displaying the passed
         string.  On exit, the current status of any inprocess ANSI
         sequences and the cursor position are restored.  It will also
         place strings outside the current window making it the best
         function for updating the terminal status line and displaying
         local screens and messages.

         The last option is to manually preserve the v_ansiseq variable,
         display local messages, and then manually restore v_ansiseq:
            temp = v_ansiseq, v_ansiseq = 0;
            displayhelp();
            v_ansiseq = temp;






         VIDEO MACROS:

         ---------------------------------------------------------------
         SETWND(top, left, btm, rgt)  -- Set Window Dimensions
         ---------------------------------------------------------------
         This macro is used to set the global variable that defines the
         screen area that will be affected by the majority of the video
         functions.  Initially set to 0,0,24,79.


         ---------------------------------------------------------------
         SETTOPLFT(top, lft), SETBTMRGT(btm, rgt)
         ---------------------------------------------------------------
         Same as above but only sets one corner.


         ---------------------------------------------------------------
         SETsWND(top, left, btm, rgt) -- Set Screen Dimensions
         ---------------------------------------------------------------
         Sets the screen limits for the functions that are allowed to
         write outside the current window.


         ---------------------------------------------------------------
         SETsTOPLFT(top, lft), SETsBTMRGT(btm, rgt)
         ---------------------------------------------------------------
         Same as SETsWND but for one corner only.


         ---------------------------------------------------------------
         SCRBUF(rows, cols)
         ---------------------------------------------------------------
         Returns a value that is the required buffer size for the
         pu_scrnd and fpu_scrnd functions.  It is used like this:

           sbuf = malloc(SCRBUF(25,80));
           if (sbuf != NULL)
              pu_scrnd(0, 0, 25, 80);


         ---------------------------------------------------------------
         d_strnat(row,col,char,attrib,count)
         ---------------------------------------------------------------
         Macro for compatibility with older versions of ANSIDRV.






         VIDEO FUNCTIONS:

         ---------------------------------------------------------------
         initvid -- Initializes Video Variables
         ---------------------------------------------------------------
            int initvid(void);

         Initializes the global video variables, v_seg, v_mode, v_page,
         and v_snow.  You MUST call this function before using any of
         the other video functions.  Calling 'initvid' does not
         automatically cause the linker to pull in the code for the
         remaining ANSI video routines.  Initvid only includes the
         global variables and enough code to initialize those variables.


         ---------------------------------------------------------------
         loc -- Locate the Cursor
         ---------------------------------------------------------------
            void loc(int row, int col);

         Locates the cursor at row, col.  The top left of the screen is
         0,0.  If an attempt is made to locate the cursor outside the
         current window the cursor is placed on the window edge closest
         to the passed location.  Setting the global variable 'v_wrel'
         to a non-zero value will make location 0,0 be the top, left
         corner of the current window.


         ---------------------------------------------------------------
         d_strat -- Display String At Specified Location
         ---------------------------------------------------------------
            void d_strat(int row, int col, char *string);

         This function displays a string at row, col.  The attribute
         used is the current value of the global variable 'v_color'.
         The area where the string can be displayed is limited to the
         current window (set by SETWND).


         ---------------------------------------------------------------
         d_str  -- Display String At Current Location
         ---------------------------------------------------------------
            void d_str(char *string);

         Displays a string at the current cursor position using v_color
         for the attribute.


         ---------------------------------------------------------------
         d_chat -- Display Char At Specified Location
         ---------------------------------------------------------------
            void d_chat(int row, int col, char ch);

         Displays one character at the specified position using v_color
         for the attribute.