home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / gio-201.zip / GIO2.DOC < prev    next >
Text File  |  1994-07-06  |  49KB  |  1,744 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.         Gern's 32-bit Multi-Thread Async I/O Routines for OS/2 2.0 (GIO)
  17.  
  18.                                 Release 2.01
  19.  
  20.          Copyright (c) 1992-1994 by John Morris   All Rights Reserved
  21.  
  22.                   OS/2 is a trademark of the IBM corporation.
  23.  
  24.  
  25.  
  26.     First, some background. What's a Gern?  Well Gern is the 486-66 that
  27.   I do most of my programming on. The name Gern comes from a Steve Martin
  28.   comedy album from the late 70's.. Learn with Gern.. Ya gotta love that
  29.   guy!  Gern's I/O routines then turned into 'GIO'.
  30.  
  31.     When I started using a beta version of OS/2 2.0 I became fascinated
  32.   with the prospect of creating 32-bit programs.  I went and bought the
  33.   Watcom C9.0/386 compiler..  Unfortunately this was some months before
  34.   I was able to obtain the official GA toolkit.  Meanwhile I wanted to
  35.   get some IO routines written so I could start porting over some of the
  36.   doors I had written to OS/2.  I started GIO using 16-bit MS C6 compiler.
  37.   I got it running pretty well with some mini comm applications I wrote
  38.   to test it.  When I finally receive the GA toolkit I ported it over to
  39.   C9.0, and was amazed at how many of the functions calls had changed..
  40.   whew.. the port took a while longer than I had expected.
  41.  
  42.     What GIO is intended to do is take some of the tedious programming out
  43.   of the equation. Using GIO you don't have to deal with file handles,
  44.   or terminally confusing calls to DosDevIOCtl.  You just tell GIO what
  45.   you need it to do.
  46.  
  47.     You need to have some experience with programming for OS/2, and you
  48.   might also get the OS/2 Physical Device Driver Reference for more
  49.   information on the data structures used in the asynchronous I/O
  50.   department.   A copy of the IBM OS/2 toolkit is a must also.  It is
  51.   a very good source of imformation! Get It!
  52.  
  53.     At this point (late Mar. 94) GIO is not completed.. it may never be!
  54.   It may need more added functions, and/or more thorough docs, though I
  55.   hope I explained the functions well enough.  What I am looking for is
  56.   feedback as to what needs to be added, or changed. If you want more
  57.   functions, ASK!
  58.   
  59.   Changes To GIO 2.0
  60.  
  61.     I changed the concept of GIO between version 1.00, and 2.00.  GIO
  62.   1.00 was a set of com routines which featured input and output ring buffers
  63.   with each ring buffer on a separate thread.  GIO 1.00 could only be used
  64.   on one com port per process.
  65.  
  66.     GIO 2.00 eliminates the threads on the input and output ring buffers.  In
  67.   fact GIO 2.00 does not use ring buffers! When it comes down to it, the OS/2
  68.   comm device driver (ie. COM.SYS, or Ray Gwinn's SIO.SYS) have their own
  69.   ring buffers right?  Why have TWO ring buffers for input, and two for
  70.   output?  In my humble opinion, that is redundant, and not multi-tasking
  71.   friendly. So in that way GIO 2.00 is no longer multi-threaded. This is not
  72.   as bad as it may sound.
  73.  
  74.     GIO 2.00 now has a handle based API. This allows it to be used in multi-
  75.   threaded programs. In fact, one process can open any number of com ports
  76.   using GIO 2.00.  The down side to a handle based API is the fact that the
  77.   entire API changed!  The 'com port handle' must be passed to every function, 
  78.   so each call has changed.
  79.  
  80.     GIO 2.00 now does named pipes.  You can tell GIO to act as a named pipe
  81.   server, or named pipe client. It will do this almost transparently to your
  82.   program, so you can use the same logic in your com program for operating on
  83.   com ports, and named pipes. You just change the com port name, and a flag
  84.   when opening the port.
  85.  
  86.     GIO 2.00 also has several new functions. More on those in the following
  87.   documentation. GIO's timers are now based on thousandths of a second rather
  88.   than hundredths of a second.
  89.  
  90.  
  91.   !!!!! SHAREWARE !!!!!
  92.  
  93.   GIO 2.00 is distributed under the shareware concept! You are highly
  94.   encouraged to copy and share GIO with others as long as it is copied
  95.   in its entirety with no changes!
  96.  
  97.   If you use GIO in your program(s) please send $25 to the address below!
  98.   (see REGISTER.DOC)
  99.  
  100.   Your help will ensure future versions of GIO.
  101.  
  102.   You can reach me through the Fidonet at 1:213/760 or 761.  RBBSNet at
  103.   8:919/1 or 2.  But it is easiest to reach me via my BBS or voice phone:
  104.  
  105. John Morris
  106. 1718 Woodhaven Ln.
  107. Sparks, NV 89434-0731
  108.  
  109. The Abandoned Land
  110. 702.359.1138 V32
  111. 702.359.0629 HST
  112.  
  113. 702.359.1303 Voice  Weekday Days, or Weekends.. I work evenings.
  114.  
  115. Your feedback will be greatly appreciated.
  116.  
  117.  
  118.   Hints on using GIO.
  119.  
  120.     Copy GIO2.DLL to your \OS2\DLL directory.  Put GIO2.LIB in the path
  121.   to your library files.
  122.  
  123.   Programming.
  124.  
  125.     To start, call ComOpen first. Even if you are passing it the
  126.   file handle of an already opened com port, GIO needs to set up its own
  127.   internal buffers, and variables.
  128.  
  129.     If you wish to open a named pipe, remember that named pipe filenames
  130.   ALWAYS begin with \PIPE\   A valid pipe name would be:  \PIPE\MyPipeName
  131.   And then set the appropriate flag when calling ComOpen, either
  132.   ISPIPESERVER or ISPIPECLIENT.  All of the modem based 'Comxxx' functions
  133.   will return without processing in named pipe mode. The only exception is
  134.   ComGetDCD. ComGetDCD can be used to determine if a client has opened and
  135.   connected to the servers named pipe. (nearly the same concept as looking
  136.   for 'Data Carrier Detect' with a modem, so I put it in the same function)
  137.   Also, ComGetDCD will let you know when the pipe connection has been cut.
  138.     
  139.   GIO 2.01 automagically detects whether a passed file handle is a com device
  140.   oe named pipe. Also fixed a thing or two in the docs here.
  141.  
  142.   Link your object files with GIO2.LIB.
  143.  
  144.  
  145.   See the two example programs for more information.
  146.  
  147.  
  148.   #include <gio2.h>
  149.  
  150.   APIRET EXPENTRY ComOpen(PSZ    PortName,   HFILE  PassedHandle,
  151.                           ULONG  BPSRate,    BYTE   Parity,
  152.                           SHORT  DataBits,   SHORT  StopBits,
  153.                           ULONG  Flags,   PHCOMINFO phComInfo)
  154.  
  155.   ComOpen opens a com port, sets the BPS rate, line control, allocates
  156.   input and output buffers, and starts the threads that control the buffers.
  157.  
  158.   PARAMETERS
  159.     PortName (PSZ) - input
  160.         This is the name of the com port you wish to open. It is not required
  161.         if you pass a file handle to ComOpen. If you wish to open a named pipe,
  162.         PortName must start with  \PIPE\   Put your own filename after \PIPE\
  163.  
  164.     PassedHandle (HFILE) - input
  165.  
  166.         The handle of a currently open com port. If GIO is given a valid
  167.         handle, it will not attempt to use 'DosOpen' to open the port.
  168.         Use this if the program will be inheritting an already open port.
  169.         A value of '0' will cause GIO to use 'DosOpen' to open the port.
  170.  
  171.     BPSRate (ULONG) - input
  172.  
  173.         This is the BPS rate you wish to open the port at. Valid rates are
  174.         10 - 345600.
  175.  
  176.     Parity (BYTE) - input
  177.  
  178.         Determines if a parity bit should exist. The values of this field
  179.         may be as folows:
  180.  
  181.         Value   Definition
  182.         -----   ----------
  183.  
  184.         'O'     Odd parity
  185.  
  186.         'E'     Even Parity
  187.  
  188.         'M'     Mark Parity (parity bit always 1)
  189.  
  190.         'S'     Space Parity (parity bit always 0)
  191.  
  192.         'N'     No Parity
  193.  
  194.     DataBits (SHORT) - input
  195.  
  196.         The number of bits contained in each character transmitted, or
  197.         received by way of the communications port. Valid values are:
  198.  
  199.         Value   Definition
  200.         -----   ----------
  201.  
  202.         5       5 data bits
  203.         6       6 data bits
  204.         7       7 data bits
  205.         8       8 data bits
  206.  
  207.     StopBits (SHORT) - input
  208.  
  209.         The number of stop bits associated with each character transmitted,
  210.         or received by way of the communications port. Valid values are:
  211.  
  212.         Value   Definition
  213.         -----   ----------
  214.  
  215.         0       This sets default stop bits. For a setting of 5 data bits,
  216.                 The default is 1.5 stop bits. For 6, 7,  or 8 data bits,
  217.                 the default is 1 stop bit.
  218.         1       1 stop bit
  219.         2       2 stop bits
  220.  
  221.     OpenFlags (ULONG) - input
  222.  
  223.         LEAVEPORTOPEN -
  224.         If an error occurs while opening the port, this flag will tell
  225.         GIO whether or not to use 'DosClose' to close the com port. Using
  226.         DosClose will cause the carrier to be dropped, and if you don't
  227.         want this to happen, then turn this switch on.
  228.  
  229.         OPENPORTSHARED -
  230.         Opens the port in 'OPEN_SHARE_DENYNONE' mode. If this bit it not set,
  231.         then the port is opened using 'OPEN_SHARE_DENYREADWRITE' mode.
  232.  
  233.         OPENWRITETHROUGH -
  234.         When this flag is set, the open mode flag 'OPEN_WRITE_THROUGH' is used
  235.         when opening the port.
  236.  
  237.         ISPIPESERVER -
  238.         Tells GIO to use the 'PortName' as the name of a named pipe, and
  239.         to create that named pipe.
  240.  
  241.         ISPIPECLIENT -
  242.         Tells GIO to treat the 'PortName' as a named pipe, and opens it
  243.         with 'DosOpen'.
  244.  
  245.      phComInfo (PHCOMINFO) - output
  246.  
  247.         On return this is the handle of the open com port. It will be used
  248.         by every GIO function.
  249.  
  250.  
  251.   RETURNS
  252.     Return code.
  253.  
  254.     ComOpen returns the following values:
  255.  
  256.     0           No Errors
  257.     1           ERROR_INVALID_FUNCTION
  258.     6           ERROR_INVALID_HANDLE
  259.     31          ERROR_GEN_FAILURE
  260.     87          ERROR_INVALID_PARAMETER
  261.     111         ERROR_BUFFER_OVERFLOW
  262.     115         ERROR_PROTECTION_VIOLATION
  263.     117         ERROR_INVALID_CATEGORY
  264.     119         ERROR_BAD_DRIVER_LEVEL
  265.     163         ERROR_UNCERTAIN_MEDIA
  266.     165         ERROR_MONITORS_NOT_SUPPORTED
  267.  
  268.     0xFF00 + 1  COMERR_PORT_NOT_OPEN
  269.     0xFF00 + 2  COMERR_INVALID_PORT_NAME
  270.     0xFF00 + 4  COMERR_NO_HCOMINFO
  271.     0xFF00 + 5  COMERR_OPENING_PORT
  272.     0xFF00 + 6  COMERR_SETTING_BPS_RATE
  273.     0xFF00 + 7  COMERR_SETTING_LINE_CONTROL
  274.  
  275.     0xFF00 + 8  COMERR_CARRIER_DROPPED
  276.     0xFF00 + 9  COMERR_NO_CHAR_WAITING
  277.     0xFF00 + 10 COMERR_TIMED_CHAR_NOT_RECIEVED
  278.  
  279.  
  280.   REMARKS
  281.     ComOpen is used to open a com port, set BPS rate, and line control.
  282.  
  283.     It can accept a file handle of an already open port, and simply use
  284.     that port, its current BPS rate, and line control settings. All GIO
  285.     will do in this case is allocate its own input and output buffers,
  286.     start the threads, and return.
  287.  
  288.     If you wish to keep GIO from using 'DosClose' when shutting down
  289.     (in 'ComOpen' shutting down always means an error) then set the
  290.     'LEAVEPORTOPEN' flag in 'OpenFlags' to TRUE. 'DosClose' will usually
  291.     drop the carrier (if one is present), and the 'LEAVEPORTOPEN' switch
  292.     is used to control the dropping of the carrier.
  293.  
  294.     To allow sharing of the com port, use the 'OPENPORTSHARED' flag.
  295.  
  296.     ComOpen uses the Extended Set Bit Rate function found in OS/2 2.x.
  297.     This allows BPS rates of up to 345600!  Using the extended com port
  298.     functions is not fully implemented in GIO, yet. You need DMA com port
  299.     hardware (found on some PS/2's) to use BPS rates above 57600 reliably.
  300.     On normal com port hardware the upper BPS limit will be 57600.
  301.  
  302.     You can also tell GIO to use non-standard port names. GIO will use 
  303.     any name you pass not just the regular "COM + PortNumber" combination. 
  304.     An example, Digiboards allow you to set the name of each port.
  305.     Lets say the first port is 'DIGI1'  You pass 'DIGI1' as the 'PortName'. 
  306.  
  307.   EXAMPLE CODE
  308.     This example shows a simple call to open COM1 at 19200, No Parity,
  309.     8 data bits, and 1 stop bit.
  310.  
  311.         APIRET ReturnCode;
  312.         HCOMINFO hComInfo;
  313.  
  314.         ReturnCode = ComOpen("COM1", 0, 19200, 'N', 8, 1, 0, &hComInfo);
  315.  
  316.         if (ReturnCode)
  317.         {
  318.             printf("Error (%lu) opening COM port\n", ReturnCode);
  319.  
  320.             exit (1);
  321.         }
  322.  
  323.     This example shows a simple to open DIGI2 as the com port at 38400,
  324.     Even Parity, 7 data bits, and 1 stop bit.
  325.  
  326.         APIRET ReturnCode;
  327.         HCOMINFO hComInfo;
  328.  
  329.         ReturnCode = ComOpen("DIGI2", 0, 38400, 'E', 7, 1, 0, &hComInfo);
  330.  
  331.         if (ReturnCode)
  332.         {
  333.             printf("Error (%lu) opening COM port\n", ReturnCode);
  334.  
  335.             exit (1);
  336.         }
  337.  
  338.  
  339.   #include <gio2.h>
  340.  
  341.   APIRET EXPENTRY ComClose(HCOMINFO hComInfo)
  342.  
  343.   ComClose shuts down a com port opened using ComOpen.
  344.  
  345.   PARAMETERS
  346.     hComInfo (HCOMINFO) - input
  347.  
  348.     Handle to the com port you wish to close.  If you told 'ComOpen' to
  349.     'LEAVEPORTOPEN' then ComClose will simply clean up and exit without
  350.     calling DosClose. (calling DosClose usually drops carrier)
  351.  
  352.   RETURNS
  353.     Always returns '0'.
  354.  
  355.   REMARKS
  356.     ComClose frees the memory used by the GIO, and optionally uses
  357.     'DosClose' to close the port.
  358.  
  359.   EXAMPLE CODE
  360.     This example shows a simple call to open COM1 at 38400, Even Parity,
  361.     7 data bits, and 1 stop bit. Then immediately closes the port.
  362.  
  363.         APIRET ReturnCode;
  364.         HCOMINFO hComInfo;
  365.  
  366.         ReturnCode = ComOpen("COM1", 0, 19200, 'E', 7, 1, 0, &hComInfo);
  367.  
  368.         if (ReturnCode)
  369.         {
  370.             printf("Error (%lu) opening com port\n", ReturnCode);
  371.  
  372.             exit (1);
  373.         }
  374.  
  375.         ComClose(hComInfo);
  376.  
  377.   #include <gio2.h>
  378.  
  379.   APIRET EXPENTRY ComSetBPS(HCOMINFO hComInfo, ULONG BPSRate)
  380.  
  381.   ComSetBPS sets the BPS rate for the port just opened using ComOpen.
  382.  
  383.   PARAMETERS
  384.      hComInfo (HCOMINFO) - input
  385.      
  386.       Handle of the com port.
  387.  
  388.      BPSRate (ULONG)  - input
  389.  
  390.       BPS rate to set the com port at.
  391.  
  392.   RETURNS
  393.     Return code.
  394.  
  395.     ComSetBPS returns the following values:
  396.  
  397.     0           No Errors
  398.     31          ERROR_GEN_FAILURE
  399.  
  400.     0xFF00 + 1  COMERR_PORT_NOT_OPEN
  401.  
  402.   REMARKS
  403.     ComSetBPS uses the set extended bit rate option of the DosDevIOCtl
  404.     function. Normally ComOpen sets this for you, so you do not need to
  405.     use this function.
  406.  
  407.     If you do not receive a general failure error, the BPS rate was set as
  408.     defined.
  409.  
  410.     Returns without action in named pipe mode.
  411.  
  412.   EXAMPLE CODE
  413.     This examples changes the BPS rate to 19200.
  414.  
  415.         APIRET ReturnCode;
  416.         HCOMINFO hComInfo;
  417.  
  418.         ReturnCode = ComSetBPS(hComInfo, 19200);
  419.  
  420.         if (ReturnCode)
  421.         {
  422.             printf("Error (%lu) setting BPS rate\n", ReturnCode);
  423.  
  424.             exit (1);
  425.         }
  426.  
  427.   #include <gio2.h>
  428.  
  429.   APIRET EXPENTRY ComSetLineControl(HCOMINFO hComInfo, BYTE Parity, 
  430.                                     SHORT DataBits, SHORT StopBits)
  431.  
  432.   ComSetLineControl is used to set the Parity, Data Bits, and Stop Bits
  433.   of the current open port.
  434.  
  435.   PARAMETERS
  436.      hComInfo (HCOMINFO) - input
  437.      
  438.       Handle of the com port.
  439.  
  440.     Parity (BYTE) - input
  441.  
  442.         Determines if a parity bit should exist. The values of this field
  443.         may be as folows:
  444.  
  445.         Value   Definition
  446.         -----   ----------
  447.  
  448.         'O'     Odd parity
  449.  
  450.         'E'     Even Parity
  451.  
  452.         'M'     Mark Parity (parity bit always 1)
  453.  
  454.         'S'     Space Parity (parity bit always 0)
  455.  
  456.         'N'     No Parity
  457.  
  458.     DataBits (SHORT) - input
  459.  
  460.         The number of bits contained in each character transmitted, or
  461.         received by way of the communications port. Valid values are:
  462.  
  463.         Value   Definition
  464.         -----   ----------
  465.  
  466.         5       5 data bits
  467.         6       6 data bits
  468.         7       7 data bits
  469.         8       8 data bits
  470.  
  471.     StopBits (SHORT) - input
  472.  
  473.         The number of stop bits associated with each character transmitted,
  474.         or received by way of the communications port. Valid values are:
  475.  
  476.         Value   Definition
  477.         -----   ----------
  478.  
  479.         0       This sets default stop bits. For a setting of 5 data bits,
  480.                 The default is 1.5 stop bits. For 6, 7,  or 8 data bits,
  481.                 the default is 1 stop bit.
  482.         1       1 stop bit
  483.         2       2 stop bits
  484.  
  485.   RETURNS
  486.     Return code.
  487.  
  488.     ComSetLineControl returns the following values:
  489.  
  490.     0           No Errors
  491.     31          ERROR_GEN_FAILURE
  492.  
  493.     0xFF00 + 1  COMERR_PORT_NOT_OPEN
  494.  
  495.   REMARKS
  496.     ComSetLineControl is set when you used ComOpen, so in most cases you
  497.     will not need to use this function.
  498.  
  499.     If you do not receive a general failure error, you can assume that the
  500.     line control was set as defined.
  501.  
  502.     Returns without action in named pipe mode.
  503.  
  504.   EXAMPLE CODE
  505.     This examples changes the line characteristics to Even Parity, 7 Data
  506.     Bits, and 1 Stop Bit.
  507.  
  508.         APIRET ReturnCode;
  509.  
  510.         ReturnCode = ComSetLineControl('E', 7, 1);
  511.  
  512.         if (ReturnCode)
  513.         {
  514.             printf("Error (%lu) setting line controls\n", ReturnCode);
  515.  
  516.             exit (1);
  517.         }
  518.  
  519.   #include <gio2.h>
  520.  
  521.   APIRET EXPENTRY ComSetFlowControl(HCOMINFO hComInfo)
  522.  
  523.   ComSetFlowControl is used to turn on hardware handshaking, and
  524.   hardware timeouts.
  525.  
  526.   PARAMETERS
  527.      hComInfo (HCOMINFO) - input
  528.      
  529.       Handle of the com port.
  530.  
  531.   RETURNS
  532.     Return Code.
  533.  
  534.     ComSetFlowControl returns the following values:
  535.  
  536.     0           No Errors
  537.     31          ERROR_GEN_FAILURE
  538.  
  539.   REMARKS
  540.     ComSetLineControl turns on RTS/CTS hardware flow control, and also
  541.     set hardware transmit and receive timeouts. It also enables DTR
  542.     control. Flow control is also set by ComOpen, so you may not have
  543.     to use this function.
  544.  
  545.     If you do not receive a general failure error, you can assume that flow
  546.     control was set.
  547.  
  548.     Returns without action in named pipe mode.
  549.  
  550.   EXAMPLE CODE
  551.     This examples turns on RTS/CTS hardware flow control.
  552.  
  553.         APIRET ReturnCode;
  554.         HCOMINFO hComInfo;
  555.  
  556.         ReturnCode = ComSetFlowControl(hComInfo);
  557.  
  558.         if (ReturnCode)
  559.         {
  560.             printf("Error (%lu) setting flow controls\n", ReturnCode);
  561.  
  562.             exit (1);
  563.         }
  564.  
  565.   #include <gio2.h>
  566.  
  567.   APIRET EXPENTRY ComSetDTR(HCOMINFO hComInfo, SHORT DTROn)
  568.  
  569.   ComSetDTR is used to turn the DTR signal on and off.
  570.  
  571.   PARAMETERS
  572.      hComInfo (HCOMINFO) - input
  573.      
  574.       Handle of the com port.
  575.  
  576.     DTROn (SHORT) - input
  577.  
  578.       If DTROn is TRUE, then the DTR signal is raised. If FALSE, then
  579.       the DTR signal is lowered.
  580.  
  581.   RETURNS
  582.     Return Code.
  583.  
  584.     ComSetDTR returns the following values:
  585.  
  586.     0           No Errors
  587.     31          ERROR_GEN_FAILURE
  588.  
  589.   REMARKS
  590.     Toggling the DTR line is usually used to drop carrier and/or reset
  591.     the modem. The DTR is lowered for a couple of seconds, then raised
  592.     in order for the modem to receive commands.
  593.  
  594.     If you do not receive a general failure error, you can assume the DTR
  595.     signal was changed.
  596.  
  597.     Returns without action in named pipe mode.
  598.  
  599.   EXAMPLE CODE
  600.     This examples drops the DTR line for 3 seconds, then raises it.
  601.  
  602.         APIRET ReturnCode;
  603.         HCOMINFO hComInfo;
  604.  
  605.         ReturnCode = ComSetDTR(hComInfo, FALSE);
  606.  
  607.         DosSleep(3000);
  608.  
  609.         ReturnCode = ComSetDTR(hComInfo, TRUE);
  610.  
  611.   #include <gio2.h>
  612.  
  613.   BOOL EXPENTRY ComGetDCD(HCOMINFO hComInfo)
  614.  
  615.   ComGetDCD is used to check for a carrier signal, or a Named Pipe connection.
  616.  
  617.   PARAMETERS
  618.      hComInfo (HCOMINFO) - input
  619.      
  620.       Handle of the com port.
  621.  
  622.   RETURNS
  623.     TRUE  if a carrier signal is detected.
  624.     FALSE is no carrier signal is detected.
  625.  
  626.   REMARKS
  627.     ComGetDCD is usually used to see if a user has dropped the carrier.
  628.  
  629.     I consider ComGetDCD a 'low level' function. Why? Because in the
  630.     real world you should first determine the carrier has been dropped,
  631.     wait a couple of seconds, and then check again. If the carrier is
  632.     not there the second time, then you can safely assume the connection
  633.     is gone.
  634.  
  635.     ComGetDCD will also determine whether or not a Named Pipe connection,
  636.     or disconnection has taken place!  When creating a named pipe server
  637.     you might want to loop around a call to ComGetDCD until TRUE, which
  638.     happens when somebody connects to your named pipe.
  639.  
  640.     When you lose a named pipe connection, you should call ComDisConnect
  641.     to kill the connection (for OS/2) then call ComConnect to again 
  642.     'listen' for the next connection.
  643.  
  644.   EXAMPLE CODE
  645.     This examples checks to see if a carrier is present.
  646.  
  647.         APIRET ReturnCode;
  648.         HCOMINFO hComInfo;
  649.  
  650.         ReturnCode = ComGetDCD(hComInfo);
  651.  
  652.         if (! ReturnCode)
  653.             printf("User has dropped carrier!\n");
  654.  
  655.   #include <gio2.h>
  656.  
  657.   BOOL EXPENTRY ComGetCTS(HCOMINFO hComInfo)
  658.  
  659.   ComReportCTS reports the status of the CTS line.
  660.  
  661.   PARAMETERS
  662.      hComInfo (HCOMINFO) - input
  663.      
  664.       Handle of the com port.
  665.  
  666.   RETURNS
  667.     TRUE  if CTS line is raised.
  668.     FALSE if CTS line is lowered.
  669.  
  670.   REMARKS
  671.     The CTS line is usually used to determine if the remote users modem
  672.     is ready to receive characters. If the other modem is not ready to
  673.     receive characters the CTS line goes low.
  674.  
  675.     Always returns TRUE in named pipe mode.
  676.  
  677.   EXAMPLE CODE
  678.     This examples checks to see if it is okay to send characters to our
  679.     modem.
  680.  
  681.         APIRET ReturnCode;
  682.         HCOMINFO hComInfo;
  683.  
  684.         ReturnCode = ComGetCTS(hComInfo);
  685.  
  686.         if (ReturnCode)
  687.             printf("It's okay to send chars! The CTS line is high!\n");
  688.  
  689.   #include <gio2.h>
  690.  
  691.   APIRET EXPENTRY ComXONEnable(HCOMINFO hComInfo)
  692.  
  693.   ComXONEnable is used to enable XON/XOFF style flow control.
  694.  
  695.   PARAMETERS
  696.      hComInfo (HCOMINFO) - input
  697.      
  698.       Handle of the com port.
  699.  
  700.   RETURNS
  701.     0           No Errors
  702.  
  703.   REMARKS
  704.     When XON/XOFF flow control is enabled, the device driver transmits an
  705.     XOFF character when the receive queue is almost full, and an XON when
  706.     the receive queue is about half full.
  707.  
  708.     Returns without action in named pipe mode.
  709.  
  710.   EXAMPLE CODE
  711.     This examples enables XON/XOFF flow control.
  712.  
  713.         APIRET ReturnCode;
  714.         HCOMINFO hComInfo;
  715.  
  716.         ReturnCode = ComXONEnable(hComInfo);
  717.  
  718.   #include <gio2.h>
  719.  
  720.   APIRET EXPENTRY ComXONDisable(HCOMINFO hComInfo)
  721.  
  722.   ComXONDisable is used to disable XON/XOFF flow control.
  723.  
  724.   PARAMETERS
  725.      hComInfo (HCOMINFO) - input
  726.      
  727.       Handle of the com port.
  728.  
  729.   RETURNS
  730.     0           No Errors
  731.  
  732.   REMARKS
  733.     Turns off XON/XOFF flow control if it was enabled with ComXONEnable.
  734.  
  735.     Returns without action in named pipe mode.
  736.  
  737.   EXAMPLE CODE
  738.     This examples disables XON/XOFF flow control.
  739.  
  740.         APIRET ReturnCode;
  741.         HCOMINFO hComInfo
  742.  
  743.         ReturnCode = ComXONDisable(hComInfo);
  744.  
  745.   #include <gio2.h>
  746.  
  747.   APIRET EXPENTRY ComGetDCB(HCOMINFO hComInfo, PDCBINFO DCBInfo)
  748.  
  749.   ComGetDCB returns Device Control Block (DCB) information.
  750.  
  751.   PARAMETERS
  752.      hComInfo (HCOMINFO) - input
  753.      
  754.       Handle of the com port.
  755.  
  756.     DCBInfo (PDCBINFO) - input/output
  757.  
  758.       DCBInfo is a pointer to a DCB structure you have allocated. When the
  759.       function returns, the current DCB information will be in the structure
  760.       pointed to by DCBInfo.
  761.  
  762.   RETURNS
  763.     Return Code.
  764.  
  765.     ComGetDCB returns the following values:
  766.  
  767.     0           No Errors
  768.     31          ERROR_GEN_FAILURE
  769.  
  770.   REMARKS
  771.     You can use ComGetDCB to receive information on the following
  772.     items.
  773.  
  774.     1. Transmit flow control using XON/XOFF.
  775.     2. Receive flow control using XON/XOFF.
  776.     3. Determine what the XON/XOFF characters are.
  777.     4. DTR Control mode.
  778.     5. RTS Control mode.
  779.     6. Transmit handshaking using CTS/DSR/DCD.
  780.     7. Reception of data using DSR.
  781.     8. Error replacement character and processing.
  782.     9. Break replacement character and processing.
  783.    10. Null stripping.
  784.    11. Transmit/Receive timeouts.
  785.    12. Extended hardware buffering info.
  786.  
  787.     See the IBM Physical Device Driver Reference for more information.
  788.  
  789.     ALWAYS call ComGetDCB before calling ComSetDCB. The information
  790.     returned should be modified by the application then set using
  791.     ComSetDCB.
  792.  
  793.     If a general failure is not returned, then valid information will be
  794.     in the DCBInfo structure.
  795.  
  796.     Returns without action in named pipe mode.
  797.  
  798.   EXAMPLE CODE
  799.     This example uses ComGetDCB to get the current DCB parameters, it
  800.     then modifies them and sets the new DCB parameters.
  801.  
  802.         DCBINFO DCBInfo;
  803.         APIRET  ReturnCode;
  804.         HCOMINFO hComInfo;
  805.  
  806.         ComGetDCB(hComInfo, &DCBInfo);
  807.  
  808.         DCBInfo.usWriteTimeout = 1;
  809.  
  810.         DCBInfo.usReadTimeout  = 1;
  811.  
  812.         ReturnCode = ComSetDCB(hComInfo, &DCBInfo);
  813.  
  814.         if (! ReturnCode)
  815.             printf("We set new write & read timeouts!\n");
  816.  
  817.   #include <gio2.h>
  818.  
  819.   APIRET EXPENTRY ComSetDCB(HCOMINFO hComInfo, PDCBINFO DCBInfo)
  820.  
  821.   ComSetDCB sets new Device Control Block (DCB) information.
  822.  
  823.   PARAMETERS
  824.      hComInfo (HCOMINFO) - input
  825.      
  826.       Handle of the com port.
  827.  
  828.     DCBInfo (PDCBINFO) - input
  829.  
  830.       DCBInfo is a pointer to a DCB structure you have allocated and/or
  831.       modified.
  832.  
  833.   RETURNS
  834.     Return Code.
  835.  
  836.     ComSetDCB returns the following values:
  837.  
  838.     0           No Errors
  839.     31          ERROR_GEN_FAILURE
  840.  
  841.   REMARKS
  842.     You can use ComSetDCB to set the following items.
  843.  
  844.     1. Transmit flow control using XON/XOFF.
  845.     2. Receive flow control using XON/XOFF.
  846.     3. Determine what the XON/XOFF characters are.
  847.     4. DTR Control mode.
  848.     5. RTS Control mode.
  849.     6. Transmit handshaking using CTS/DSR/DCD.
  850.     7. Reception of data using DSR.
  851.     8. Error replacement character and processing.
  852.     9. Break replacement character and processing.
  853.    10. Null stripping.
  854.    11. Transmit/Receive timeouts.
  855.    12. Extended hardware buffering info.
  856.  
  857.     See the IBM Physical Device Driver Reference for more information.
  858.  
  859.     ALWAYS call ComGetDCB before calling ComSetDCB. The information
  860.     returned should be modified by the application then set using
  861.     ComSetDCB.
  862.  
  863.     If a general failure is not returned, then you may assume that the
  864.     device driver changed the information.
  865.  
  866.     Returns without action in named pipe mode.
  867.  
  868.   EXAMPLE CODE
  869.     This example uses ComGetDCB to get the current DCB parameters, it
  870.     then modifies them and sets the new DCB parameters.
  871.  
  872.         DCBINFO DCBInfo;
  873.         APIRET  ReturnCode;
  874.         HCOMINFO hComInfo;
  875.  
  876.         ComGetDCB(hComInfo, &DCBInfo);
  877.  
  878.         DCBInfo.fbCtlHndShake  = MODE_CTS_HANDSHAKE | MODE_DTR_CONTROL;
  879.  
  880.         ReturnCode = ComSetDCB(hComInfo, &DCBInfo);
  881.  
  882.         if (! ReturnCode)
  883.             printf("We set new handshake info!\n");
  884.  
  885.   #include <gio2.h>
  886.  
  887.   APIRET EXPENTRY ComTXPurge(HCOMINFO hComInfo)
  888.  
  889.   ComTXPurge is used to flush the output buffers.
  890.  
  891.   PARAMETERS
  892.      hComInfo (HCOMINFO) - input
  893.      
  894.       Handle of the com port.
  895.  
  896.   RETURNS
  897.     0  (No Error)
  898.  
  899.   REMARKS
  900.     Use ComTXPurge if you wish to delete all data which were to
  901.     be transmitted. This function clears the device driver output buffer.
  902.  
  903.   EXAMPLE CODE
  904.     The following short example flushes the output buffer.
  905.  
  906.     HCOMINFO hComInfo;
  907.  
  908.     ComTXPurge(hComInfo);
  909.  
  910.   #include <gio2.h>
  911.  
  912.   APIRET EXPENTRY ComTXCharImm(HCOMINFO hComInfo, BYTE Char)
  913.  
  914.   ComTXCharImm transmits a byte immediately.
  915.  
  916.   PARAMETERS
  917.      hComInfo (HCOMINFO) - input
  918.      
  919.       Handle of the com port.
  920.  
  921.     Char (BYTE) - input
  922.  
  923.       This is the character you wished to be transmitted immediately.
  924.  
  925.   RETURNS
  926.     Return Code.
  927.  
  928.     ComTXCharImm returns the following values:
  929.  
  930.     0           No Errors
  931.     31          ERROR_GEN_FAILURE
  932.  
  933.   REMARKS
  934.     If a general failure is not returned then the character was transmitted.
  935.  
  936.     ComTXCharImm always returns immediately (before the character is actually
  937.     transmitted). If you already have sent one character using this function
  938.     and it has not been sent, then this function will return a general
  939.     failure.
  940.  
  941.     If there are already bytes waiting in the buffer to be transmitted, then
  942.     the byte goes to the 'front' of the buffer, and will be the next
  943.     character transmitted.
  944.  
  945.     The byte is not transmitted if flow control is currently not allowing
  946.     any data to be transmitted.
  947.  
  948.     ComTXCharImm is generally used to send XON and XOFF characters.
  949.  
  950.     Purging the transmit buffers does not purge a byte sent using
  951.     ComTXCharImm.
  952.  
  953.     In named pipe mode, the transmit buffer is purged, and 'Char' is
  954.     sent to the transmit buffer.
  955.  
  956.   EXAMPLE CODE
  957.     This examples sends a Ctrl-Q (a typical XON character) to the port.
  958.  
  959.         HCOMINFO hComInfo;
  960.         APIRET ReturnCode;
  961.         BYTE   XONChar = 17;
  962.  
  963.         ReturnCode = ComTXCharImm(hComInfo, XONChar);
  964.  
  965.   #include <gio2.h>
  966.  
  967.   ULONG EXPENTRY ComTXChar(HCOMINFO hComInfo, BYTE Char, BOOL CheckCD)
  968.  
  969.   ComTXChar sends one byte to the communications port.
  970.  
  971.   PARAMETERS
  972.      hComInfo (HCOMINFO) - input
  973.      
  974.       Handle of the com port.
  975.  
  976.     Char (BYTE) - input
  977.  
  978.       This is the byte to be sent to the communications port.
  979.  
  980.     CheckCD (BOOL) - input
  981.  
  982.       This determines whether or not the function checks for a valid carrier
  983.       signal.
  984.  
  985.   RETURNS
  986.     0  (No Error)
  987.  
  988.   REMARKS
  989.     The char to be transfered is placed in the next available spot in
  990.     the transmit buffers. And is sent out as soon as possible.
  991.  
  992.   EXAMPLE CODE
  993.     This examples sends a character from the keyboard to the com port.
  994.  
  995.         APIRET ReturnCode;
  996.         HCOMINFO hComInfo;
  997.         int    KeyIn;
  998.  
  999.         do
  1000.         {
  1001.             if (kbhit())
  1002.             {
  1003.                 KeyIn = getch();
  1004.  
  1005.                 ReturnCode = ComTXChar(hComInfo, (BYTE) KeyIn);
  1006.             }
  1007.         } while (1);
  1008.  
  1009.   #include <gio2.h>
  1010.  
  1011.   APIRET EXPENTRY ComTXString(HCOMINFO hComInfo, PSZ String, BOOL CheckCD)
  1012.  
  1013.   ComTXString sends a zero-terminated string to the com port.
  1014.  
  1015.   PARAMETERS
  1016.      hComInfo (HCOMINFO) - input
  1017.      
  1018.       Handle of the com port.
  1019.  
  1020.     String (PSZ) - input
  1021.  
  1022.       This is the string to be sent to the comm port. It must be zero-
  1023.       terminated.
  1024.  
  1025.     CheckCD (BOOL) - input
  1026.  
  1027.       This determines whether or not the function checks for a valid carrier
  1028.       signal.
  1029.  
  1030.   RETURNS
  1031.     0           No Errors
  1032.     0xFF00 + 10 COMERR_CARRIER_DROPPED
  1033.  
  1034.   REMARKS
  1035.     If you ask the function not to check for a valid carrier signal, then it
  1036.     will always return 0 (No Errors).
  1037.  
  1038.     The string is placed in the transmit buffers character by character, and
  1039.     these chars are sent out as soon as possible.
  1040.  
  1041.   EXAMPLE CODE
  1042.     This examples sends a string to the com port, and checks for a dropped
  1043.     carrier:
  1044.  
  1045.         APIRET ReturnCode;
  1046.         PSZ    StringOut = "This is a test of the ComTXString function\n\r";
  1047.  
  1048.         ReturnCode = ComTXString(StringOut, TRUE);
  1049.  
  1050.         if (ReturnCode)
  1051.             printf("The remote user dropped the carrier!\n");
  1052.  
  1053.   #include <gio2.h>
  1054.  
  1055.   APIRET EXPENTRY ComTXBlock(HCOMINFO hComInfo, PBYTE Buffer, 
  1056.                              ULONG Size,        BOOL CheckCD)
  1057.  
  1058.   ComTXBlock sends a buffer of a defined length to the com port.
  1059.  
  1060.   PARAMETERS
  1061.      hComInfo (HCOMINFO) - input
  1062.      
  1063.       Handle of the com port.
  1064.  
  1065.     Buffer (PBYTE) - input
  1066.  
  1067.       This is a pointer to the data to be transmitted.
  1068.  
  1069.     Size (ULONG) - input
  1070.  
  1071.       This is the amount of bytes to be transmitted.
  1072.  
  1073.     CheckCD (BOOL) - input
  1074.  
  1075.       This determines whether or not the function checks for a valid carrier
  1076.       signal.
  1077.  
  1078.   RETURNS
  1079.     0           No Errors
  1080.     0xFF00 + 10 COMERR_CARRIER_DROPPED
  1081.  
  1082.   REMARKS
  1083.     If you ask the function not to check for a valid carrier signal, then it
  1084.     will always return 0 (No Errors).
  1085.  
  1086.     The string is placed in the transmit buffers character by character, and
  1087.     these chars are sent out as soon as possible.
  1088.  
  1089.   EXAMPLE CODE
  1090.     This examples sends a buffer of data to the com port, and doesn't check
  1091.     for carrier:
  1092.  
  1093.         APIRET ReturnCode;
  1094.         HCOMINFO hComInfo;
  1095.         BYTE   CharBuffer[128];
  1096.  
  1097.         memset(CharBuffer, 32, 128);  // fill buffer with spaces (' ')
  1098.  
  1099.         ReturnCode = ComTXBlock(hComInfo, CharBuffer, 128, FALSE);
  1100.  
  1101.   #include <gio2.h>
  1102.  
  1103.   BOOL EXPENTRY ComTXEmpty(HCOMINFO hComInfo)
  1104.  
  1105.   ComTXEmpty determines whether or no the transmit buffers are empty.
  1106.  
  1107.   PARAMETERS
  1108.      hComInfo (HCOMINFO) - input
  1109.      
  1110.       Handle of the com port.
  1111.  
  1112.   RETURNS
  1113.     TRUE  is the transmit buffers are empty.
  1114.     FALSE if any bytes remain in the transmit buffers.
  1115.  
  1116.   REMARKS
  1117.     ComTXEmpty is usually used to determine if all bytes have been sent
  1118.     out the com port before a program ends, which will destroy the data
  1119.     in the buffers.
  1120.  
  1121.   EXAMPLE CODE
  1122.     This example waits an indefinate period until the transmit buffers
  1123.     are empty before it exits.
  1124.  
  1125.         HCOMINFO hComInfo;
  1126.  
  1127.         while (! ComTXEmpty(hComInfo));
  1128.  
  1129.         exit();
  1130.  
  1131.   #include <gio2.h>
  1132.  
  1133.   VOID EXPENTRY ComTXFlush(HCOMINFO hComInfo, ULONG MaxWait)
  1134.  
  1135.   ComTXFlush waits until the transmit buffer is empty, or MaxWait
  1136.   milliseconds, whichever comes first.
  1137.  
  1138.   PARAMETERS
  1139.      hComInfo (HCOMINFO) - input
  1140.      
  1141.       Handle of the com port.
  1142.  
  1143.      MaxWait (ULONG) - input
  1144.  
  1145.       Maximum amount of milliseconds to wait for the buffer to empty.
  1146.  
  1147.   RETURNS
  1148.     None.
  1149.  
  1150.   REMARKS
  1151.  
  1152.   EXAMPLE CODE
  1153.     This example waits for a five second period or until the transmit buffers
  1154.     are empty before it exits.
  1155.  
  1156.         HCOMINFO hComInfo;
  1157.  
  1158.         ComTXFlush(hComInfo, 5000);
  1159.  
  1160.         return;
  1161.  
  1162.  
  1163.   #include <gio2.h>
  1164.  
  1165.   APIRET EXPENTRY ComTXCount(HCOMINFO hComInfo, PUSHORT Bytes)
  1166.  
  1167.   ComTXCount returns how many bytes are in the transmit buffer.
  1168.  
  1169.   PARAMETERS
  1170.      hComInfo (HCOMINFO) - input
  1171.      
  1172.       Handle of the com port.
  1173.  
  1174.     Bytes (PUSHORT) - output
  1175.  
  1176.       Bytes is a pointer to a variable which will receive the number
  1177.       of bytes in the transmit buffer.
  1178.  
  1179.   RETURNS
  1180.     0           No Errors
  1181.  
  1182.   REMARKS
  1183.     ComTXCount is usually used to determine if there is enough room in the
  1184.     buffers for the data you are about so send.  This sort of anticipates
  1185.     a condition where flow control takes over. GIO uses a transmit buffer
  1186.     (though not a ring buffer) which is 8K in size.
  1187.  
  1188.   EXAMPLE CODE
  1189.     This example shows how many bytes are in the transmit buffer.
  1190.  
  1191.         USHORT Bytes;
  1192.         HCOMINFO hComInfo;
  1193.  
  1194.         ComTXCount(hComInfo, &Bytes);
  1195.  
  1196.         printf("The transmit buffer has %u bytes in it\n", Bytes);
  1197.  
  1198.  
  1199.   #include <gio2.h>
  1200.  
  1201.   APIRET EXPENTRY ComTXStart(HCOMINFO hComInfo)
  1202.  
  1203.   ComTXStart causes the com port to behave as if it has received an XON
  1204.   character.
  1205.  
  1206.   PARAMETERS
  1207.      hComInfo (HCOMINFO) - input
  1208.      
  1209.       Handle of the com port.
  1210.  
  1211.   RETURNS
  1212.     0           No Errors
  1213.  
  1214.   REMARKS
  1215.     ComTXStart can be used to 'unstick' a transmission that appears to be
  1216.     'stuck'.
  1217.  
  1218.   EXAMPLE CODE
  1219.     This example will attempt to restart transmission.
  1220.  
  1221.         HCOMINFO hComInfo;
  1222.  
  1223.         ComTXStart(hComInfo);
  1224.  
  1225.  
  1226.   #include <gio2.h>
  1227.  
  1228.   APIRET EXPENTRY ComTXStop(HCOMINFO hComInfo)
  1229.  
  1230.   ComTXStop causes the com port to behave as if it has received an XOFF
  1231.   character.
  1232.  
  1233.   PARAMETERS
  1234.      hComInfo (HCOMINFO) - input
  1235.      
  1236.       Handle of the com port.
  1237.  
  1238.   RETURNS
  1239.     0           No Errors
  1240.  
  1241.   REMARKS
  1242.     ComTXStop can be used to stop any current transmission of characters.
  1243.  
  1244.     If you call ComTXStop, you may want to issue a ComTXStart at a later
  1245.     time!
  1246.  
  1247.   EXAMPLE CODE
  1248.     This example will attempt to stop transmission, then restart.
  1249.  
  1250.         HCOMINFO hComInfo;
  1251.  
  1252.         ComTXStop(hComInfo);
  1253.         .
  1254.         .
  1255.         .
  1256.         ComTXStart(hComInfo);
  1257.  
  1258.  
  1259.   #include <gio2.h>
  1260.  
  1261.   APIRET EXPENTRY ComRXPurge(HCOMINFO hComInfo)
  1262.  
  1263.   ComRXPurge is used to purge the input buffers.
  1264.  
  1265.   PARAMETERS
  1266.      hComInfo (HCOMINFO) - input
  1267.      
  1268.       Handle of the com port.
  1269.  
  1270.   RETURNS
  1271.     0           No Errors
  1272.  
  1273.   REMARKS
  1274.     ComRXPurge can be used to purge all input from the remote user.
  1275.  
  1276.   EXAMPLE CODE
  1277.     The following line purges the input buffer.
  1278.  
  1279.         HCOMINFO hComInfo;
  1280.  
  1281.         ComRXPurge(hComInfo);
  1282.  
  1283.         return;
  1284.  
  1285.   #include <gio2.h>
  1286.  
  1287.   APIRET EXPENTRY ComRX(HCOMINFO hComInfo, PSHORT Char, ULONG MaxWait,
  1288.                         BOOL JustPeeking,  BOOL CheckCD)
  1289.  
  1290.   ComRX returns the next available char in the input buffer, if any.
  1291.  
  1292.   PARAMETERS
  1293.      hComInfo (HCOMINFO) - input
  1294.      
  1295.       Handle of the com port.
  1296.  
  1297.     Char (PSHORT) - output
  1298.  
  1299.       The next available character is stored in Char. If no character is
  1300.       waiting Char will be -1.
  1301.  
  1302.     MaxWait (ULONG) - input
  1303.  
  1304.       Maximum time to wait for a character in milliseconds.
  1305.  
  1306.     JustPeeking (BOOL) - input
  1307.  
  1308.       Flag to indicate that we should not remove the character from the
  1309.       buffer.
  1310.  
  1311.     CheckCD (BOOL) - input
  1312.  
  1313.       This determines whether or not the function checks for a valid carrier
  1314.       signal.
  1315.  
  1316.   RETURNS
  1317.     0           No Errors
  1318.     0xFF00 + 11 COMERR_NO_CHAR_WAITING
  1319.  
  1320.   REMARKS
  1321.     ComRX is usually accessed thru one of four different macros (defined
  1322.     in GIO2.H)    They are:
  1323.  
  1324.     ComRXChar(HCOMINFO hComInfo, PSHORT Char, BOOL CheckCD)
  1325.  
  1326.     ComRXCharTimed(HCOMINFO hComInfo, PSHORT Char, BOOL CheckCD, ULONG Delay)
  1327.  
  1328.     ComRXPeek(HCOMINFO hComInfo, PSHORT Char, BOOL CheckCD)
  1329.  
  1330.     ComRXPeekTimed(HCOMINFO hComInfo, PSHORT Char, BOOL CheckCD, ULONG Delay)
  1331.  
  1332.     If 'ComRXxxxx' returns with a 0 return code a valid character is 
  1333.     contained in Char. Otherwise Char is -1, and a error code is returned.
  1334.  
  1335.     If the 'JustPeeking' flag is FALSE, then the character is removed from
  1336.     the buffer.
  1337.  
  1338.   EXAMPLE CODE
  1339.     The follow example uses ComRXCharTimed to receive a character within
  1340.     a five second time period.
  1341.  
  1342.         HCOMINFO hComInfo;
  1343.         SHORT  CharIn;
  1344.         APIRET ReturnCode;
  1345.  
  1346.         ReturnCode = ComRXCharTimed(hComInfo, &CharIn, TRUE, 5000);
  1347.  
  1348.   #include <gio2.h>
  1349.  
  1350.   APIRET EXPENTRY ComRXBlock(HCOMINFO hComInfo, PBYTE Buffer, ULONG BufSize,
  1351.                              ULONG MaxDelay, BOOL CheckCD, 
  1352.                              PULONG BytesRead)
  1353.  
  1354.   ComRXBlock returns a block of characters from the input buffer, if any.
  1355.  
  1356.   PARAMETERS
  1357.      hComInfo (HCOMINFO) - input
  1358.      
  1359.       Handle of the com port.
  1360.  
  1361.     Buffer (PBYTE) - output
  1362.  
  1363.       The address of the buffer which will contain the bytes received.
  1364.  
  1365.     BufSize (ULONG) - input
  1366.  
  1367.       Number of bytes to receive.
  1368.  
  1369.     MaxDelay (ULONG) - input
  1370.  
  1371.       Maximum time to wait for any SINGLE character in milliseconds.
  1372.  
  1373.     CheckCD (BOOL) - input
  1374.  
  1375.       This determines whether or not the function checks for a valid carrier
  1376.       signal.
  1377.  
  1378.     BytesRead (PULONG) - input
  1379.  
  1380.       Pointer to variable which will receive the number of bytes read.
  1381.  
  1382.   RETURNS
  1383.     0           No Errors
  1384.     0xFF00 + 8  COMERR_CARRIER_DROPPED
  1385.     0xFF00 + 12 COMERR_BLOCK_TIMEOUT
  1386.  
  1387.   REMARKS
  1388.     ComRXBlock reads a block of characters from the com port. It will wait
  1389.     MaxDelay seconds for any one character. In other words, if a delay
  1390.     between characters is 'MaxDelay' milliseconds, it will return a timeout.
  1391.     The timeout period begins at the beginning of the call, and/or after
  1392.     the last byte that was received (if any). In this manner, this function
  1393.     may wait longer than 'MaxDelay' milliseconds for a block of characters.
  1394.  
  1395.   EXAMPLE CODE
  1396.     The follow example uses ComRXBlock to receive a 1024 characters within
  1397.     a five second time period.
  1398.  
  1399.         HCOMINFO hComInfo;
  1400.         UCHAR MyBuffer[1024];
  1401.         APIRET ReturnCode;
  1402.         ULONG  BytesRead;
  1403.  
  1404.         ReturnCode = ComRXBlock(hComInfo, MyBuffer, 1024, 
  1405.                                 5000, TRUE, &BytesRead);
  1406.  
  1407.  
  1408.   #include <gio2.h>
  1409.  
  1410.   APIRET EXPENTRY ComRXString(HCOMINFO hComInfo, PBYTE Buffer, ULONG BufSize,
  1411.                               SHORT Terminator, ULONG MaxDelay, BOOL CheckCD)
  1412.  
  1413.   ComRXString returns a string of characters from the input buffer, if any.
  1414.  
  1415.   PARAMETERS
  1416.      hComInfo (HCOMINFO) - input
  1417.      
  1418.       Handle of the com port.
  1419.  
  1420.     Buffer (PBYTE) - output
  1421.  
  1422.       The address of the buffer which will contain the bytes received.
  1423.  
  1424.     BufSize (ULONG) - input
  1425.  
  1426.       Number of bytes to receive.
  1427.  
  1428.     Terminator (SHORT) - input
  1429.  
  1430.       Character which will terminate the input of the string.
  1431.  
  1432.     MaxDelay (ULONG) - input
  1433.  
  1434.       Maximum time to wait for any SINGLE character in milliseconds.
  1435.  
  1436.     CheckCD (BOOL) - input
  1437.  
  1438.       This determines whether or not the function checks for a valid carrier
  1439.       signal.
  1440.  
  1441.   RETURNS
  1442.     0           No Errors
  1443.     0xFF00 + 8  COMERR_CARRIER_DROPPED
  1444.     0xFF00 + 12 COMERR_BLOCK_TIMEOUT
  1445.  
  1446.   REMARKS
  1447.     ComRXString reads in a string from the com port. It will end the input
  1448.     of the string if a character matching 'Terminator' is read. (The
  1449.     termination character is returned as well).  ComRXString will also
  1450.     timeout after 'MaxDelay' milliseconds. It will also return if 'BufSize'
  1451.     bytes are read into 'Buffer'.
  1452.  
  1453.   EXAMPLE CODE
  1454.     The follow example uses ComRXString to receive a string within
  1455.     a sixty second time period.
  1456.  
  1457.         HCOMINFO hComInfo;
  1458.         UCHAR MyBuffer[1024];
  1459.         APIRET ReturnCode;
  1460.         ULONG  BytesRead;
  1461.  
  1462.         ReturnCode = ComRXString(hComInfo, MyBuffer, 200, '\r', 60000, TRUE);
  1463.  
  1464.  
  1465.   #include <gio2.h>
  1466.  
  1467.   BOOL EXPENTRY ComRXEmpty(HCOMINFO hComInfo)
  1468.  
  1469.   ComRXEmpty determines whether or not the receive buffer is empty.
  1470.  
  1471.   PARAMETERS
  1472.      hComInfo (HCOMINFO) - input
  1473.      
  1474.       Handle of the com port.
  1475.  
  1476.   RETURNS
  1477.     TRUE  is the receive buffers are empty.
  1478.     FALSE if any bytes remain in the receive buffers.
  1479.  
  1480.   REMARKS
  1481.     ComRXEmpty is usually used to determine if any bytes have been received
  1482.     and are ready for use.
  1483.  
  1484.   EXAMPLE CODE
  1485.     This example waits an indefinate period until the receive buffer has
  1486.     a character in it.
  1487.  
  1488.         HCOMINFO hComInfo;
  1489.  
  1490.         while (ComRXEmpty(hComInfo));
  1491.         .
  1492.         .
  1493.         .
  1494.  
  1495.   #include <gio2.h>
  1496.  
  1497.   APIRET EXPENTRY ComRXCount(HCOMINFO hComInfo, PUSHORT Bytes)
  1498.  
  1499.   ComRXCount returns how many bytes are in the receive buffer.
  1500.  
  1501.   PARAMETERS
  1502.      hComInfo (HCOMINFO) - input
  1503.      
  1504.       Handle of the com port.
  1505.  
  1506.     Bytes (PUSHORT) - output
  1507.  
  1508.       Bytes is a pointer to a variable which will receive the number
  1509.       of bytes in the receive buffer.
  1510.  
  1511.   RETURNS
  1512.     0           No Errors
  1513.  
  1514.   REMARKS
  1515.     ComRXCount is used to determine how many bytes have been received.
  1516.  
  1517.   EXAMPLE CODE
  1518.     This example shows how many bytes are in the receive buffer.
  1519.  
  1520.         USHORT Bytes;
  1521.         HCOMINFO hComInfo;
  1522.  
  1523.         ComRXCount(hComInfo, &Bytes);
  1524.  
  1525.         printf("The receive buffer has %u bytes in it\n", Bytes);
  1526.  
  1527.  
  1528.   #include <gio2.h>
  1529.  
  1530.   APIRET EXPENTRY ComPause(HCOMINFO hComInfo)
  1531.  
  1532.   ComPause resets GIO's transmit buffer.
  1533.  
  1534.   PARAMETERS
  1535.      hComInfo (HCOMINFO) - input
  1536.      
  1537.       Handle of the com port.
  1538.  
  1539.   RETURNS
  1540.     0           No Errors
  1541.  
  1542.   REMARKS
  1543.     This function resets GIO's transmit buffer. Nothing more.
  1544.  
  1545.   EXAMPLE CODE
  1546.     This code calls ComPause then ComResume.
  1547.  
  1548.         APIRET ReturnCode;
  1549.         HCOMINFO hComInfo;
  1550.  
  1551.         ReturnCode = ComPause(hComInfo);    // stop input and output threads.
  1552.  
  1553.         //
  1554.         // the program might shell out to another com program here.
  1555.         //
  1556.  
  1557.         ReturnCode = ComResume(hComInfo);   // restart input and output threads.
  1558.  
  1559.         //
  1560.         // the program resumes here.
  1561.         //
  1562.  
  1563.   #include <gio2.h>
  1564.  
  1565.   APIRET EXPENTRY ComResume(HCOMINFO hComInfo)
  1566.  
  1567.   ComResume resets GIO's transmit buffer.
  1568.  
  1569.   PARAMETERS
  1570.      hComInfo (HCOMINFO) - input
  1571.      
  1572.       Handle of the com port.
  1573.  
  1574.   RETURNS
  1575.     0           No Errors
  1576.  
  1577.   REMARKS
  1578.     This function resets GIO's transmit buffer. Nothing more.
  1579.  
  1580.   EXAMPLE CODE
  1581.     This code calls ComPause then ComResume.
  1582.  
  1583.         APIRET ReturnCode;
  1584.         HCOMINFO hComInfo;
  1585.  
  1586.         ReturnCode = ComPause(hComInfo);    // stop input and output threads.
  1587.  
  1588.         //
  1589.         // the program might shell out to another com program here.
  1590.         //
  1591.  
  1592.         ReturnCode = ComResume(hComInfo); // restart input and output threads.
  1593.  
  1594.         //
  1595.         // the program resumes here.
  1596.         //
  1597.  
  1598.   #include <gio2.h>
  1599.  
  1600.   APIRET EXPENTRY ComGetHandle(HCOMINFO hComInfo, PULONG Handle)
  1601.  
  1602.   ComGetHandle returns a copy of the com port handle used by GIO.
  1603.  
  1604.   PARAMETERS
  1605.      hComInfo (HCOMINFO) - input
  1606.      
  1607.       Handle of the com port.
  1608.  
  1609.     Handle (PULONG) - output
  1610.  
  1611.       Contains the address of the variable which will contain the copy
  1612.       of file handle used by GIO. This is either an HFILE or HPIPE,
  1613.       depending on the open method.
  1614.  
  1615.   RETURNS
  1616.     0           No Errors
  1617.  
  1618.   REMARKS
  1619.     This function is provided as a convenience only. It will return a copy
  1620.     of the file handle used by GIO for the current com port.  Be very
  1621.     careful what you do with this copy of the handle, as you might cause
  1622.     GIO to malfunction.
  1623.  
  1624.     It should be used to pass on the handle to any child programs which may
  1625.     need access to the com port.
  1626.  
  1627.   EXAMPLE CODE
  1628.     This example retrieves a copy of GIO's file handle.
  1629.  
  1630.         APIRET ReturnCode;
  1631.         HCOMINFO hComInfo;
  1632.         HFILE  ThisIsTheGIOHandle;
  1633.  
  1634.         ReturnCode = ComGetHandle(hComInfo, (PULONG) &ThisIsTheGIOHandle);
  1635.  
  1636.         printf("The file handle in use by GIO is %lu\n", ThisIsTheGIOHandle);
  1637.  
  1638.  
  1639.  
  1640.   #include <gio2.h>
  1641.  
  1642.   VOID EXPENTRY ComBreak(HCOMINFO hComInfo, BOOL BreakOn)
  1643.  
  1644.   ComBreak turns a break signal on or off.
  1645.  
  1646.   PARAMETERS
  1647.      hComInfo (HCOMINFO) - input
  1648.      
  1649.       Handle of the com port.
  1650.  
  1651.      BreakOn (BOOL) - input
  1652.  
  1653.       Determines whether or not to turn the break signal on or off.
  1654.  
  1655.   RETURNS
  1656.     0           No Errors
  1657.  
  1658.   REMARKS
  1659.     ComBreak is used to send a break signal.
  1660.  
  1661.   EXAMPLE CODE
  1662.     This example will send a break signal for 2 seconds.
  1663.  
  1664.         HCOMINFO hComInfo;
  1665.  
  1666.         ComBreak(hComInfo, TRUE);
  1667.  
  1668.         DosSleep(2000);
  1669.  
  1670.         ComBreak(hComInfo, FALSE);
  1671.  
  1672.  
  1673.   #include <gio2.h>
  1674.  
  1675.   APIRET EXPENTRY ComConnect(HCOMINFO hComInfo)
  1676.  
  1677.   ComConnect prepares a named pipe for a client.
  1678.  
  1679.   PARAMETERS
  1680.      hComInfo (HCOMINFO) - input
  1681.      
  1682.       Handle of the com port.
  1683.  
  1684.   RETURNS
  1685.     0           No Errors
  1686.  
  1687.   REMARKS
  1688.     ComConnect is used by a named pipe server to put the named pipe
  1689.     into a listening state.  That is, 'listening' for a named pipe
  1690.     client to open and use the named pipe.
  1691.  
  1692.     ComConnect is called by ComOpen when the named pipe is first 
  1693.     opened. This means the named pipe is waiting for a connection
  1694.     just after it is opened.
  1695.  
  1696.     When the named pipe connection is to be ended on the server side,
  1697.     you must call ComDisConnect, and then call ComConnect to put the
  1698.     named pipe back into listening mode.
  1699.  
  1700.     See DosConnectNPipe for more information.
  1701.  
  1702.   EXAMPLE CODE
  1703.     This example will put a named pipe into a listening state.
  1704.  
  1705.         HCOMINFO hComInfo;
  1706.  
  1707.         ComConnect(hComInfo);
  1708.  
  1709.  
  1710.   #include <gio2.h>
  1711.  
  1712.   APIRET EXPENTRY ComDisConnect(HCOMINFO hComInfo)
  1713.  
  1714.   ComDisConnect acknowledges that a client has closed the named pipe.
  1715.  
  1716.   PARAMETERS
  1717.      hComInfo (HCOMINFO) - input
  1718.      
  1719.       Handle of the com port.
  1720.  
  1721.   RETURNS
  1722.     0           No Errors
  1723.  
  1724.   REMARKS
  1725.     ComDisConnect is used by a named pipe server to acknowledge that
  1726.     the client has closed the named pipe. The server should then call
  1727.     ComConnect to put the named pipe into listening mode if it wishes
  1728.     to connect with another client.
  1729.  
  1730.     ComDisConnect can also be used to force a named pipe closed (even
  1731.     before the client has closed their end of the pipe). The nearest
  1732.     equivalent to ComDisConnect in 'modem terms' would be dropping
  1733.     the DTR to sever the connection.
  1734.  
  1735.     See DosDisConnectNPipe for more information.
  1736.  
  1737.   EXAMPLE CODE
  1738.     This example will put a named pipe into a listening state.
  1739.  
  1740.         HCOMINFO hComInfo;
  1741.  
  1742.         ComConnect(hComInfo);
  1743.  
  1744.