home *** CD-ROM | disk | FTP | other *** search
/ High Voltage Shareware / high1.zip / high1 / DIR24 / OTHL_100.ZIP / GIO-100.ZIP / GIO.DOC < prev    next >
Text File  |  1993-05-29  |  42KB  |  1,472 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 1.00
  19.  
  20.          Copyright (c) 1992-1993 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 386-40 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 Sept. 92) 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.
  57.  
  58.     I am currently _not_ running OS/2 on my BBS as I am waiting till I
  59.   complete my 32-bit BBS program, and not until I can port some more
  60.   doors over to OS/2.. but I'm working on it.  I need you folks to help
  61.   me test it. Beat it to death, etc.
  62.  
  63.   You can reach me through the Fidonet at 1:213/760 or 761.  RBBSNet at
  64.   8:919/1 or 2.  But it is easiest to reach me via my BBS or voice phone:
  65.  
  66. John Morris
  67. Tradewars Software
  68.  
  69. The Abandoned Land
  70. 702.359.1138 V32
  71. 702.359.0629 HST
  72.  
  73. 702.359.1303 Voice  Weekday Days, or Weekends.. I work evenings.
  74.  
  75. Your feedback will be greatly appreciated.
  76.  
  77.  
  78.   Hints on using GIO.
  79.  
  80.     Copy GIO.DLL to your \OS2\DLL directory.  Put GIO.LIB in the path
  81.   to your library files.
  82.  
  83.   Programming.
  84.  
  85.     To start, call ComOpen first. Even if you are passing it the
  86.   file handle of an already opened com port, GIO needs to set up its own
  87.   internal buffers, and variables.
  88.  
  89.     If you wish to use GIO's debug mode dialog box, your program must
  90.   be a PM program (creates a message queue, and has a window). You must
  91.   call 'ComSetDebug(TRUE)' before calling ComOpen.  Also, you may call
  92.   'ComSetDebugIdentity' with an identity string so you may distinguish
  93.   between multiple GIO infobox's.
  94.  
  95.     Start up two threads in addition to the main program thread.  Your
  96.   main program thread might be used to simply handle the windows message
  97.   queue, while two comm threads handle the input and output respectively.
  98.  
  99.  
  100.     Link your object files with GIO.LIB.
  101.  
  102.  
  103.     See the two example programs for more information.
  104.  
  105.  
  106.   #include <gio.h>
  107.  
  108.   APIRET EXPENTRY ComOpen(PSZ   PortName,   SHORT  PortNumber,
  109.                           ULONG BPSRate,    BYTE Parity,
  110.                           SHORT  DataBits,  SHORT StopBits,
  111.                           USHORT InBufSize, USHORT OutBufSize,
  112.                           HFILE ValidHandle,ULONG  OpenFLags)
  113.  
  114.   ComOpen opens a com port, sets the BPS rate, line control, allocates
  115.   input and output buffers, and starts the threads that control the buffers.
  116.  
  117.   PARAMETERS
  118.     PortName (PSZ) - input  (added 10/7/92)
  119.         This is the name of the com port you wish to open. Use this to open
  120.         a port which does not used the standard 'COMx' filename.
  121.  
  122.     PortNumber (SHORT) - input
  123.  
  124.         This is the number of the com port you wish to open. For instance
  125.         to open COM1 this variable would be 1.
  126.  
  127.     BPSRate (ULONG) - input
  128.  
  129.         This is the BPS rate you wish to open the port at. Valid rates are
  130.         10 - 345600.
  131.  
  132.     Parity (BYTE) - input
  133.  
  134.         Determines if a parity bit should exist. The values of this field
  135.         may be as folows:
  136.  
  137.         Value   Definition
  138.         -----   ----------
  139.  
  140.         'O'     Odd parity
  141.  
  142.         'E'     Even Parity
  143.  
  144.         'M'     Mark Parity (parity bit always 1)
  145.  
  146.         'S'     Space Parity (parity bit always 0)
  147.  
  148.         'N'     No Parity
  149.  
  150.     DataBits (SHORT) - input
  151.  
  152.         The number of bits contained in each character transmitted, or
  153.         received by way of the communications port. Valid values are:
  154.  
  155.         Value   Definition
  156.         -----   ----------
  157.  
  158.         5       5 data bits
  159.         6       6 data bits
  160.         7       7 data bits
  161.         8       8 data bits
  162.  
  163.     StopBits (SHORT) - input
  164.  
  165.         The number of stop bits associated with each character transmitted,
  166.         or received by way of the communications port. Valid values are:
  167.  
  168.         Value   Definition
  169.         -----   ----------
  170.  
  171.         0       This sets default stop bits. For a setting of 5 data bits,
  172.                 The default is 1.5 stop bits. For 6, 7,  or 8 data bits,
  173.                 the default is 1 stop bit.
  174.         1       1 stop bit
  175.         2       2 stop bits
  176.  
  177.     InBufSize (USHORT) - input
  178.  
  179.         This determines the size of the input buffer GIO should create.
  180.         Valid sizes are 64 to 32000 bytes.
  181.  
  182.     OutBufSize (USHORT) - input
  183.  
  184.         This determines the size of the output buffer GIO should create.
  185.         Valid sizes are 64 to 32000 bytes.
  186.  
  187.     ValidHandle (HFILE) - input
  188.  
  189.         The handle of a currently open com port. If GIO is given a valid
  190.         handle, it will not attempt to use 'DosOpen' to open the port.
  191.         Use this if the program will be inheritting an already open port.
  192.         A value of '0' will cause GIO to use 'DosOpen' to open the port.
  193.  
  194.     OpenFlags (ULONG) - input
  195.  
  196.         LEAVEPORTOPEN -
  197.         If an error occurs while opening the port, this flag will tell
  198.         GIO whether or not to use 'DosClose' to close the com port. Using
  199.         DosClose will cause the carrier to be dropped, and if you don't
  200.         want this to happen, then turn this switch on.
  201.  
  202.         OPENPORTSHARED -
  203.         Opens the port in 'OPEN_SHARE_DENYNONE' mode. If this bit it not set,
  204.         then the port is opened using 'OPEN_SHARE_DENYREADWRITE' mode.
  205.  
  206.         OPENWRITETHROUGH -
  207.         When this flag is set, the open mode flag 'OPEN_WRITE_THROUGH' is used
  208.         when opening the port.
  209.  
  210.   RETURNS
  211.     Return code.
  212.  
  213.     ComOpen returns the following values:
  214.  
  215.     0           No Errors
  216.     1           ERROR_INVALID_FUNCTION
  217.     6           ERROR_INVALID_HANDLE
  218.     31          ERROR_GEN_FAILURE
  219.     87          ERROR_INVALID_PARAMETER
  220.     111         ERROR_BUFFER_OVERFLOW
  221.     115         ERROR_PROTECTION_VIOLATION
  222.     117         ERROR_INVALID_CATEGORY
  223.     119         ERROR_BAD_DRIVER_LEVEL
  224.     163         ERROR_UNCERTAIN_MEDIA
  225.     165         ERROR_MONITORS_NOT_SUPPORTED
  226.  
  227.     0xFF00 + 1  COMERR_PORT_NOT_OPEN
  228.     0xFF00 + 2  COMERR_INVALID_BUFFER_SIZES
  229.     0xFF00 + 3  COMERR_INPUT_BUFFER_ALLOCATION
  230.     0xFF00 + 4  COMERR_OUTPUT_BUFFER_ALLOCATION
  231.     0xFF00 + 5  COMERR_STARTING_INPUT_THREAD
  232.     0xFF00 + 6  COMERR_STARTING_OUTPUT_THREAD
  233.     0xFF00 + 7  COMERR_OPENING_PORT
  234.     0xFF00 + 8  COMERR_SETTING_BPS_RATE
  235.     0xFF00 + 9  COMERR_SETTING_LINE_CONTROL
  236.  
  237.     0xFF00 + 10 COMERR_CARRIER_DROPPED
  238.     0xFF00 + 11 COMERR_NO_CHAR_WAITING
  239.     0xFF00 + 12 COMERR_TIMED_CHAR_NOT_RECIEVED
  240.  
  241.  
  242.   REMARKS
  243.     ComOpen is used to open a com port, set BPS rate, and line control.
  244.     This process also includes starting to 'threads' which control the
  245.     input and output buffers.
  246.  
  247.     It can accept a file handle of an already open port, and simply use
  248.     that port, its current BPS rate, and line control settings. All GIO
  249.     will do in this case is allocate its own input and output buffers,
  250.     start the threads, and return.
  251.  
  252.     If you wish to keep GIO from using 'DosClose' when shutting down
  253.     (in 'ComOpen' shutting down always means an error) then set the
  254.     'LEAVEPORTOPEN' flag in 'OpenFlags' to TRUE. 'DosClose' will usually
  255.     drop the carrier (if one is present), and the 'LEAVEPORTOPEN' switch
  256.     is used to control the dropping of the carrier.
  257.  
  258.     To allow sharing of the com port, use the 'OPENPORTSHARED' flag.
  259.  
  260.     ComOpen uses the Extended Set Bit Rate function found in OS/2 2.0.
  261.     This allows BPS rates of up to 345600!  Using the extended com port
  262.     functions is not fully implemented in GIO, yet. You need DMA com port
  263.     hardware (found on some PS/2's) to use BPS rates above 57600 reliably.
  264.     On normal com port hardware the upper BPS limit will be 57600.
  265.  
  266.     You can also tell GIO to use non-standard port names. If you pass
  267.     a string as a 'PortName' then GIO will use that name instead of
  268.     the regular "COM + PortNumber" combination.  An example, Digiboards
  269.     allow you to set the name of each port. Lets say the first port
  270.     is 'DIGI1'  You pass 'DIGI1' as the 'PortName'. In that case,
  271.     GIO will ignore 'PortNumber'.  If you don't wish to use this feature,
  272.     set PortName to NULL, and GIO will use the regular "COMx" filename.
  273.  
  274.   EXAMPLE CODE
  275.     This example shows a simple call to open COM1 at 19200, No Parity,
  276.     8 data bits, and 1 stop bit.
  277.  
  278.         APIRET ReturnCode;
  279.  
  280.         ReturnCode = ComOpen(NULL, 1, 19200, 'N', 8, 1, 1024, 1024, 0, 0);
  281.  
  282.         if (ReturnCode)
  283.         {
  284.             printf("Error (%lu) opening COM port\n", ReturnCode);
  285.  
  286.             exit (1);
  287.         }
  288.  
  289.     This example shows a simple to open DIGI2 as the com port at 38400,
  290.     Even Parity, 7 data bits, and 1 stop bit.
  291.  
  292.         APIRET ReturnCode;
  293.  
  294.         ReturnCode = ComOpen("DIGI2", 0, 38400, 'E', 7, 1, 1024, 1024, 0, 0);
  295.  
  296.         if (ReturnCode)
  297.         {
  298.             printf("Error (%lu) opening COM port\n", ReturnCode);
  299.  
  300.             exit (1);
  301.         }
  302.  
  303.  
  304.   #include <gio.h>
  305.  
  306.   APIRET EXPENTRY ComClose(BOOL LeavePortOpen)
  307.  
  308.   ComClose shuts down a com port opened using ComOpen.
  309.  
  310.   PARAMETERS
  311.     LeavePortOpen (BOOL) - input
  312.  
  313.         Setting this parameter to TRUE will keep GIO from using 'DosClose'
  314.         when shutting down. 'DosClose' will usually drop the carrier (if
  315.         one is present) and this switch allows you to control whether or
  316.         not the carrier is dropped.
  317.  
  318.  
  319.   RETURNS
  320.     Always returns '0'.
  321.  
  322.  
  323.   REMARKS
  324.     ComClose is used to shut down the input and output buffer control
  325.     threads, frees the memory used by the buffers, and optional uses
  326.     'DosClose' to close the port.
  327.  
  328.   EXAMPLE CODE
  329.     This example shows a simple call to open COM1 at 38400, Even Parity,
  330.     7 data bits, and 1 stop bit. Then immediately closes the port.
  331.  
  332.         APIRET ReturnCode;
  333.  
  334.         ReturnCode = ComOpen(NULL, 1, 19200, 'E', 7, 1, 1024, 1024, 0, FALSE);
  335.  
  336.         if (ReturnCode)
  337.         {
  338.             printf("Error (%lu) opening com port\n", ReturnCode);
  339.  
  340.             exit (1);
  341.         }
  342.  
  343.         ComClose(FALSE);
  344.  
  345.   #include <gio.h>
  346.  
  347.   APIRET EXPENTRY ComSetBPSRate(ULONG BPSRate)
  348.  
  349.   ComSetBPSRate sets the BPS rate for the port just opened using ComOpen.
  350.  
  351.   PARAMETERS
  352.     BPSRate (ULONG)  - input
  353.  
  354.       BPS rate to set the com port at.
  355.  
  356.   RETURNS
  357.     Return code.
  358.  
  359.     ComSetBPSRate returns the following values:
  360.  
  361.     0           No Errors
  362.     31          ERROR_GEN_FAILURE
  363.  
  364.     0xFF00 + 1  COMERR_PORT_NOT_OPEN
  365.  
  366.   REMARKS
  367.     ComSetBPSRate uses the set extended bit rate option of the DosDevIOCtl
  368.     function. Normally ComOpen sets this for you, so you do not need to
  369.     use this function.
  370.  
  371.     If you do not receive a general failure error, the BPS rate was set as
  372.     defined.
  373.  
  374.   EXAMPLE CODE
  375.     This examples changes the BPS rate to 19200.
  376.  
  377.         APIRET ReturnCode;
  378.  
  379.         ReturnCode = ComSetBPSRate(19200);
  380.  
  381.         if (ReturnCode)
  382.         {
  383.             printf("Error (%lu) setting BPS rate\n", ReturnCode);
  384.  
  385.             exit (1);
  386.         }
  387.  
  388.   #include <gio.h>
  389.  
  390.   APIRET EXPENTRY ComSetLineControl(BYTE Parity, SHORT DataBits,
  391.                                     SHORT StopBits)
  392.  
  393.   ComSetLineControl is used to set the Parity, Data Bits, and Stop Bits
  394.   of the current open port.
  395.  
  396.   PARAMETERS
  397.     Parity (BYTE) - input
  398.  
  399.         Determines if a parity bit should exist. The values of this field
  400.         may be as folows:
  401.  
  402.         Value   Definition
  403.         -----   ----------
  404.  
  405.         'O'     Odd parity
  406.  
  407.         'E'     Even Parity
  408.  
  409.         'M'     Mark Parity (parity bit always 1)
  410.  
  411.         'S'     Space Parity (parity bit always 0)
  412.  
  413.         'N'     No Parity
  414.  
  415.     DataBits (SHORT) - input
  416.  
  417.         The number of bits contained in each character transmitted, or
  418.         received by way of the communications port. Valid values are:
  419.  
  420.         Value   Definition
  421.         -----   ----------
  422.  
  423.         5       5 data bits
  424.         6       6 data bits
  425.         7       7 data bits
  426.         8       8 data bits
  427.  
  428.     StopBits (SHORT) - input
  429.  
  430.         The number of stop bits associated with each character transmitted,
  431.         or received by way of the communications port. Valid values are:
  432.  
  433.         Value   Definition
  434.         -----   ----------
  435.  
  436.         0       This sets default stop bits. For a setting of 5 data bits,
  437.                 The default is 1.5 stop bits. For 6, 7,  or 8 data bits,
  438.                 the default is 1 stop bit.
  439.         1       1 stop bit
  440.         2       2 stop bits
  441.  
  442.   RETURNS
  443.     Return code.
  444.  
  445.     ComSetLineControl returns the following values:
  446.  
  447.     0           No Errors
  448.     31          ERROR_GEN_FAILURE
  449.  
  450.     0xFF00 + 1  COMERR_PORT_NOT_OPEN
  451.  
  452.   REMARKS
  453.     ComSetLineControl is set when you used ComOpen, so in most cases you
  454.     will not need to use this function.
  455.  
  456.     If you do not receive a general failure error, you can assume that the
  457.     line control was set as defined.
  458.  
  459.   EXAMPLE CODE
  460.     This examples changes the line characteristics to Even Parity, 7 Data
  461.     Bits, and 1 Stop Bit.
  462.  
  463.         APIRET ReturnCode;
  464.  
  465.         ReturnCode = ComSetLineControl('E', 7, 1);
  466.  
  467.         if (ReturnCode)
  468.         {
  469.             printf("Error (%lu) setting line controls\n", ReturnCode);
  470.  
  471.             exit (1);
  472.         }
  473.  
  474.   #include <gio.h>
  475.  
  476.   APIRET EXPENTRY ComSetFlowControl(VOID)
  477.  
  478.   ComSetFlowControl is used to turn on hardware handshaking, and
  479.   hardware timeouts.
  480.  
  481.   PARAMETERS
  482.     None.
  483.  
  484.   RETURNS
  485.     Return Code.
  486.  
  487.     ComSetFlowControl returns the following values:
  488.  
  489.     0           No Errors
  490.     31          ERROR_GEN_FAILURE
  491.  
  492.   REMARKS
  493.     ComSetLineControl turns on RTS/CTS hardware flow control, and also
  494.     set hardware transmit and receive timeouts. It also enables DTR
  495.     control. Flow control is also set by ComOpen, so you may not have
  496.     to use this function.
  497.  
  498.     If you do not receive a general failure error, you can assume that flow
  499.     control was set.
  500.  
  501.   EXAMPLE CODE
  502.     This examples turns on RTS/CTS hardware flow control.
  503.  
  504.         APIRET ReturnCode;
  505.  
  506.         ReturnCode = ComSetFlowControl();
  507.  
  508.         if (ReturnCode)
  509.         {
  510.             printf("Error (%lu) setting flow controls\n", ReturnCode);
  511.  
  512.             exit (1);
  513.         }
  514.  
  515.   #include <gio.h>
  516.  
  517.   APIRET EXPENTRY ComSetDTR(SHORT DTROn)
  518.  
  519.   ComSetDTR is used to turn the DTR signal on and off.
  520.  
  521.   PARAMETERS
  522.     DTROn (SHORT) - input
  523.  
  524.       If DTROn is TRUE, then the DTR signal is raised. If FALSE, then
  525.       the DTR signal is lowered.
  526.  
  527.   RETURNS
  528.     Return Code.
  529.  
  530.     ComSetDTR returns the following values:
  531.  
  532.     0           No Errors
  533.     31          ERROR_GEN_FAILURE
  534.  
  535.   REMARKS
  536.     Toggling the DTR line is usually used to drop carrier and/or reset
  537.     the modem. The DTR is lowered for a couple of seconds, then raised
  538.     in order for the modem to receive commands.
  539.  
  540.     If you do not receive a general failure error, you can assume the DTR
  541.     signal was changed.
  542.  
  543.   EXAMPLE CODE
  544.     This examples drops the DTR line for 3 seconds, then raises it.
  545.  
  546.         APIRET ReturnCode;
  547.  
  548.         ReturnCode = ComSetDTR(FALSE);
  549.  
  550.         DosSleep(3000);
  551.  
  552.         ReturnCode = ComSetDTR(TRUE);
  553.  
  554.   #include <gio.h>
  555.  
  556.   BOOL EXPENTRY ComReportDCD(VOID)
  557.  
  558.   ComReportDCD is used to check for a carrier signal.
  559.  
  560.   PARAMETERS
  561.     None.
  562.  
  563.   RETURNS
  564.     TRUE  if a carrier signal is detected.
  565.     FALSE is no carrier signal is detected.
  566.  
  567.   REMARKS
  568.     ComReportDCD is usually used to see if a user has dropped the carrier.
  569.  
  570.   EXAMPLE CODE
  571.     This examples checks to see if a carrier is present.
  572.  
  573.         APIRET ReturnCode;
  574.  
  575.         ReturnCode = ComReportDCD();
  576.  
  577.         if (! ReturnCode)
  578.             printf("User has dropped carrier!\n");
  579.  
  580.   #include <gio.h>
  581.  
  582.   BOOL EXPENTRY ComReportCTS(VOID)
  583.  
  584.   ComReportCTS reports the status of the CTS line.
  585.  
  586.   PARAMETERS
  587.     None.
  588.  
  589.   RETURNS
  590.     TRUE  if CTS line is raised.
  591.     FALSE if CTS line is lowered.
  592.  
  593.   REMARKS
  594.     The CTS line is usually used to determine if the remote users modem
  595.     is ready to receive characters. If the other modem is not ready to
  596.     receive characters the CTS line goes low.
  597.  
  598.   EXAMPLE CODE
  599.     This examples checks to see if it is okay to send characters to our
  600.     modem.
  601.  
  602.         APIRET ReturnCode;
  603.  
  604.         ReturnCode = ComReportCTS();
  605.  
  606.         if (ReturnCode)
  607.             printf("It's okay to send chars! The CTS line is high!\n");
  608.  
  609.   #include <gio.h>
  610.  
  611.   APIRET EXPENTRY ComXONEnable(VOID)
  612.  
  613.   ComXONEnable is used to enable XON/XOFF style flow control.
  614.  
  615.   PARAMETERS
  616.     None.
  617.  
  618.   RETURNS
  619.     0           No Errors
  620.  
  621.   REMARKS
  622.     When XON/XOFF flow control is enabled, the device driver transmits an
  623.     XOFF character when the receive queue is almost full, and an XON when
  624.     the receive queue is about half full.
  625.  
  626.   EXAMPLE CODE
  627.     This examples enables XON/XOFF flow control.
  628.  
  629.         APIRET ReturnCode;
  630.  
  631.         ReturnCode = ComXONEnable();
  632.  
  633.   #include <gio.h>
  634.  
  635.   APIRET EXPENTRY ComXONDisable(VOID)
  636.  
  637.   ComXONDisable is used to disable XON/XOFF flow control.
  638.  
  639.   PARAMETERS
  640.     None.
  641.  
  642.   RETURNS
  643.     0           No Errors
  644.  
  645.   REMARKS
  646.     Turns off XON/XOFF flow control if it was enabled with ComXONEnable.
  647.  
  648.   EXAMPLE CODE
  649.     This examples disables XON/XOFF flow control.
  650.  
  651.         APIRET ReturnCode;
  652.  
  653.         ReturnCode = ComXONDisable();
  654.  
  655.   #include <gio.h>
  656.  
  657.   APIRET EXPENTRY ComGetDCBInfo(PDCBINFO DCBInfo)
  658.  
  659.   ComGetDCBInfo returns Device Control Block (DCB) information.
  660.  
  661.   PARAMETERS
  662.     DCBInfo (PDCBINFO) - input/output
  663.  
  664.       DCBInfo is a pointer to a DCB structure you have allocated. When the
  665.       function returns, the current DCB information will be in the structure
  666.       pointed to by DCBInfo.
  667.  
  668.   RETURNS
  669.     Return Code.
  670.  
  671.     ComGetDCBInfo returns the following values:
  672.  
  673.     0           No Errors
  674.     31          ERROR_GEN_FAILURE
  675.  
  676.   REMARKS
  677.     You can use ComGetDCBInfo to receive information on the following
  678.     items.
  679.  
  680.     1. Transmit flow control using XON/XOFF.
  681.     2. Receive flow control using XON/XOFF.
  682.     3. Determine what the XON/XOFF characters are.
  683.     4. DTR Control mode.
  684.     5. RTS Control mode.
  685.     6. Transmit handshaking using CTS/DSR/DCD.
  686.     7. Reception of data using DSR.
  687.     8. Error replacement character and processing.
  688.     9. Break replacement character and processing.
  689.    10. Null stripping.
  690.    11. Transmit/Receive timeouts.
  691.    12. Extended hardware buffering info.
  692.  
  693.     See the IBM Physical Device Driver Reference for more information.
  694.  
  695.     ALWAYS call ComGetDCBInfo before calling ComSetDCBInfo. The information
  696.     returned should be modified by the application then set using
  697.     ComSetDCBInfo.
  698.  
  699.     If a general failure is not returned, then valid information will be
  700.     in the DCBInfo structure.
  701.  
  702.   EXAMPLE CODE
  703.     This example uses ComGetDCBInfo to get the current DCB parameters, it
  704.     then modifies them and sets the new DCB parameters.
  705.  
  706.         DCBINFO DCBInfo;
  707.         APIRET  ReturnCode;
  708.  
  709.         ComGetDCBInfo(&DCBInfo);
  710.  
  711.         DCBInfo.usWriteTimeout = 1;
  712.  
  713.         DCBInfo.usReadTimeout  = 1;
  714.  
  715.         ReturnCode = ComSetDCBInfo(&DCBInfo);
  716.  
  717.         if (! ReturnCode)
  718.             printf("We set new write & read timeouts!\n");
  719.  
  720.   #include <gio.h>
  721.  
  722.   APIRET EXPENTRY ComSetDCBInfo(PDCBINFO DCBInfo)
  723.  
  724.   ComSetDCBInfo sets new Device Control Block (DCB) information.
  725.  
  726.   PARAMETERS
  727.     DCBInfo (PDCBINFO) - input
  728.  
  729.       DCBInfo is a pointer to a DCB structure you have allocated and/or
  730.       modified.
  731.  
  732.   RETURNS
  733.     Return Code.
  734.  
  735.     ComSetDCBInfo returns the following values:
  736.  
  737.     0           No Errors
  738.     31          ERROR_GEN_FAILURE
  739.  
  740.   REMARKS
  741.     You can use ComSetDCBInfo to set the following items.
  742.  
  743.     1. Transmit flow control using XON/XOFF.
  744.     2. Receive flow control using XON/XOFF.
  745.     3. Determine what the XON/XOFF characters are.
  746.     4. DTR Control mode.
  747.     5. RTS Control mode.
  748.     6. Transmit handshaking using CTS/DSR/DCD.
  749.     7. Reception of data using DSR.
  750.     8. Error replacement character and processing.
  751.     9. Break replacement character and processing.
  752.    10. Null stripping.
  753.    11. Transmit/Receive timeouts.
  754.    12. Extended hardware buffering info.
  755.  
  756.     See the IBM Physical Device Driver Reference for more information.
  757.  
  758.     ALWAYS call ComGetDCBInfo before calling ComSetDCBInfo. The information
  759.     returned should be modified by the application then set using
  760.     ComSetDCBInfo.
  761.  
  762.     If a general failure is not returned, then you may assume that the
  763.     device driver changed the information.
  764.  
  765.   EXAMPLE CODE
  766.     This example uses ComGetDCBInfo to get the current DCB parameters, it
  767.     then modifies them and sets the new DCB parameters.
  768.  
  769.         DCBINFO DCBInfo;
  770.         APIRET  ReturnCode;
  771.  
  772.         ComGetDCBInfo(&DCBInfo);
  773.  
  774.         DCBInfo.fbCtlHndShake  = MODE_CTS_HANDSHAKE | MODE_DTR_CONTROL;
  775.  
  776.         ReturnCode = ComSetDCBInfo(&DCBInfo);
  777.  
  778.         if (! ReturnCode)
  779.             printf("We set new handshake info!\n");
  780.  
  781.   #include <gio.h>
  782.  
  783.   APIRET EXPENTRY ComPurgeTXBuffer(VOID)
  784.  
  785.   ComPurgeTXBuffer is used to flush the output buffers.
  786.  
  787.   PARAMETERS
  788.     None.
  789.  
  790.   RETURNS
  791.     0  (No Error)
  792.  
  793.   REMARKS
  794.     Use ComPurgeTXBuffer if you wish to flush all data which were to
  795.     be transmitted. This function clears the GIO output buffer as well
  796.     as the device driver output buffer.
  797.  
  798.   EXAMPLE CODE
  799.     The following short example flushes the output buffer.
  800.  
  801.     ComPurgeTXBuffer();
  802.  
  803.   #include <gio.h>
  804.  
  805.   APIRET EXPENTRY ComTXCharImm(BYTE Char)
  806.  
  807.   ComTXCharImm transmits a byte immediately.
  808.  
  809.   PARAMETERS
  810.     Char (BYTE) - input
  811.  
  812.       This is the character you wished to be transmitted immediately.
  813.  
  814.   RETURNS
  815.     Return Code.
  816.  
  817.     ComTXCharImm returns the following values:
  818.  
  819.     0           No Errors
  820.     31          ERROR_GEN_FAILURE
  821.  
  822.   REMARKS
  823.     If a general failure is not returned then the character was transmitted.
  824.  
  825.     ComTXCharImm always returns immediately (before the character is actually
  826.     transmitted). If you already have sent one character using this function
  827.     and it has not been sent, then this function will return a general
  828.     failure.
  829.  
  830.     If there are already bytes waiting in the buffer to be transmitted, then
  831.     the byte goes to the 'front' of the buffer, and will be the next
  832.     character transmitted.
  833.  
  834.     The byte is not transmitted if flow control is currently not allowing
  835.     any data to be transmitted.
  836.  
  837.     ComTXCharImm is generally used to send XON and XOFF characters.
  838.  
  839.     Purging the transmit buffers does not purge a byte sent using
  840.     ComTXCharImm.
  841.  
  842.   EXAMPLE CODE
  843.     This examples sends a Ctrl-Q (a typical XON character) to the port.
  844.  
  845.         APIRET ReturnCode;
  846.         BYTE   XONChar = 17;
  847.  
  848.         ReturnCode = ComTXCharImm(XONChar);
  849.  
  850.   #include <gio.h>
  851.  
  852.   ULONG EXPENTRY ComTXChar(BYTE Char)
  853.  
  854.   ComTXChar sends one byte to the communications port.
  855.  
  856.   PARAMETERS
  857.     Char (BYTE) - input
  858.  
  859.       This is the byte to be sent to the communications port.
  860.  
  861.   RETURNS
  862.     0  (No Error)
  863.  
  864.   REMARKS
  865.     The char to be transfered is placed in the next available spot in
  866.     the transmit buffers. And is sent out as soon as possible.
  867.  
  868.   EXAMPLE CODE
  869.     This examples sends a character from the keyboard to the com port.
  870.  
  871.         APIRET ReturnCode;
  872.         int    KeyIn;
  873.  
  874.         do
  875.         {
  876.             if (kbhit())
  877.             {
  878.                 KeyIn = getch();
  879.  
  880.                 ReturnCode = ComTXChar((BYTE) KeyIn);
  881.             }
  882.         } while (1);
  883.  
  884.   #include <gio.h>
  885.  
  886.   APIRET EXPENTRY ComTXString(PSZ String, BOOL CheckCD)
  887.  
  888.   ComTXString sends a zero-terminated string to the com port.
  889.  
  890.   PARAMETERS
  891.     String (PSZ) - input
  892.  
  893.       This is the string to be sent to the comm port. It must be zero-
  894.       terminated.
  895.  
  896.     CheckCD (BOOL) - input
  897.  
  898.       This determines whether or not the function checks for a valid carrier
  899.       signal.
  900.  
  901.   RETURNS
  902.     0           No Errors
  903.     0xFF00 + 10 COMERR_CARRIER_DROPPED
  904.  
  905.   REMARKS
  906.     If you ask the function not to check for a valid carrier signal, then it
  907.     will always return 0 (No Errors).
  908.  
  909.     The string is placed in the transmit buffers character by character, and
  910.     these chars are sent out as soon as possible.
  911.  
  912.   EXAMPLE CODE
  913.     This examples sends a string to the com port, and checks for a dropped
  914.     carrier:
  915.  
  916.         APIRET ReturnCode;
  917.         PSZ    StringOut = "This is a test of the ComTXString function\n\r";
  918.  
  919.         ReturnCode = ComTXString(StringOut, TRUE);
  920.  
  921.         if (ReturnCode)
  922.             printf("The remote user dropped the carrier!\n");
  923.  
  924.   #include <gio.h>
  925.  
  926.   APIRET EXPENTRY ComTXBuffer(PBYTE Buffer, ULONG Size, BOOL CheckCD)
  927.  
  928.   ComTXBuffer sends a buffer of a defined length to the com port.
  929.  
  930.   PARAMETERS
  931.     Buffer (PBYTE) - input
  932.  
  933.       This is a pointer to the data to be transmitted.
  934.  
  935.     Size (ULONG) - input
  936.  
  937.       This is the amount of bytes to be transmitted.
  938.  
  939.     CheckCD (BOOL) - input
  940.  
  941.       This determines whether or not the function checks for a valid carrier
  942.       signal.
  943.  
  944.   RETURNS
  945.     0           No Errors
  946.     0xFF00 + 10 COMERR_CARRIER_DROPPED
  947.  
  948.   REMARKS
  949.     If you ask the function not to check for a valid carrier signal, then it
  950.     will always return 0 (No Errors).
  951.  
  952.     The string is placed in the transmit buffers character by character, and
  953.     these chars are sent out as soon as possible.
  954.  
  955.   EXAMPLE CODE
  956.     This examples sends a buffer of data to the com port, and doesn't check
  957.     for carrier:
  958.  
  959.         APIRET ReturnCode;
  960.         BYTE   CharBuffer[128];
  961.  
  962.         memset(CharBuffer, 32, 128);  // fill buffer with spaces (' ')
  963.  
  964.         ReturnCode = ComTXBuffer(StringOut, 128, FALSE);
  965.  
  966.   #include <gio.h>
  967.  
  968.   APIRET EXPENTRY ComTXEmpty(VOID)
  969.  
  970.   ComTXEmpty determines whether or no the transmite buffers are empty.
  971.  
  972.   PARAMETERS
  973.     None.
  974.  
  975.   RETURNS
  976.     TRUE  is the transmit buffers are empty.
  977.     FALSE if any bytes remain in the transmit buffers.
  978.  
  979.   REMARKS
  980.     ComTXEmpty is usually used to determine if all bytes have been sent
  981.     out the com port before a program ends, which will destroy the data
  982.     in the buffers.
  983.  
  984.   EXAMPLE CODE
  985.     This example waits an indefinate period until the transmit buffers
  986.     are empty before it exits.
  987.  
  988.         while (! ComTXEmpty());
  989.  
  990.         exit();
  991.  
  992.   #include <gio.h>
  993.  
  994.   APIRET EXPENTRY ComTXFull(VOID)
  995.  
  996.   ComTXFull determines whether or not the transmit buffers are full.
  997.  
  998.   PARAMETERS
  999.     None.
  1000.  
  1001.   RETURNS
  1002.     TRUE  is the transmit buffers are full.
  1003.     FALSE if no bytes remain in the transmit buffers.
  1004.  
  1005.   REMARKS
  1006.  
  1007.   EXAMPLE CODE
  1008.     This example shows whether or not the transmit buffers are full.
  1009.  
  1010.         APIRET ReturnCode;
  1011.  
  1012.         if (ComTXFull())
  1013.             printf("The transmit buffer is full\n");
  1014.  
  1015.   #include <gio.h>
  1016.  
  1017.   APIRET EXPENTRY ComTXFree(PUSHORT BytesFree)
  1018.  
  1019.   ComTXFree returns how many free bytes are in the transmit buffer.
  1020.  
  1021.   PARAMETERS
  1022.     BytesFree (PUSHORT) - output
  1023.  
  1024.       BytesFree is a pointer to a variable which will receive the number
  1025.       of bytes free in the transmit buffer.
  1026.  
  1027.   RETURNS
  1028.     0           No Errors
  1029.  
  1030.   REMARKS
  1031.     ComTXFree is usually used to determine if there is enough room in the
  1032.     buffers for the data you are about so send.  This sort of anticipates
  1033.     a condition where flow control takes over.
  1034.  
  1035.   EXAMPLE CODE
  1036.     This example shows how many bytes are free in the transmit buffer.
  1037.  
  1038.         USHORT BytesFree;
  1039.  
  1040.         ComTXFree(&BytesFree);
  1041.  
  1042.         printf("The transmit buffer has %u bytes free\n", BytesFree);
  1043.  
  1044.   #include <gio.h>
  1045.  
  1046.   VOID EXPENTRY ComWaitTillTXEmpty(ULONG Delay)
  1047.  
  1048.   ComWaitTillTXEmpty returns when the transmit buffer is empty, or a delay
  1049.   period has expired.
  1050.  
  1051.   PARAMETERS
  1052.     Delay (ULONG) - input
  1053.  
  1054.       Maximum time to wait for the transmit buffer to empty in hundredths
  1055.       of a second.
  1056.  
  1057.   RETURNS
  1058.     None.
  1059.  
  1060.   REMARKS
  1061.     ComWaitTillTXEmpty returns when the transmit buffer is empty, or the
  1062.     time delay period expires, whichever comes first.
  1063.  
  1064.     The delay time is in hundredths of a second rather than thousands of
  1065.     a second associated with the 'DosSleep' function.
  1066.  
  1067.   EXAMPLE CODE
  1068.     This example waits five seconds or until the transmit buffer is empty.
  1069.  
  1070.         ComWaitTillTXEmpty(500);
  1071.  
  1072.         printf("The transmit buffer is empty.. ending program\n");
  1073.  
  1074.         exit();
  1075.  
  1076.   #include <gio.h>
  1077.  
  1078.   APIRET EXPENTRY ComPurgeRXBuffer(VOID)
  1079.  
  1080.   ComPurgeRXBuffer is used to purge the input buffers.
  1081.  
  1082.   PARAMETERS
  1083.     None.
  1084.  
  1085.   RETURNS
  1086.     0           No Errors
  1087.  
  1088.   REMARKS
  1089.     ComPurgeRXBuffer can be used to purge all input from the remote user.
  1090.  
  1091.   EXAMPLE CODE
  1092.     The following line purges the input buffers.
  1093.  
  1094.         ComPurgeRXBuffer();
  1095.  
  1096.         return;
  1097.  
  1098.   #include <gio.h>
  1099.  
  1100.   APIRET EXPENTRY ComRXChar(PSHORT Char)
  1101.  
  1102.   ComRXChar returns the next available char in the input buffer, if any.
  1103.  
  1104.   PARAMETERS
  1105.     Char (PSHORT) - output
  1106.  
  1107.       The next available character is stored in Char. If no character is
  1108.       waiting Char will be -1.
  1109.  
  1110.   RETURNS
  1111.     0           No Errors
  1112.     0xFF00 + 11 COMERR_NO_CHAR_WAITING
  1113.  
  1114.   REMARKS
  1115.     If ComRXChar returns with a 0 return code a valid character is contained
  1116.     in Char. Otherwise Char is -1, and a error code is returned.
  1117.  
  1118.     After ComRXChar has read in the next character it is removed from the
  1119.     buffer.
  1120.  
  1121.     For best results, use ComRXChar after you have determined whether or
  1122.     not a character is waiting using ComRXCharWaiting.
  1123.  
  1124.   EXAMPLE CODE
  1125.     The follow example uses ComRXCharWaiting to determine is a character is
  1126.     waiting then uses ComRXChar to retrieve the character.
  1127.  
  1128.         SHORT  CharIn;
  1129.         APIRET ReturnCode;
  1130.  
  1131.         if (ComRXCharWaiting())
  1132.             ReturnCode = ComRXChar(&CharIn);
  1133.  
  1134.   #include <gio.h>
  1135.  
  1136.   APIRET EXPENTRY ComRXPeek(PSHORT Char)
  1137.  
  1138.   ComRXPeek retrieves the next character from the input buffer without
  1139.   removing it from the buffer.
  1140.  
  1141.   PARAMETERS
  1142.     Char (PSHORT) - output
  1143.  
  1144.       The next available character is stored in Char. If no character is
  1145.       waiting Char will be -1.
  1146.  
  1147.   RETURNS
  1148.     0           No Errors
  1149.     0xFF00 + 11 COMERR_NO_CHAR_WAITING
  1150.  
  1151.   REMARKS
  1152.     If ComRXPeek returns with a 0 return code a valid character is contained
  1153.     in Char. Otherwise Char is -1, and a error code is returned.
  1154.  
  1155.     Use ComRXPeek to determine what the next character is without removing
  1156.     it from the input buffer.
  1157.  
  1158.     For best results, use ComRXPeek after you have determined whether or
  1159.     not a character is waiting using ComRXCharWaiting.
  1160.  
  1161.   EXAMPLE CODE
  1162.     The follow example uses ComRXPeek to determine is a character is
  1163.     waiting then uses ComRXChar to retrieve the character.
  1164.  
  1165.         SHORT  CharIn;
  1166.         APIRET ReturnCode;
  1167.  
  1168.         if (ComRXCharWaiting())
  1169.             ReturnCode = ComRXChar(&CharIn);
  1170.  
  1171.   #include <gio.h>
  1172.  
  1173.   APIRET EXPENTRY ComRXCharWaiting(VOID)
  1174.  
  1175.   ComRXCharWaiting is used to determine whether or not a character is
  1176.   available in the input buffer.
  1177.  
  1178.   PARAMETERS
  1179.     None.
  1180.  
  1181.   RETURNS
  1182.     TRUE  if a character is waiting.
  1183.     FALSE if no character is waiting.
  1184.  
  1185.   REMARKS
  1186.      Use ComRXCharWaiting to see if there are any pending characters before
  1187.      you make a call to ComRXChar or ComRXPeek.
  1188.  
  1189.   EXAMPLE CODE
  1190.     The follow example uses ComRXCharWaiting to determine is a character is
  1191.     waiting then uses ComRXChar to retrieve the character.
  1192.  
  1193.         SHORT  CharIn;
  1194.         APIRET ReturnCode;
  1195.  
  1196.         if (ComRXCharWaiting())
  1197.             ReturnCode = ComRXChar(&CharIn);
  1198.  
  1199.   #include <gio.h>
  1200.  
  1201.   APIRET EXPENTRY ComRXCharTimed(PSHORT Char, ULONG Delay)
  1202.  
  1203.   ComRXCharTimed is used to wait a certain amount of time for an expected
  1204.   character.
  1205.  
  1206.   PARAMETERS
  1207.     Char (PSHORT) - output
  1208.  
  1209.       The next available character is stored in Char. If no character is
  1210.       waiting Char will be -1.
  1211.  
  1212.     Delay (ULONG) - input
  1213.  
  1214.       Maximum time to wait for expected character in hundredths of a
  1215.       second.
  1216.  
  1217.   RETURNS
  1218.     0           No Errors
  1219.     0xFF00 + 12 COMERR_TIMED_CHAR_NOT_RECEIVED
  1220.  
  1221.   REMARKS
  1222.     ComRXCharTimed is used to receive an expected character within a
  1223.     certain time period. If the character is received within the specified
  1224.     time period then the return code is zero (0). Otherwise you will
  1225.     receive the COMERR_TIMED_CHAR_NOT_RECEIVED error.
  1226.  
  1227.     This function is useful in protocol situations where characters are
  1228.     expected within certain time frames.
  1229.  
  1230.     The delay time is in hundredths of a second rather than thousands of
  1231.     a second associated with the 'DosSleep' function.
  1232.  
  1233.   EXAMPLE CODE
  1234.     The following example waits 2.5 seconds for an expected character.
  1235.  
  1236.         SHORT  CharIn;
  1237.         APIRET ReturnCode;
  1238.  
  1239.         ReturnCode = ComRXCharTimed(&CharIn, 250);
  1240.  
  1241.         if (ReturnCode)
  1242.             printf("Expected character not received!\n");
  1243.  
  1244.   #include <gio.h>
  1245.  
  1246.   VOID EXPENTRY ComSetDebug(BOOL Mode)
  1247.  
  1248.   ComSetDebug is used to start up GIO's 'Infobox' dialog window which shows
  1249.   information on GIO.
  1250.  
  1251.   PARAMETERS
  1252.     Mode (BOOL) - input
  1253.  
  1254.     FALSE - turns debug mode off.
  1255.     TRUE  - turns debug mode, and GIO dialog box on.
  1256.  
  1257.   RETURNS
  1258.     None.
  1259.  
  1260.   REMARKS
  1261.     Calling ComSetDebug starts up two more threads within GIO.  One is a
  1262.     thread which opens a message queue and pops up a dialog box which
  1263.     will contain information on the current copy of GIO. The other thread
  1264.     updates some of the data in the dialog, so you don't have to.
  1265.  
  1266.     If you wish to use the GIO Infobox (as the dialog is called) call
  1267.     ComSetDebug(TRUE) before calling ComOpen. This assures that all data
  1268.     will be up-to-date on your local screen.  If you wish to uniquely
  1269.     indentify each GIO Infobox, call ComSetDebugIdentity with an identity
  1270.     string (see ComSetDebugIdentity).
  1271.  
  1272.     Currently the infobox will show the status of several modem lines such
  1273.     as DTR, CTS, and DCD.  It also shows RTS, but the RTS box is currently
  1274.     not implemented.  The DTR box is not updated unless you call ComSetDTR.
  1275.  
  1276.     The program wishing to create the dialog box must be a PM based
  1277.     program. If the program is not PM based, you will here a very short
  1278.     beep which occurs when GIO can't create the dialog box.
  1279.  
  1280.   EXAMPLE CODE
  1281.     The following turns debug mode on, sets a unique identity, and then
  1282.     calls ComOpen.
  1283.  
  1284.         APIRET ReturnCode;
  1285.  
  1286.         ComSetDebug(TRUE);     // turn debug mode on
  1287.  
  1288.         sprintf(sTempString, "TW/2 - Node %d", sNode);
  1289.  
  1290.         ComSetDebugIdentity(sTempString);   //  unique identifier
  1291.  
  1292.         ReturnCode = ComOpen(NULL, 1, 19200, 'N', 8, 1, 1024, 1024, 0, FALSE);
  1293.  
  1294.   #include <gio.h>
  1295.  
  1296.   APIRET EXPENTRY ComPause(VOID)
  1297.  
  1298.   Used to temporarily stop GIO's input and output threads.  For instance, if
  1299.   your com program must shell out to another com program, you might want to 
  1300.   stop GIO's threads from continually grabbing characters from the port.
  1301.  
  1302.   PARAMETERS
  1303.     None.
  1304.  
  1305.   RETURNS
  1306.     0           No Errors
  1307.  
  1308.   REMARKS
  1309.     This function grabs the input and output semaphores, and doesn't let them
  1310.     go. It effectively stops the input and output threads.
  1311.  
  1312.     To start the threads back up, use ComResume. It releases the semaphores
  1313.     grabbed by ComPause.
  1314.  
  1315.   EXAMPLE CODE
  1316.     This code calls ComPause then ComResume.
  1317.  
  1318.         APIRET ReturnCode;
  1319.  
  1320.         ReturnCode = ComPause();    // stop input and output threads.
  1321.  
  1322.         //
  1323.         // the program might shell out to another com program here.
  1324.         //
  1325.  
  1326.         ReturnCode = ComResume();   // restart input and output threads.
  1327.  
  1328.         //
  1329.         // the program resumes here.
  1330.         //
  1331.  
  1332.   #include <gio.h>
  1333.  
  1334.   APIRET EXPENTRY ComResume(VOID)
  1335.  
  1336.   ComResume is used to restart the input and output threads which were stopped
  1337.   by ComPause.
  1338.  
  1339.   PARAMETERS
  1340.     None.
  1341.  
  1342.   RETURNS
  1343.     0           No Errors
  1344.  
  1345.   REMARKS
  1346.     This function releases the input and output thread semaphores grabbed by
  1347.     ComPause.
  1348.  
  1349.   EXAMPLE CODE
  1350.     This code calls ComPause then ComResume.
  1351.  
  1352.         APIRET ReturnCode;
  1353.  
  1354.         ReturnCode = ComPause();    // stop input and output threads.
  1355.  
  1356.         //
  1357.         // the program might shell out to another com program here.
  1358.         //
  1359.  
  1360.         ReturnCode = ComResume();   // restart input and output threads.
  1361.  
  1362.         //
  1363.         // the program resumes here.
  1364.         //
  1365.  
  1366.   #include <gio.h>
  1367.  
  1368.   APIRET EXPENTRY ComQueryHandle(PHFILE Handle)
  1369.  
  1370.   ComQueryHandle returns a copy of the com port handle used by GIO.
  1371.  
  1372.   PARAMETERS
  1373.     Handle (PHFILE) - output
  1374.  
  1375.       Contains the address of the variable which will contain the copy
  1376.       of file handle used by GIO.
  1377.  
  1378.   RETURNS
  1379.     0           No Errors
  1380.  
  1381.   REMARKS
  1382.     This function is provided as a convenience only. It will return a copy
  1383.     of the file handle used by GIO for the current com port.  Be very
  1384.     careful what you do with this copy of the handle, as you might cause
  1385.     GIO to malfunction.
  1386.  
  1387.     It should be used to pass on the handle to any child programs which may
  1388.     need access to the com port.
  1389.  
  1390.   EXAMPLE CODE
  1391.     This example retrieves a copy of GIO's file handle.
  1392.  
  1393.         APIRET ReturnCode;
  1394.         HFILE  ThisIsTheGIOHandle;
  1395.  
  1396.         ReturnCode = ComQueryHandle(&ThisIsTheGIOHandle);
  1397.  
  1398.         printf("The file handle in use by GIO is %lu\n", ThisIsTheGIOHandle);
  1399.  
  1400.   #include <gio.h>
  1401.  
  1402.   APIRET EXPENTRY ComSetInfoboxHwnd(ULONG Type, HWND Hwnd)
  1403.  
  1404.   This function is to used parent and/or owner window of the GIO Infobox
  1405.   dialog window.
  1406.  
  1407.   PARAMETERS
  1408.     Type (ULONG) - input
  1409.  
  1410.       COM_SETINFOBOXPARENT - This will cause the HWND contained in the
  1411.                              second parameter to become the parent window
  1412.                              of the GIO Infobox.
  1413.  
  1414.       COM_SETINFOBOXOWNER  - This will cause the HWND contained in the
  1415.                              second paramter to become the owner window
  1416.                              of the GIO Infobox.
  1417.  
  1418.     Hwnd (HWND) - input
  1419.  
  1420.       This is the parent or owner window handle as specified by the 'Type'.
  1421.  
  1422.   RETURNS
  1423.     0           No Errors
  1424.  
  1425.   REMARKS
  1426.     The default parent and owner of the GIO Infobox dialog is the desktop.
  1427.     You can change the parent and/or the owner of the Infobox using the
  1428.     call.
  1429.  
  1430.     If you wish to set the owner, and the parent, you must make two separate
  1431.     calls to ComSetInfoboxHwnd.
  1432.  
  1433.   EXAMPLE CODE
  1434.     This example sets the parent of the GIO Infobox.
  1435.  
  1436.         APIRET ReturnCode;
  1437.         HWND   MyHwnd;       // set by your code
  1438.  
  1439.         ReturnCode = ComSetInfoboxHwnd(COM_SETINFOBOXPARENT, MyHwnd);
  1440.  
  1441.   #include <gio.h>
  1442.  
  1443.   VOID EXPENTRY ComSetDebugIdentity(PSZ Identity)
  1444.  
  1445.   This function is used to uniquely identify each GIO Infobox with a string
  1446.   of your choice.
  1447.  
  1448.   PARAMETERS
  1449.     Identity (PSZ) - input
  1450.  
  1451.       A pointer to the string you wish to use to identify the GIO Infobox.
  1452.  
  1453.   RETURNS
  1454.     None.
  1455.  
  1456.   REMARKS
  1457.     You may identify each GIO Infobox with a string up to 20 characters in 
  1458.     length. If you string is longer than 20 characters, GIO will use only
  1459.     the first 20 characters.
  1460.  
  1461.     This string is shown in the dialog box when it is visible, and in
  1462.     the dialog title when the dialog box is minimized.
  1463.  
  1464.   EXAMPLE CODE
  1465.  
  1466.         PSZ = MyIdentifier = "Unique Identifier";
  1467.  
  1468.         ComSetDebugIdentity(MyIdentifyier);
  1469.  
  1470.  
  1471. 
  1472.