home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / modem / byepc300.arc / BYE-PC.DOC < prev    next >
Text File  |  1987-01-03  |  48KB  |  1,590 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.                   BYE-PC Resident Modem Driver
  12.                            with
  13.                        DOS Interface
  14.  
  15.               Manual Version 1.0 - February, 1987
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.      This  document  describes  the operation of BYE-PC  and  the
  43. application interfaces required to access functions that  control
  44. modem  operations.  It  is  not intended as a reference  to  8086
  45. assembly language or the 'C' programming language,  but serves to
  46. provide a description of the operation and uses of BYE-PC.
  47.  
  48.  
  49.                            by
  50.  
  51.                      MCODE Software
  52.                     3444 Dresden Drive
  53.                  Montgomery, Alabama, 36111
  54.                       (205)244-7230
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.              Copyright (C) 1986, 1987 MCODE Software
  64.  
  65.      All  of  the  source code is copyrighted material  by  MCODE
  66. Software.  The  author  retains  all rights to  the  source  code
  67. provided in this package. This code may not be distributed in any
  68. modified form without written or verbal consent from the  author.
  69. Any  form of sale other than MCODE Software is  prohibited.  This
  70. software  may  not  be offered for sale by any means or  form  to
  71. others without written permission from MCODE Software.
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.                          DISCLAIMER
  86.  
  87.      The  author has taken great care to insure that this  manual
  88. and  associated software provide accurate information in  regards
  89. to the documentation and source code provided.  Any references to
  90. particular  compilers,  linkers  or other development  tools  are
  91. believed to be true by the author.  No warranty is made regarding
  92. the  fitness  or validity of such material for any  circumstance.
  93. Hardware  and  software compatibility is not guaranteed  for  any
  94. particular  types of machines other than those mentioned in  this
  95. manual.  This software has been tested extensively under specific
  96. operating  environments and is believed to operate  as  described
  97. within  this  manual.  In  no event will MCODE  software  or  the
  98. authors  be held liable for damages of any kind,  in regard to or
  99. arising  from the use of accompanying software or and  documenta
  100. tion.  No  representation to the suitablity for this product  for
  101. any use is made by the author.
  102.  
  103.  
  104.      BYE-PC is a Tradmark of MCODE Software.  IBM, IBM PC, PC XT,
  105. PC  AT,  DOS  and PCDOS are Tradmarks of  International  Business
  106. Machines Corp.   Microsoft C,  MSDOS, ASM, and MASM are Tradmarks
  107. of Microsoft Corp.  Hayes, Smartmodem, Smartmodem 300, Smartmodem
  108. 1200 are trademarks of Hayes Microcomputer Products Inc.  CP/M is
  109. a tradmark of the Digital Research Corp.
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.                   TABLE OF CONTENTS
  117.  
  118.  
  119. Introduction.........................................
  120.  
  121. Compiler Information.................................
  122.  
  123. Configuring BYE-PC for your system...................
  124.  
  125. BYE-PC Program Structure.............................
  126.  
  127. Interface to application programs....................
  128.  
  129. Caller status word...................................
  130.  
  131. Getting Started......................................
  132.  
  133. Program Operating structure..........................
  134.  
  135. Interface functions..................................
  136.  
  137. Compiling BYE.ASM Source Code........................
  138.  
  139. Telebit Trailblazer(tm) 9600bps high speed modem.....
  140. .PA
  141.                      INTRODUCTION
  142.  
  143.  
  144.      Welcome  to BYE-PC!  Your support is greatly appreciated and
  145. we sincerely thank you for using our product. It is our hope
  146. that you will benifit and learn from the provided source code. If
  147. you  are  an accomplished programmer and already  understand  the
  148. operations  of  interrupt driven software,  please send  us  your
  149. comments,   advice  or  any  other  suggestions  concerning  this
  150. package.  We  hope that you will enjoy using this package as much
  151. as  we have in providing it.  Contact us if you  are  having  any
  152. problems  setting  up the system and we will try to  provide  you
  153. with  an  answer or solution.  It is recommended  that  a  $30.00
  154. donation  be  made  to the author if you use this  program  on  a
  155. regular  basis.  Registered users will receive technical  support
  156. only.  PLEASE  DON'T  BOTHER TO CALL IF YOU ARE NOT A  REGISTERED
  157. USER!
  158.  
  159.      MCODE  Software  will  provide  all  registered  users  with
  160. updates  for  an  unlimited period of time.  Users  that  request
  161. updates will have to provide for any shipping and disk cost at  a
  162. very minimal fee. Also, we plan to keep the latest copies of BYE-
  163. PC  and  related  programs available for downloads at  any  time.
  164. Please keep in touch with us via the Board Walk RBBS distribution
  165. point in Montgomery,  Alabama at (205)277-3882 or write to us  at
  166. MCODE  Software.  There are still many new features in the making
  167. and  we  want you to receive the latest versions as soon  as  re
  168. leased.
  169.  
  170.  
  171. WHAT IS BYE-PC?
  172.  
  173.      BYE-PC  is a memory resident modem driver that is  interrupt
  174. driven to provide fast reliable serial communications with  phone
  175. modems.  BYE-PC  is  a  complete implementation of the  BYE  CP/M
  176. version  offered  in  the  public domain for  use  on  eight  bit
  177. systems.  The  CP/M implementation does not support rs232  driven
  178. interrupts and is much slower than BYE-PC. BYE-PC allows for full
  179. keyboard  type ahead from the remote station.  Characters may  be
  180. received during other processes without polling the receive  port
  181. for a data ready signal.
  182.  
  183.      Please  be  sure and read  the  supplementary  documentation
  184. files that exsists.  These files contain important information on
  185. recent updates that may have occured:
  186.  
  187.                READ.ME        ----      Latest modifications
  188.  
  189. Any recent modifications that occur since the last manual  publi
  190. cation,  are contained in the file READ.ME.  Please read the copy
  191. right notice and license agreement in the file COPYRGHT.BYE.
  192. .PA
  193. WHAT WILL BYE-PC DO?
  194.  
  195.      An  IBM  PC,  PC XT,  or PC AT host computer running  BYE-PC
  196. allows a remote callers access to DOS. A series of interrupts are
  197. overtaken  and/or chained that patch the modem i/o  signals  into
  198. the  BIOS.  Since  DOS makes calls through the BIOS,  almost  any
  199. program  that does not access the serial port or screen  directly
  200. will run under BYE-PC. Although the large majority of programs do
  201. not  adhere to these rules,  most programs that are well  behaved
  202. and write to 'stdin' and 'stdout' will run properly under BYE-PC.
  203. For instance,  DEBUG may run remotely to allow viewing the system
  204. internally,  or file archive utilities such as ARC,  ZOO, etc...,
  205. may be used.
  206.  
  207.     Once a caller has established a connection, BYE-PC allows the
  208. option to execute a .COM or .EXE file.  This allows any number of
  209. programs,  such  as bulletin boards,  to receive  control  before
  210. allowing  users to enter DOS.  Since any DOS commands may be exe
  211. cuted  while  running BYE-PC,  users  have  complete  control.  A
  212. security shell is provided that parses all DOS commands prior  to
  213. execution by COMMAND.COM. This allows selective commands to check
  214. internal status before execution to eliminate unwanted  commands,
  215. paths, drives or DOS functions.
  216.  
  217.      Currently  all  application programs that provide access  to
  218. BYE-PC such as XMODEM,  CHAT,  STAT,  and RBBS, are created using
  219. the Microsoft C compiler.   A standard interface is provided that
  220. allows  C  programs  direct control  over  the  host  system.  An
  221. application  may  disconnect,  check  status,  or  change  values
  222. within BYE-PC through an additional software interrupt.  Assembly
  223. language  routines  may  call  BYE-PC functions as  easily  as  C
  224. applications through the system control interrupt (SCI).
  225.  
  226.      Since  all  data  is  received  from  hardware   interrupts,
  227. characters are stored in a buffer within BYE-PC as each interrupt
  228. occurs.  All  requests for data are made through the SCI and  the
  229. provided  C  interface BYEXFACE.C.  These topics are  covered  in
  230. greater detail in the following sections of this manual. Hardware
  231. interrupts  occur  with changes of state in the  rs-232  serial
  232. port  card.  In  the event of a carrier  loss,  an  interrupt  is
  233. generated  that  warm  boots the system to prepare for  the  next
  234. call.
  235. .PA
  236.                    COMPILER INFORMATION
  237.  
  238.      Currently, all of our assembly and C source code modules are
  239. compiled  using Microsoft Compilers. We feel that these compilers
  240. are  amoung  some  of the best available for the  PC  market  and
  241. strongly  recommend their use with our packge.   We have not used
  242. any  other  C compilers or assemblers available on the market  to
  243. compile  our  code with.  Since the  C language  for  8086  based
  244. machines varies so widely in its library extensions,  it would be
  245. very difficult to adapt the code to all versions.
  246.  
  247.      Either  MASM or ASM may be used to compile BYE-PC  directly.
  248. Once the .OBJ file is created,  LINK and EXE2BIN are then used to
  249. create  the  resulting .COM file.  Version 3.0 or 4.0  of  the  C
  250. compiler  will  compile  all C modules in any  of  the  available
  251. memory models with without difficulties.  MASM is required on all
  252. of the assembly modules used in conjuntion with C  programs.  The
  253. file  MODEL.H contains the macros used to setup the C environment
  254. needed  for  all  assembly language files.  If  you  develop  any
  255. assembly source code,  we strongly recommend using MODEL.H in all
  256. of the modules to set up the segments and pointers argument list.
  257.  
  258.      Any  C compiler that suports access to  software  interrupts
  259. should  work with BYE-PC.  All modem i/o,  modem  control,  modem
  260. status, and line control are performed through software interrupt
  261. 66h.  If your compiler supports this feature,  only the interface
  262. functions  should  require  changes.   All  application  programs
  263. provided in this package are device independant. All of the modem
  264. functions are dependant upon BYEXLIBx.LIB to provide the  necces
  265. sary  interface  functions.  These libraries contain all  of  the
  266. functions needed to access BYE-PC functions within C programs.
  267.  
  268.      How to compile BYEx.xx.ASM:
  269.  
  270.           1) Compile .ASM source code using ASM
  271.  
  272.           2) Link using LINK to generate and .EXE file
  273.  
  274.           3) use EXE2BIN to convert to a .COM file
  275.  
  276.           4) delete the .EXE extension file
  277.  
  278.      Using MAKE:
  279.  
  280.             C>make bye {return}
  281.  
  282.      A  MAKE  file 'BYE' is provided to  automatically  link  the
  283. object code and produce the .COM file.  This will also delete the
  284. copy of the .EXE file since it is of no use.  Once the BYExxx.COM
  285. file is generated,  rename it to BYE.COM and place it in the root
  286. directory of the RBBS system disk.
  287. .PA
  288.                CONFIGURING BYE-PC FOR YOUR SYSTEM
  289.  
  290.  
  291.      In  order  to run BYE-PC on your system you  will  need  the
  292. appropriate modem and serial port for you system.  A standard DCE
  293. configuration  port is required to the modem.  This port must  be
  294. configured  for COM1 using IRQ4 or,  COM2 using IRQ3 respectivly.
  295. Almost  all serial cards availble for PC's will be configured  in
  296. this fashion at purchase and should not require altering.  If you
  297. are not sure of you boards configuration, consult you serial port
  298. manual and check the jumper locations on you board.
  299.  
  300.      A  Hayes Smartmodem(tm) with AT command sets is required  to
  301. work  with  BYE-PC  or a manual modem such as  a  Universal  Data
  302. Systems 212B.  If a manual modem is used, BYE-PC will monitor the
  303. data  carrier detect (DCD) to determine when a call occurs.  Once
  304. carrier is acknowledged,  BYE-PC will begin switching baud  rates
  305. of  the port and looking for a sycronization character  (carriage
  306. return or Ctrl-C). Smart modems return a result code that informs
  307. BYE-PC of the baud rate currently on line.
  308.  
  309.      Configuring  BYE-PC  is  basically a matter of  setting  the
  310. various equates in the source code file BYExx.x.ASM. All of these
  311. equates are found after the title 'program configuration section'
  312. of the source code file.  If you choose to execute a .COM or .EXE
  313. file  upon receiving a valid carrier,  you will need to edit  the
  314. path/file name at the end of the source code listing at the label
  315. 'child  name'.  You  may enter a full path/drive name  if  needed
  316. here, however, make sure it not over 63 characters in length. The
  317. following sections expains the various equate settings.
  318.  
  319. .PA
  320. Selecting a COM port
  321.  
  322.      BYExx.x is configured to use COM1 on the distribution  disk.
  323. However,  may  alter  this  to  COM2 by  changing  the  following
  324. three equates:
  325.  
  326.  
  327.      RS232_INT - This is used to select the interrupt  vector
  328.                  location. COM1 uses interrupt vector 0Ch, while
  329.                  COM2 requires interrupt location 0Bh.
  330.  
  331.      IRQ_BASE  - This is the interrupt request register base port
  332.                  address. COM1 (IRQ4) uses i/o address 10h, while
  333.                  COM2 (IRQ3) uses i/o port 08h.
  334.  
  335.      PORT_BASE - This is the 8255 serial i/o port base  address.
  336.                  COM1 is at 03F8h, and COM2 is at address 02F8h
  337.  
  338.  
  339.  
  340. Selecting Modem Type
  341.  
  342.      If you are using a smart modem,  you will need to make  sure
  343. the  equate SMART_MDM is set to YES.  The next three equates  are
  344. used  to  describe  the highest baud rate  your  modem  supports.
  345. Select ONE of the equates labeled BPS_300,  BPS_1200,  or BPS_2400
  346. and  set it to YES.  If you wish to use BYE-PC with a high  speed
  347. modem,   the   Telebit   Trailblazer(tm)   modem   will   support
  348. transmission speed in excess of 18k bps with a maximum throughput
  349. of  9600  baud.  If you have a Trailblazer,  set the TELEBIT  and
  350. USE_RTS equates to YES.
  351.  
  352. The  Trailblazer(tm)  requires  handshaking via RTS  and  CTS  to
  353. provide  flow control.  Since the possiblity exists for  data  to
  354. overflow the receive queue,  handshaking is required for reliable
  355. operation.  If  the  receive  data queue  becomes  full,  RTS  is
  356. asserted  low until the receive data queue is 1/4th full  of  the
  357. total queue size.  This allows BYE-PC to catch up with the  modem
  358. receive data until it can accept more data.
  359.  
  360.  
  361. Sending 'nulls' to Remote
  362.  
  363.      If you do not have a 2400bps modem,  you may want to disable
  364. this feature.  If enabled, this will send the requested number of
  365. nulls  (0 to 9) after a line feed is recevied.  This  feature  is
  366. mainly a leftover from the teletype days, but it is still used by
  367. high speed callers.  This allows the remote end to settle after a
  368. line  feed  before  sending any other data on a new  line.
  369.  
  370.  
  371. Executing a Program on Carrier Detect
  372.  
  373.      If  you wish to execute a program,  such as a bulletin board
  374. service,  upon carrier detect,  set the LOGON_EXE equate to  YES.
  375. You will have to set the drive/path/file name at the end very end
  376. of the source code. The default value is "A:SYSTEM\XBBS\XBBS.EXE"
  377. for the source code mailed out.  If LOGON_EXE is set to YES, BYE-
  378. PC will attempt to execute this program from drive A:.  If it  is
  379. not  found,   an  error  message  is  displayed  and  control  is
  380. transferred to DOS.
  381.  
  382.  
  383. Warm Booting After Local Execute
  384.  
  385.      The  equate NBOOT is used mainly for debugging  applications
  386. that  run  under BYE-PC such as bulleting board system.  If  this
  387. equate is set to YES,  BYE-PC will re-boot after pressing  Ctrl-C
  388. and  running the LOGON_EXE file locally.  If NO,  BYE-PC will not
  389. re-boot  but  cut off data sent to and from the modem  and  allow
  390. entry into DOS.  This allows BYE-PC to remain resident,  but  not
  391. send  or receive any data from the modem.  This is a very  useful
  392. feature  for  debugging application programs that run under  XBBS
  393. such  as  XBBS.  You may perform any operations  in  DOS,  except
  394. loading  other  resident programs,  that you normally  use  while
  395. creating  applications  to  run  under  BYE-PC   (i.e.   editing,
  396. compiling, etc..).
  397.  
  398.  
  399. Setting the Default Time Limit
  400.  
  401.      The  default time limit for callers initially is set for  60
  402. minutes.  This  is  usually  set to by XBBS  or  other  programs,
  403. however,  before  allowing entry into DOS or upon logging on  the
  404. system.  The equate TIME, allows setting the initial time allowed
  405. on the system per caller. You may set this value to 0 if you wish
  406. unlimited time per call.
  407. .PA
  408. Special Function Keys
  409.  
  410.      BYE-PC  has several special ALT function  keys.  These  keys
  411. allow  direct  control over all programs operating under  BYE-PC.
  412. These keys are mapped as follows:
  413.  
  414.           ALT-B     Toggles the remote caller on/off while in
  415.                     DOS. If off, no data is sent or received
  416.                     from the remote.
  417.  
  418.           ALT-C     Displays Caller online when using XBBS.
  419.  
  420.           ALT-O     Send 'system going down in 2 min(s)' msg.
  421.                     This is used to tell the caller to log off.
  422.  
  423.           ALT-H     Hangup on the caller and re-boot system.
  424.  
  425.           ALT-Q     Enter 'message from sys/op' mode. This dis-
  426.                     ables data from the remote, and allows the
  427.                     sys/op to type a message to the remote. To
  428.                     exit, press ESC or the [End] key.
  429.  
  430.           ALT-Z     Clear the screen locally.
  431.  
  432.           ALT-U     Gives the caller online unlimited time for
  433.                     session active.
  434.  
  435.           ALT-S     Temporarily gives a caller sys/op privledges
  436.                     by setting the CSW to ffffh.
  437.  
  438.      These  keys  may  be re-mapped if you wish  by  setting  the
  439. K_{function}  keys  to different ALT_c keys.  Simply  change  the
  440. equates  to reflect the new ALT_c keys.  Be careful not to  cause
  441. any  conficts  in  changing these keys if you must  change  them.
  442. Normally you should not have to change any of these values.
  443. .PA
  444. BYE-PC interface via INT 66
  445.  
  446.  
  447.      BYE-PC  provides  all  functions  needed  to  support  modem
  448. control  and i/o functions used by application programs that  run
  449. under  BYE-PC.  The  most common program to run under  BYE-PC  is
  450. XMODEM.  XMODEM  requires  many  interface  functions  for  modem
  451. control  and data i/o transfer.  The accompanying source code  on
  452. disk  1,  BYEXFACE.C,  contains  all  of the funcions  needed  to
  453. support C applications under BYE-PC. Make a listing of all of the
  454. source  code and study the functions carefully.  This is used  by
  455. all C programs for modem control and i/o.
  456.  
  457.      These  functions can be called from most any  language  that
  458. allows  access to software interrupts.  Assembly language  allows
  459. the most direct control of software interrupts.  BYE-PC currently
  460. uses  software  interrupt  66h  for all  modem  control  and  i/o
  461. functions.  The  following  is  a complete list of  all  INT  66h
  462. functions currently provided by BYE-PC:
  463.  
  464. -----------------------------------------------------------------------
  465. INT66 APPLICATIONS PROGRAM INTERFACE (API) -- This interrupt provides
  466.  modem i/o for applications which need direct control of the modem.
  467.  
  468.    Altered registers  :  AX, BX, CX, DX
  469.                          ES (only when funct 21 called)
  470.  
  471.    Preserved registers:  CS, DS, SS, DI, SI, SP, BP
  472.  
  473. -----------------------------------------------------------------------
  474.  
  475.  Functions Provided:
  476.  
  477.    AH=0       Get character from modem in AL.
  478.                    AL=character returned
  479.                    AH=0 null (no keybd scan codes)
  480.                    AX = EOF if no data.
  481.  
  482.    AH=1       Put character in AL to modem.
  483.                    AL=character to send.
  484.  
  485.    AH=2       Hang up the modem (DTR off):
  486.                    AL=0 turn off dtr
  487.                    AL=1 turn on dtr
  488.  
  489.    AH=3       Get carrier detect status in AX:
  490.                    AX=0 no carrier detect found
  491.                    AX=1 carrier detect found
  492.  
  493.    AH=4       Set carrier detect check status:
  494.                    AX=0 ignore carrier detect status
  495.                    AX=1 check carrier detect status
  496.  
  497.    AH=5       Flush the rx queue of all data.
  498. .PA
  499.    AH=6       Get # of chars in rx queue:
  500.                    AX=0 rx queue size
  501.  
  502.    AH=7       Get Baud rate of this call in AX:
  503.                   (0=300bps, 1=1200bps, 3=2400bps)
  504.  
  505.    AH=8       Set Control Break/Pause (CTRL-C/CTRL-S) flag state:
  506.                    AL=0 CTRL_NOBRK  - disable remote ^C & ^S breaks
  507.                    AL=1 CTRL_BRK    - enable remote breaks
  508.                    AL=2 CTRL_NOTOUT - disable ^S pause timeout
  509.                    AL=3 CTRL_TOUT   - enable ^S timeout
  510.                    AL=4 CTRL_NOTRAP - dont trap ^C & ^S characters
  511.                    AL=5 CTRL_TRAP   - allow ^C & ^S to be trapped out
  512.  
  513.    AH=9       Set <stdout> merged with modem:
  514.                    AL=0 disable output modem
  515.                    AL=1 enable output to modem
  516.  
  517.    AH=10      Set <stdin> merged with modem:
  518.                    AL=0 disable input from modem  (rx-queue active)
  519.                    AL=1 enable input from modem   (rx-queue active)
  520.  
  521.    AH=11      Get BYE-PC version/revison level in AX:
  522.                    AL=Current Revision level
  523.                    AH=Current Version level
  524.  
  525.    AH=12      Get number of nulls requested in AX:
  526.                    AX=Number of nulls requested
  527.  
  528.    AH=13      Set number of nulls to AX:
  529.                    AL=Number of nulls to send
  530.  
  531.    AH=14      Warm Boot the system through bios Ctrl-Alt-Del.
  532.  
  533.    AH=15      Get the user caller status
  534.                    AX=Status level (0-FFFFh).
  535.  
  536.    AH=16      Set the user caller status
  537.                    CX=Status level (0-FFFFh).
  538.  
  539.    AH=17      Set the time limit caller is allowed on line.
  540.                    AL=number of minutes (0-255, 0=Unlimited).
  541.  
  542.    AH=18      Get the time caller has been on line
  543.                    AX=number of minutes online (0-255).
  544.  
  545.    AH=19      Set the receive data interrupt mode
  546.                    AL=Mode (0=Off, 1=On)
  547.  
  548.    AH=20      Get the time limit caller is allowed on line.
  549.                    AX=number of minutes allowed online (0-255).
  550.  
  551.    AH=21      Get far pointer to caller name buffer.
  552.                    ES:BX -> far ptr to name buffer
  553. .PA
  554.    AH=22      Get far pointer to terminal configuration buffer
  555.                    ES:BX -> far ptr to terminal config buffer
  556.  
  557.  
  558.  
  559. CALLER STATUS WORD STRUCTURE
  560.  
  561.  
  562. The caller status word is a sixteen bit word used by SHELL, XMDM,
  563. and other application programs to check for command priorities which
  564. are set by an RBBS program before the user can enter DOS. The MSW of
  565. the status word bits have been reserved for any applications that
  566. may be developed in the future. The LSW bits have the followine
  567. meaning:
  568.  
  569.         CSW (Caller status word):
  570.  
  571.         {LSW (least significant word)}
  572.  
  573.         ----MSB----  ----LSB----
  574.         D7 D6 D5 D4  D3 D2 D1 D0
  575.         |  |  |  |   |  |  |---|--- {reserved for future use}
  576.         |  |  |  |   |  |---------- PATH restriction disable.
  577.         |  |  |  |   |------------- CD command allowed enable.
  578.         |  |  |  |----------------- XMDM S {file} allowed.
  579.         |  |  |-------------------- XMDM R {file} allowed.
  580.         |  |----------------------- Shell DOS command allowed.
  581.         |-------------------------- Shell EXIT command allowed.
  582.  
  583.  
  584.         {MSW (most significant word)}
  585.  
  586.         ----MSB----  ----LSB----
  587.         D7 D6 D5 D4  D3 D2 D1 D0
  588.           {unused}   |  |  |  |
  589.                      |--|--|--|---  Max Drive allowed (0-15).
  590.  
  591.  
  592.  
  593.      The   settings  of  the  CSW  has  no  effect  upon   BYE-PC
  594. operations,  it  is intended for use as a global flag word  which
  595. various  applications  may refer to.  This allows any  number  of
  596. applications  running under BYE-PC to check status levels set  by
  597. other  programs before performing an operation.  Its main purpose
  598. is to inform XMODEM and SHELL if a user has sufficient status  to
  599. perform file transfers or change directories/paths.
  600.  
  601. .PA
  602. BYEXLIXs.C Interface Functions
  603.  
  604.      The  following  pages  describe each  function  provided  in
  605. BYEXLIBx.C  and how to use each one.  This is provided as a quick
  606. reference  when  developing code that use BYE-PC control  or  i/o
  607. functions.  Do  not  attempt to address the  serial  port  either
  608. directly  or  through the BIOS in any application  program.  This
  609. will  cause  severe problems with the interrupts and  very  likly
  610. crash the system. The following libraries contain the modules for
  611. all memory models supported by MSC:
  612.  
  613.           BYEXLIBS.LIB   {small memory model}
  614.           BYEXLIBM.LIB   {medium memory model}
  615.           BYEXLIBC.LIB   {compact memory model}
  616.           BYEXLIBL.LIB   {large memory model}
  617.  
  618. All  of the source code in these library files requires MASM  5.0
  619. to  create.  This  version  contatins  macros  which  allow  easy
  620. creation of assembly modules for use with MSC.
  621.  
  622.      All  applicactions must use INT66 for all modem control  and
  623. i/o  for  data transfer.  XMDM.C provided  with  the  development
  624. package  shows  how to use BYE-PC interrupt functions in  detail.
  625. You  may  wish to develop your own interface in Pascal  or  other
  626. language however.  If you develop an interface module for another
  627. lauguage  than  C,  please  contact us if you  wish  to  make  it
  628. available to other programers of BYE-PC applications.
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636. 
  637.                        'BYEXLIBx.LIB'
  638.  
  639.                     FUNCTIONS DESCRIPTION
  640.  
  641.                    FOR MSC 3.0, 4.0, & 5.0
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652. 
  653. NOTE:  These  functions  describe BYEXLIBx.LIB version  2.00.  Any
  654.        previous versions released are no longer in use.
  655. 
  656.  
  657. FUNCTION:      int _bye_check(lver, hver, lrev, hrev)
  658.  
  659. PARAMETERS:   int lver, hver;     lowest/highest version
  660.                int lrev, hrev;     lowest/highest revision
  661.  
  662. PURPOSE:      Allows  checking  to ensure that BYE-PC is  loaded
  663.                and resident in memory and of the correct  version
  664.                and  revision level.  This function must be called
  665.                before any '_bye' functions are called or,  a hard
  666.                system crash will result and require power down to
  667.                reload the system.
  668.  
  669. RETURN:       0 = BYE-PC loaded and is an acceptable version
  670.                1 = BYE-PC is not loaded yet
  671.                2 = BYE-PC is loaded  but,  invalid version#
  672.                3 = BYE-PC is loaded but, invalid revision#
  673.  
  674. EXAMPLE:
  675.  
  676. #include <stdio.h>
  677. #include "byexface.h"
  678.  
  679. #define MIN_VER 1       /* minimum BYE-PC version# required  */
  680. #define MIN_REV 2       /* minimum BYE-PC revision# required */
  681. #define MAX_VER 9       /* maximum BYE-PC version# allowed   */
  682. #define MAX_REV 99      /* maximum BYE-PC revision# allowed  */
  683.  
  684. main()             /* must at least be version 1.02 */
  685.     {              /* but, any version after and up */
  686.     int rtn;       /* to 9.99 will work.            */
  687.  
  688.     if ((rtn = _bye_check(MIN_VER, MAX_VER, MIN_REV, MAX_REV)) != 0)
  689.         {
  690.         printf("\nERROR: BYE-PC ");
  691.         switch(rtn)
  692.             {
  693.             case 1:
  694.                 printf("is not loaded!\n");
  695.                 break;
  696.             case 2:
  697.                 printf("loaded is the wrong Version!\n");
  698.                 break;
  699.             case 3:
  700.                 printf("loaded is the wrong Revision!\n");
  701.                 break;
  702.             default:
  703.                 printf("returned invalid error code!\n");
  704.                 break;
  705.             }
  706.         exit(1);
  707.         }
  708.  
  709.  
  710.  
  711.  
  712. FUNCTION:      int _bye_getc()
  713.  
  714. PARAMETERS:    void
  715.  
  716. PURPOSE:       Returns a character from the receive data queue if
  717.                avilable.  This is for directly reading a a stream
  718.                of data from the modem.  Make sure that data  sent
  719.                and  received  from  the  screen/keyboard  is  off
  720.                before using _bye_getc() and _bye_putc().
  721.  
  722. RETURN:        Returns  an 8 bit character from the receive  data
  723.                queue.  If  no  data is available an EOF value  is
  724.                returned.
  725.  
  726. EXAMPLE:
  727.  
  728. #include <stdio.h>
  729. #include "byexface.h"
  730.  
  731. /*
  732. ** Collect a 128 bytes of binary data from the receive queue.
  733. ** This function will not return until all data has been
  734. ** received. Before we can receve the data we must disable
  735. ** data sent to the screen and key presses from going to
  736. ** the modem. We must also disable trapping of ^S and ^C
  737. ** so that they may pass a valid binary data characters.
  738. */
  739.  
  740. main()
  741.      {
  742.      char buf[140];
  743.      int i;
  744.  
  745.     _bye_setbreak(CTRL_NOTRAP); /* dont trap/filter ^C & ^S data */
  746.     _bye_stdout(0);             /* turn on console Rx & Tx */
  747.     _bye_stdin(0);
  748.  
  749.     for(i = 0; i < 128; i++)       /* read 128 bytes of data */
  750.           {
  751.           while(!_bye_rxsize())    /* wait for data to appear */
  752.                ;
  753.           buf[i] = _bye_getc();    /* place data in buffer */
  754.           }
  755.  
  756.     _bye_stdin(1);              /* turn on console Rx & Tx */
  757.     _bye_stdout(1);
  758.     _bye_setbreak(CTRL_TRAP);   /* enable trap ^C & ^S data */
  759.     exit(0);                    /* exit back to DOS */
  760.     }
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767. FUNCTION:      int _bye_putc(c)
  768.  
  769. PARAMETERS:    int c;    character to transmit to modem
  770.  
  771. PURPOSE:       Transmit the character 'c' to the modem . A return
  772.                return  value  of EOF indicates a  serious  error.
  773.                Either the serial port is defective, the modem is
  774.                no longer functioning or a cable problem exists.
  775.  
  776. RETURN:        EOF = Transmit timeout error
  777.                0 = Character transmitted.
  778.  
  779. EXAMPLE:
  780.  
  781. #include <stdio.h>
  782. #include "byexface.h"
  783.  
  784. /*
  785. ** Disable the remote callers ^S and ^C keys and send a string
  786. ** to the remote caller. This will prevent the caller from
  787. ** being able to pause or break the program from running. Note,
  788. ** however, that the local console can still press Ctrl-Break
  789. ** and stop the program. Carefully coded applications should
  790. ** trap for Ctrl-Break on the local keyboard as well.
  791. */
  792.  
  793. main()
  794.      {
  795.      char buf[64];
  796.      int i;
  797.  
  798.     _bye_setbreak(CTRL_NOTRAP); /* dont trap/filter ^C & ^S data */
  799.     strcpy(buf, "This a string from BYEXFACE ....\n");
  800.  
  801.     for(i = 0; i < strlen(buf); i++)    /* send for string len */
  802.           _bye_putc((int)buf[i]);       /*  send a byte of data */
  803.  
  804.     _bye_setbreak(CTRL_TRAP);   /* enable trap ^C & ^S data */
  805.     exit(0);                    /* exit back to DOS */
  806.     }
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822. FUNCTION:      int _bye_dtr(f)
  823.  
  824. PARAMETERS:    int f;    toggle dtr line (0=inactive, 1=active)
  825.  
  826. PURPOSE:       This function is used to hangup the modem by
  827.                toggling the DTR/CTS line to the modem.
  828.  
  829. RETURN:        void
  830.  
  831.  
  832.  
  833. FUNCTION:      int _bye_warmboot()
  834.  
  835. PARAMETERS:    void
  836.  
  837. PURPOSE:       Hangup on the caller and warm boot the system
  838.                via Alt-Ctrl-Del bios routine. This causes
  839.                BYE-PC to turn execution over to the BIOS for
  840.                a system re-boot. Note that this function calls
  841.                _bye_dtr() before warm booting to ensure that
  842.                the modem is hung up.
  843.  
  844. RETURN:        void
  845.  
  846.  
  847.  
  848. EXAMPLE:
  849.  
  850. #include <stdio.h>
  851. #include "byexface.h"
  852.  
  853. main()
  854.     {
  855.     printf("\n\nGoodbye...Please Call Again...\n\n");
  856.  
  857.     _bye_warmboot();
  858.     }
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877. FUNCTION:      int _bye_getcd()
  878.  
  879. PARAMETERS:    void
  880.  
  881. PURPOSE:       This function is used to hangup return the stat-
  882.                us of the carrier detect (CD) line to the modem.
  883.                This is used to test for carrier detect while
  884.                carrier check is disabled. This allows checking
  885.                for carrier while writing to disk files with
  886.                carrier check disabled via _bye_setcd().
  887.  
  888.                NOTE: This use rs-232 pin 20 to check from the
  889.                modem and it must be connected for this function
  890.                to operate properly.
  891.  
  892. RETURN:        0 = no carrier detect found
  893.                1 = carrier detect found (CD).
  894.  
  895. EXAMPLE:
  896.  
  897. #include <stdio.h>
  898. #include "byexface.h"
  899.  
  900. /*
  901. ** display the current status of the carrier detect line
  902. */
  903.  
  904. main()
  905.     {
  906.     rtn = _bye_getcd();       /* read CD status line */
  907.     if (rtn)
  908.           printf("Carrier Found...\n");
  909.     else
  910.           printf("No Carrier Found...\n");
  911.     }
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932. FUNCTION:      void _bye_setcd(f)
  933.  
  934. PARAMETERS:    int f;    (0=ingnore CD, 1=re-boot if CD false)
  935.  
  936. PURPOSE:       This function is used to disable carrier checking
  937.                from the modem. It's main purpose is to prevent
  938.                the system from re-booting while writing to a file
  939.                on disk. Carrier checking should be disabled and
  940.                checked via '_bye_getcd()' while writing to disk.
  941.  
  942. RETURN:        void
  943.  
  944. EXAMPLE:
  945.  
  946. #include <stdio.h>
  947. #include "byexface.h"
  948.  
  949. /* Open file 'temp.dat' and fill it with 1k of binary data.
  950. ** Make sure that the system does not re-boot if carrier is
  951. ** lost while writing to disk.
  952. */
  953.  
  954. main()
  955.      {
  956.      int i, c;
  957.      FILE *fp;
  958.  
  959.      if ((fp = fopen("TEST.DAT", "wb")) == NULL)
  960.           exit(1);
  961.      _bye_setbreak(CTRL_NOTRAP);
  962.      _bye_setcd(0);                /* disable carrier checking */
  963.      _bye_stdin(0);
  964.      _bye_stdout(0);
  965.      for (i = 0; i < 1024; i++)    /* write 1k of data */
  966.           {
  967.           while(!_bye_rxsize() && _bye_getcd());
  968.           if (!_bye_getcd())       /* check for carrier good */
  969.                {
  970.                printf("\n** CARRIER LOST - CLOSING FILE **\n");
  971.                break;
  972.                }
  973.           else
  974.               {
  975.               c = _bye_getc();          /* get a character */
  976.               fprintf(fp, "%c", c);     /* write to disk */
  977.               }
  978.           }
  979.      fclose(fp);              /* now close the file */
  980.      _bye_setcd(1);           /* re-enable carrier checking */
  981.      _bye_setbreak(CTRL_TRAP);
  982.      _bye_stdin(1);
  983.      _bye_stdout(1);
  984.      }
  985.  
  986.  
  987. FUNCTION:      void _bye_rxflush()
  988.  
  989. PARAMETERS:    void
  990.  
  991. PURPOSE:       This function clears all data from the rx-queue
  992.                and resets the count to zero.
  993.  
  994. RETURN:        void
  995.  
  996.  
  997.  
  998. FUNCTION:      int _bye_rxsize()
  999.  
  1000. PARAMETERS:    void
  1001.  
  1002. RETURN:        Size of receive data queue.
  1003.  
  1004. PURPOSE:       Returns the size of the receive data queue in
  1005.                bytes. The maximum size of the receive data queue
  1006.                depends on the configuration BYE-PC.
  1007.  
  1008. EXAMPLE:
  1009.  
  1010. #include <stdio.h>
  1011. #include "byexface.h"
  1012.  
  1013. /* Allow a 128 bytes of data to collect in the receive data
  1014. ** queue and move it to a local buffer for checksum calculation.
  1015. */
  1016.  
  1017. main()
  1018.      {
  1019.      int i;
  1020.      unsigned checksum;
  1021.      char buf[130];
  1022.  
  1023.      _bye_rxflush();            /* make sure rx-queue is empty */
  1024.      _bye_setbreak(CTRL_NOTRAP);
  1025.      _bye_stdin(0);        /* disable screen & keybd patch */
  1026.      _bye_stdout(0);
  1027.  
  1028.      while(_bye_rxsize() < 128);    /* let 128 bytes collect */
  1029.      for (i = 0; i < 128; i++)          /* move it to buffer */
  1030.           buf[i++] = _bye_getc();
  1031.  
  1032.      checksum = 0;                      /* compute checksum */
  1033.      for (i = 0; i < 128; i++)
  1034.           checksum += buf[i];
  1035.  
  1036.      _bye_stdin(1);        /* re-enable screen & keybd merge */
  1037.      _bye_stdout(1);
  1038.      _bye_setbreak(CTRL_TRAP);
  1039.      }
  1040.  
  1041.  
  1042. FUNCTION:      int _bye_baud()
  1043.  
  1044. PARAMETERS:    void
  1045.  
  1046. PURPOSE:       Returns the baud rate of the call on line. When
  1047.                BYE-PC logs on a caller, the baud rate is de-
  1048.                termined and stored for access by '_bye_baud()'.
  1049.                This is mainly used for calculating file trans-
  1050.                mission times for file transfer protocols.
  1051.  
  1052. RETURN:        0 = 300 bps
  1053.                1 = 1200 bps
  1054.                2 = 2400 bps
  1055.                3 = 9600 bps
  1056.  
  1057. EXAMPLE:
  1058.  
  1059. #include <stdio.h>
  1060. #include "byexface.h"
  1061.  
  1062. /*
  1063. ** Display the baud rate of the caller presently on line
  1064. */
  1065.  
  1066. main()
  1067.     {
  1068.     int bps;
  1069.  
  1070.     switch(_bye_baud())       /* get baud rate from BYE */
  1071.         {
  1072.         case 0:
  1073.             bps = 300;
  1074.             break;
  1075.         case 1:
  1076.             bps = 1200;
  1077.             break;
  1078.         case 2:
  1079.             bps = 2400;
  1080.             break;
  1081.         default:
  1082.             bps = 9600;
  1083.             break;
  1084.         }
  1085.     printf("\nBaud Rate for this call: %d bps\n", bps);
  1086.     }
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097. FUNCTION:      void _bye_setbreak(f)
  1098.  
  1099. PARAMETERS:    int f;    (break state flag)
  1100.  
  1101.          Valid States:
  1102.  
  1103.          CTRL_NOBRK  = 0 -> ignore ^C and ^S keys from remote
  1104.          CTRL_BRK    = 1 -> check for ^C and ^S keys
  1105.          CTRL_NOTOUT = 2 -> disable 1 min timeout on ^S
  1106.          CTRL_TOUT   = 3 -> enable 1 min timeout on ^S
  1107.          CTRL_NOTRAP = 4 -> disable all key trapping (^C & ^S).
  1108.          CTRL_TRAP   = 5 -> enable key trapping (^C & ^S).
  1109.  
  1110. PURPOSE:       This function is used to control ^S & ^C keys from
  1111.                the remote caller and to disable timeout on ^S.
  1112.                This function must be disabled before transferring
  1113.                binary files, to prevent ^S and ^C data from
  1114.                being interpretted.
  1115.  
  1116. RETURN:        void
  1117.  
  1118. EXAMPLE:
  1119.  
  1120. #include <stdio.h>
  1121. #include "byexface.h"
  1122.  
  1123. main()
  1124.      {
  1125.      int i, c;
  1126.      FILE *fp;
  1127.  
  1128.      if ((fp = fopen("TEST.DAT", "wb")) == NULL)
  1129.           exit(1);
  1130.      _bye_setbreak(CTRL_NOTRAP);   /* dont trap ^C & ^S */
  1131.      _bye_setcd(0);                /* disable carrier checking */
  1132.      for (i = 0; i < 1024; i++)    /* write 1k of data */
  1133.           {
  1134.           while(!_bye_rxsize() && _bye_getcd());
  1135.           if (!_bye_getcd())       /* check for carrier good */
  1136.                {
  1137.                printf("\n** CARRIER LOST - CLOSING FILE **\n");
  1138.                break;
  1139.                }
  1140.           else
  1141.               {
  1142.               c = _bye_getc();          /* get a character */
  1143.               fprintf(fp, "%c", c);     /* write to disk */
  1144.               }
  1145.           }
  1146.      fclose(fp);              /* now close the file */
  1147.      _bye_setcd(1);           /* re-enable carrier checking */
  1148.      _bye_setbreak(CTRL_TRAP);
  1149.      }
  1150.  
  1151.  
  1152. FUNCTION:      void _bye_stdin(f)
  1153.  
  1154. PARAMETERS:    int f;    (bios keyboard rx-data merge flag)
  1155.                          (1=data rx'ed merged to stdin)
  1156.                          (0=data rx'ed is not merged)
  1157.  
  1158. PURPOSE:       This function is used to control merging data
  1159.                to the keyboard at the bios level. All modem data
  1160.                received is treated the same as keys pressed at
  1161.                the local keyboard. This is provided to disable
  1162.                the INT16 bios patch so data can be transferred.
  1163.  
  1164. RETURN:        void
  1165.  
  1166. EXAMPLE:
  1167.  
  1168. #include <stdio.h>
  1169. #include "byexface.h"
  1170.  
  1171. /* Allow a 128 bytes of data to collect in the receive data
  1172. ** queue and move it to a local buffer for checksum calculation.
  1173. */
  1174.  
  1175. main()
  1176.      {
  1177.      int i;
  1178.      unsigned checksum;
  1179.      char buf[130];
  1180.  
  1181.      _bye_rxflush();            /* make sure rx-queue is empty */
  1182.      _bye_setbreak(CTRL_NOTRAP);
  1183.      _bye_stdin(0);        /* disable screen & keybd patch */
  1184.      _bye_stdout(0);
  1185.  
  1186.      while(_bye_rxsize() < 128);    /* let 128 bytes collect */
  1187.      for (i = 0; i < 128; i++)          /* move it to buffer */
  1188.           buf[i++] = _bye_getc();
  1189.  
  1190.      checksum = 0;                      /* compute checksum */
  1191.      for (i = 0; i < 128; i++)
  1192.           checksum += buf[i];
  1193.  
  1194.      _bye_stdin(1);        /* re-enable screen & keybd merge */
  1195.      _bye_stdout(1);
  1196.      _bye_setbreak(CTRL_TRAP);
  1197.      }
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207. FUNCTION:      void _bye_stdout(f)
  1208.  
  1209. PARAMETERS:    int f;    (bios screen tx-data merge flag)
  1210.                          (1=data sent to screen tx'ed)
  1211.                          (0=data sent to screen not tx'ed)
  1212.  
  1213. PURPOSE:       This function is used to control merging data
  1214.                sent to the screen. If enabled, all characters
  1215.                printed to the screen via INT10 TTY, are sent
  1216.                to the modem as well. If disabled, prints to
  1217.                stdout are sent to screen only.
  1218.  
  1219. RETURN:        void
  1220.  
  1221. EXAMPLE:
  1222.  
  1223. #include <stdio.h>
  1224. #include "byexface.h"
  1225.  
  1226. /* Allow a 128 bytes of data to collect in the receive data
  1227. ** queue and move it to a local buffer for checksum calculation.
  1228. */
  1229.  
  1230. main()
  1231.      {
  1232.      int i;
  1233.      unsigned checksum;
  1234.      char buf[130];
  1235.  
  1236.      _bye_rxflush();            /* make sure rx-queue is empty */
  1237.      _bye_setbreak(CTRL_NOTRAP);
  1238.      _bye_stdin(0);        /* disable screen & keybd patch */
  1239.      _bye_stdout(0);
  1240.  
  1241.      while(_bye_rxsize() < 128);    /* let 128 bytes collect */
  1242.      for (i = 0; i < 128; i++)          /* move it to buffer */
  1243.           buf[i++] = _bye_getc();
  1244.  
  1245.      checksum = 0;                      /* compute checksum */
  1246.      for (i = 0; i < 128; i++)
  1247.           checksum += buf[i];
  1248.  
  1249.      _bye_stdin(1);        /* re-enable screen & keybd merge */
  1250.      _bye_stdout(1);
  1251.      _bye_setbreak(CTRL_TRAP);
  1252.      }
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262. FUNCTION:      unsigned _bye_vers()
  1263.  
  1264. PARAMETERS:    void
  1265.  
  1266. PURPOSE:       Return the version/revison level of BYE-PC
  1267.                currently running.
  1268.  
  1269. RETURN:        lsb = revision number
  1270.                msb = version number
  1271.  
  1272.  
  1273.  
  1274. FUNCTION:      void _bye_version(ver, rev)
  1275.  
  1276. PARAMETERS:    int *ver, *rev;     (buffers to place version in)
  1277.  
  1278. PURPOSE:       Sets the version/revison level of BYE-PC in the
  1279.                int buffer addresses passed.
  1280.  
  1281. RETURN:        void
  1282.  
  1283.  
  1284.  
  1285. EXAMPLE:
  1286.  
  1287. #include <stdio.h>
  1288. #include "byexface.h"
  1289.  
  1290. /*
  1291. ** Ask BYE-PC for the version number currently operating.
  1292. */
  1293.  
  1294. main()
  1295.      {
  1296.      int rev, ver;
  1297.      unsigned x;
  1298.  
  1299.        /* try the hard way first.... */
  1300.  
  1301.      x = _bye_vers();
  1302.      ver = (int)(x >> 8);
  1303.      rev = (int)(x & 0x00ff);
  1304.      printf("\nBYE-PC Version %1d.%-2.2d\n", ver, rev);
  1305.  
  1306.        /* or use '_bye_version()' for easier access */
  1307.  
  1308.      _bye_version(&ver, &rev);
  1309.      printf("\nBYE-PC Version %1d.%-2.2d\n", ver, rev);
  1310.      }
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317. FUNCTION:      int _bye_getnulls()
  1318.  
  1319. PARAMETERS:    void
  1320.  
  1321. PURPOSE:       Return the number of nulls presently active. This
  1322.                causes BYE-PC to send 'n' (0-9) to the remote
  1323.                station after each feed (LF) printed through the
  1324.                BIOS write to video INT10.
  1325.  
  1326. RETURN:        Number of nulls active 0 through 9.
  1327.  
  1328.  
  1329.  
  1330. FUNCTION:      void _bye_setnulls()
  1331.  
  1332. PARAMETERS:    void
  1333.  
  1334. PURPOSE:       Sets the number of nulls sent to the remote after
  1335.                each line feed printed.
  1336.  
  1337. RETURN:        void
  1338.  
  1339.  
  1340.  
  1341. EXAMPLE:
  1342.  
  1343. #include <stdio.h>
  1344. #include <conio.h>
  1345. #include "byexface.h"
  1346.  
  1347. /*
  1348. ** Ask BYE-PC for the number of nulls active and ask the user
  1349. ** what to set it too.
  1350. */
  1351.  
  1352. main()
  1353.      {
  1354.      int n;
  1355.  
  1356.      n = _bye_getnulls();
  1357.      printf("\nCurrent Nulls Setting: d\n", n);
  1358.  
  1359.      printf("\nEnter new value <RET=0>: ");
  1360.      n = getch();
  1361.      if (n >= '0' && n <= '9')
  1362.           {
  1363.           n -= '0'
  1364.           _bye_setnulls(n);
  1365.           }
  1366.      printf("\nNulls Set to %d\n", _bye_getnulls());
  1367.      }
  1368.  
  1369.  
  1370.  
  1371.  
  1372. FUNCTION:      int _bye_getcsw()
  1373.  
  1374. PARAMETERS:    void
  1375.  
  1376. PURPOSE:       Return the present caller status word (CSW)
  1377.                setting. (Refer to CSW section of manual).
  1378.  
  1379. RETURN:        16 bit CSW
  1380.  
  1381.  
  1382.  
  1383. FUNCTION:      void _bye_setcsw(s)
  1384.  
  1385. PARAMETERS:    int s;   (16 bit caller status word)
  1386.  
  1387. PURPOSE:       Sets the caller status word to a new value.
  1388.  
  1389. RETURN:        void
  1390.  
  1391.  
  1392.  
  1393. EXAMPLE:
  1394.  
  1395. #include <stdio.h>
  1396. #include <conio.h>
  1397. #include "byexface.h"
  1398.  
  1399. /*
  1400. ** Read the CSW and display the present status, then enable file
  1401. ** transmit and receive flags.
  1402. */
  1403.  
  1404. #define B_FILE_TX   4
  1405. #define B_FILE_RX   8
  1406.  
  1407. main()
  1408.      {
  1409.      int s;
  1410.  
  1411.      s = _bye_getcsw();
  1412.      printf("\nOld Caller Status Word: %-4.4x\n", s);
  1413.  
  1414.           /* set transmit and receive flags */
  1415.  
  1416.      s = s | B_FILE_TX | B_FILE_RX;
  1417.      _bye_setcsw(s);
  1418.  
  1419.      printf("\nNew Caller Status Word: %-4.4x\n", s);
  1420.  
  1421.      printf("\nFILE Transmit/Receive Enabled...\n");
  1422.      }
  1423.  
  1424.  
  1425.  
  1426.  
  1427. FUNCTION:      int _bye_gettimer()
  1428.  
  1429. PARAMETERS:    void
  1430.  
  1431. PURPOSE:       Return the number of minutes caller has been on
  1432.                line and since carrier detect was acknowleged.
  1433.  
  1434. RETURN:        number of minutes online (0-255)
  1435.  
  1436.  
  1437.  
  1438. EXAMPLE:
  1439.  
  1440. #include <stdio.h>
  1441. #include <conio.h>
  1442. #include "byexface.h"
  1443.  
  1444. /*
  1445. ** Tell caller how long he has been online and how much time
  1446. ** is remaining.
  1447. */
  1448.  
  1449. main()
  1450.      {
  1451.      int l, t;
  1452.  
  1453.      l = _bye_gettimeon();         /* original time limit */
  1454.      t = _bye_gettimer();          /* time already used   */
  1455.  
  1456.      if (!l)
  1457.           printf("\nUnlimited Time...\n");
  1458.      else
  1459.           {
  1460.           printf("\nMaximum Time Allowsd: %u\n", l);
  1461.           printf("\nMinutes Since Logon : %u\n", t);
  1462.           printf("\nTime remaining      : %u\n", t - l);
  1463.           }
  1464.  
  1465.  
  1466.  
  1467.  
  1468.  
  1469.  
  1470.  
  1471.  
  1472.  
  1473.  
  1474.  
  1475.  
  1476.  
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482. FUNCTION:      void _bye_settimeon(mins)
  1483.  
  1484. PARAMETERS:    int minutes; (0-255 max time limit, 0=unlimited)
  1485.  
  1486. PURPOSE:         Set the time in minutes that the caller may  re-
  1487.                  main on line. The time limit becomes effective
  1488.                  as soon as this function is called. If the time
  1489.                  limit is set to 0, the time limit is unlimited.
  1490.  
  1491. RETURN:        void
  1492.  
  1493.  
  1494.  
  1495. FUNCTION:      int _bye_gettimeon()
  1496.  
  1497. PARAMETERS:    int minutes; (0-255 max time limit, 0=unlimited)
  1498.  
  1499. PURPOSE:       Return the original time limit value set by
  1500.                _bye_settimeon(). This value is not decremented
  1501.                by the system timer, this only allows you to
  1502.                read what the time limit was set to.
  1503.  
  1504. RETURN:        void
  1505.  
  1506.  
  1507. EXAMPLE:
  1508.  
  1509.  
  1510. #include <stdio.h>
  1511. #include <conio.h>
  1512. #include "byexface.h"
  1513.  
  1514. /*
  1515. ** Tell caller how long he has been online and set the limit
  1516. ** for 5 minutes longer before disconnect.
  1517. */
  1518.  
  1519. main()
  1520.      {
  1521.      int s;
  1522.  
  1523.      printf("\nMinutes Online: %d\n", _bye_gettimer());
  1524.  
  1525.      printf("\nYou now have five minutes left...\n");
  1526.  
  1527.      _bye_settimeon(5);
  1528.      }
  1529.  
  1530.  
  1531.  
  1532.  
  1533.  
  1534.  
  1535.  
  1536.  
  1537. FUNCTION:      void _bye_setname(s)
  1538.  
  1539. PARAMETERS:    char *s;  (ptr to string up to 63 characters)
  1540.  
  1541. PURPOSE:       This function loads the string pointed to by 's'
  1542.                into the resident portion of BYE.COM.  This allows
  1543.                the  ALT-C key to display the caller on line while
  1544.                in DOS. The string must be null terminated.
  1545.  
  1546. RETURN:        void
  1547.  
  1548.  
  1549.  
  1550. FUNCTION:      void _bye_getname(s)
  1551.  
  1552. PARAMETERS:    char *s;  (ptr to string up to 63 characters)
  1553.  
  1554. PURPOSE:       This function loads the buffer pointed to by 's'
  1555.                from the resident portion of BYE.COM.  This allows
  1556.                allows reading the users name currently online  by
  1557.                other programs while in DOS.
  1558.  
  1559. RETURN:        void
  1560.  
  1561.  
  1562.  
  1563. EXAMPLE:
  1564.  
  1565. #include <stdio.h>
  1566. #include "byexface.h"
  1567.  
  1568. /* Allow a 128 bytes of data to collect in the receive data
  1569. ** queue and move it to a local buffer for checksum calculation.
  1570. */
  1571.  
  1572. main()
  1573.      {
  1574.      int i;
  1575.      char buf[65];
  1576.  
  1577.     _bye_setname("John, Doe");    /* set callers name */
  1578.  
  1579.         /* now read it back */
  1580.  
  1581.     _bye_getname(buf);
  1582.     printf("Caller on line:%s\n", buf);
  1583.     }
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.