home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / fossil / fosil006.arc / FOSIL006.DOC < prev   
Encoding:
Text File  |  1989-11-05  |  15.4 KB  |  380 lines
  1. FLATWARE Presents:  Documentation, Utah-style!
  2.  
  3. This file is the beta-version documentation for the following programs:
  4.  
  5. FOSIL006.Com
  6.  
  7.  
  8.  
  9. What it does:
  10.  
  11. FOSIL006.Com will do a number of "usefull" things.  Most important is
  12. the ability to initialize and deinitialize the FOSSIL driver.  The
  13. program will also send a string to the modem on any com port, if there
  14. is a CD.  The program has the ability to turn the DTR on and off on any
  15. port and it can also enable and disable the watchdog function of the
  16. FOSSIL driver on any port.  FOSIL006.Com has the ability to use any of
  17. the standard com ports (com1: through com16:), although the acutal
  18. ability to use the higher com ports depends on the FOSSIL driver.
  19.  
  20.  
  21. Who needs it:
  22.  
  23. 99.9% of all SysOp's will never need this program.  However, for the
  24. three of us who do, it is indespensable.  The people who may need this
  25. program are SysOps who run Opus (or any BBS which uses the FOSSIL *and*
  26. is capable of running "doors" or outside programs) and DoubleDOS with
  27. doors or outside programs running in the *other* DoubleDOS partition.
  28. This program is only needed *if* the doors use the FOSSIL driver.
  29. However, to these people, the doors usually won't run right if this
  30. program (or programs like it) isn't used.
  31.  
  32.  
  33. Get to the point!:
  34.  
  35. Here's the problem:  Opus (for example) drops out to dos to run the
  36. batch file which switches partitions and runs the doors "on the other
  37. side" of DoubleDOS.  Fine.  The batch file "sends" the command to the
  38. other side to start another batch file in the other partition.  Still
  39. fine.  The door runs, and it uses the FOSSIL, and everything *usually*
  40. works well.  Then...the program exits back to the batch file and the
  41. batch file tells the other partition to start up again (see examples
  42. somewhere else in this file (probably)).  No problem.  The other side
  43. fires back up and exits back to Opus.  Oops!  Opus comes up, pukes and
  44. dies.  Well, that's what has happened in my case, anyway.  Here's what
  45. is going wrong:  When the FOSSIL-usin' program in the other partition
  46. starts up, it "steals" the FOSSIL away from the other partition, and
  47. when it exits, Opus can't get the FOSSIL back.  This makes Opus go nuts.
  48.  
  49. Here's the fix:  Turn off the FOSSIL in the Opus partition *before* you
  50. switch over to the other side, *then* turn the FOSSIL back on over there
  51. before you run the door.  That way the door doesn't have to steal the
  52. FOSSIL away.  After the door exits, turn the FOSSIL off in the "other"
  53. partition (where you just ran the door from) and switch back to Opus.
  54. Before you exit back to Opus from the batch file, turn the FOSSIL on
  55. again, and Opus will be happy.
  56.  
  57. Here's how:  Turning the FOSSIL on and off is where my program comes in.
  58. Here are examples of how to use FOSIL006.Com with Kram Mail:
  59.  
  60. ---Kram.Bat:
  61.  
  62. Rem * Batch file to run Kram Mail from the other DDOS partition on com1:
  63. echo off
  64.  
  65. Rem Check for activity in the other partition
  66. FlipStat.Com
  67. if errorlevel 1 goto busy
  68. Rem FlipStat will exit with errorlevel 1 or better if all is not well
  69.  
  70. Rem Turn the FOSSIL off before you change over
  71. FOSIL006.Com f 0
  72.  
  73. Rem Send the command to start the batch file in the other partition
  74. Send Kram1.Bat
  75.  
  76. Rem Watch the other side or it won't work right
  77. Switch
  78.  
  79. Rem Run a "child process" here while Kram Mail runs over there
  80. Command.Com
  81.  
  82. Rem all done over there, fire the FOSSIL up again and exit back to Opus
  83. FOSIL006.Com n 0
  84.  
  85. Rem Skip the message about being busy, and we're all done
  86. goto End
  87.  
  88. Rem Tell the user that the program is not available right now
  89. :Busy
  90. FOSIL006.Com s 0 Sorry, Kram Mail is not available now, please try later.
  91.  
  92. Rem  If the other side is busy, we can just fall through and exit because
  93. Rem  we checked the FlipStat before we turned the FOSSIL off, so we don't
  94. Rem  need to turn it back on again.
  95.  
  96. :End
  97.  
  98. Rem  *ALWAYS* put an exit at the end of your batch files.  With Opus, if
  99. Rem  don't, you'll get those crazy message numbers.
  100.  
  101. exit
  102.  
  103. ---
  104.  
  105. ---Kram1.Bat
  106.  
  107. Rem Batch file to run Kram Mail from the other DDOS partition on com1:
  108. echo off
  109.  
  110. Rem Turn the other partition off just in case there isn't enough ram to
  111. Rem run the shell "child" over there.
  112. Suspend.Com
  113.  
  114. Rem Turn the FOSSIL on now over here since it should be available.
  115. FOSIL006.Com n 0
  116.  
  117. Rem Run the door, and you're almost done
  118. KramMail
  119.  
  120. Rem Turn the FOSSIL off and we're outta here
  121. FOSIL006.Com f 0
  122.  
  123. Rem Well, turn the other side back on
  124. Resume.Com
  125.  
  126. Rem Kill the child process over there
  127. Send exit
  128.  
  129. Rem And put the display back in the right place
  130. Switch
  131.  
  132. Rem *Now* you can quit
  133.  
  134. exit
  135.  
  136. ---
  137.  
  138.  
  139. New stuff on the block:
  140.  
  141. There have been a couple of changes since v0.004.  The program is "space-
  142. smart" now.  That means that it knows how to deal with spaces in the command
  143. line.  So now you can do something like this:
  144.  
  145. FOSIL006 F 0
  146.  
  147. And the program will parse the line properly.  There is a special note here.
  148. For the most part, the command line used with versions 0.004 and earlier can
  149. still be used by version 0.006.  However, when you are sending a string
  150. to the modem, the format has changed slightly.  Here is another example:
  151.  
  152. FOSIL006 S 0 Please wait for the door to open.
  153.             ^-------,
  154. Look at this space -'  It is now manditory to put a space between the port
  155. number and the first character of the string.  If you don't put the space
  156. there, the program will hack off the first character of your string.
  157.  
  158. Note:
  159. Only the first space of the string is ignored.  If you put more than one space
  160. at the beginning of the string, all but the first space will be sent to the
  161. modem.  One more example:
  162.  
  163. FOSIL006 S 0     Please wait for the door to open.
  164.  
  165. Would send "    Please wait for the door to open." to the modem.
  166.  
  167.  
  168. Added features:
  169.  
  170. Two new actions have been added to the program.  Command and Get baud rate.
  171. Both of these actions are listed in the Actions List.
  172.  
  173.  
  174. Actions list:
  175.  
  176. This section gives you a basic idea of what each of the commands does.  The
  177. general format for FOSIL006 is:
  178.  
  179.      FOSIL006 A P [string]
  180.  
  181. Boot the system
  182.     This action will reboot the computer.  Basically the same as a "three-
  183.     fingered salute".  While it seems pointless (at least to me) to
  184.     specify a port on a re-boot, you must.  In other words, when you
  185.     reboot your computer with this action, you must still type
  186.  
  187.      FOSIL006 B 0
  188.  
  189.     or the program will report an error and exit without re-booting.
  190.  
  191. C Send command
  192.     This is the sister-action to Send string.  When the program is requested
  193.     to send a command, then if there is a carrier detected (CD or DCD), then
  194.     the program will not send the command.  However, if there is NO carrier
  195.     detected, then the command will be sent to the modem.
  196.  
  197. Disable watchdog
  198.     This action will turn the FOSSIL watchdog function off, if it was turned
  199.     on.  When turned on, the watchdog function will reboot the computer if
  200.     the user hangs up.
  201.  
  202. Enable watchdog
  203.     This action will turn the FOSSIL watchdog function on.  It is advisable to
  204.     turn the watchdog function on, anytime a user goes outside of the BBS.
  205.  
  206. F Disable FOSSIL
  207.     This action will turn the FOSSIL off.  There is a big section somewhere
  208.     else in this doc file which describes, in some detail, the usefullness
  209.     of this action.
  210.  
  211. Get baud rate
  212.     This action will return the current baud rate to which the FOSSIL is set.
  213.     The FOSSIL driver *MUST* be active when this action is used
  214.     (FOSIL006 N 0).  When using this action, the program will exit with
  215.     the errorlevel set to the value of the baud rate of the FOSSIL.  The
  216.     following values are returned for their baud rate equvalents:
  217.  
  218.          baud     errorlevel
  219.         38,400        38
  220.         19,200       192
  221.          9,600        96
  222.          4,800        48
  223.          2,400        24
  224.          1,200        12
  225.            600        60
  226.            300        30
  227.  
  228.     Please note that errorlevels for baud rates 38,400, 600, and 300 are
  229.     different from the rest.  38,400 baud should be errorlevel 384, however
  230.     the largest errorlevel which can be returned is 255.  300 baud should be
  231.     errorlevel 3, and 600 baud should be errorlevel 6, however these values
  232.     are reserved for error exits.
  233.  
  234.     NOTE:  It seems that Get baud rate only works with X00 v1.20c and
  235.            newer.  Evidently, earlier versions of X00 did not return the
  236.            correct baud rate.
  237.  
  238. Lower DTR
  239.     This action will drop the DATA TERMINAL READY line to the modem.  The
  240.     usual effect of this action will either hang up on a caller, or render the
  241.     modem incapable of answering the phone.
  242.  
  243. N Initialize FOSSIL
  244.     This action will turn the FOSSIL on.  There is a big section somewhere
  245.     else in this doc file which describes, in some detail, the usefullness
  246.     of this action.
  247.  
  248. Raise DTR
  249.     This action will raise the DATA TERMINAL READY line to the modem.  The
  250.     purpose of this action is usually to allow the modem to answer the phone.
  251.     With some modems, if the DTR line is low, the modem will not accept
  252.     commands from the computer.
  253.  
  254. Send string
  255.     This action will send the [string] listed in the command line format
  256.     (above) to the user, if there is a carrier detected on the given comm
  257.     port.  The command is also echoed to the local terminal.  If there is
  258.     a carrier detected, then the word "Sending:" will appear on the local
  259.     monitor, in front of the string.
  260.  
  261.  
  262. The action letter is not case-sensitive.
  263.  
  264.  
  265. "P" is the port number.  This is the com port, and it is a single digit,
  266. 0-9 and A-F, where 0 is com1:.
  267.  
  268. [string] is the user-defined string which will be sent to the port if
  269. the C or S actions are used.
  270.  
  271. If you run the program without a command line, you will get a brief
  272. summary of all commands.
  273.  
  274. If you ask FOSIL006.Com to turn the FOSSIL driver on, and it can't (for
  275. any reason), the program will exit with an errorlevel 1.
  276.  
  277. If you run FOSIL006.Com with incorrect parameters, the program will
  278. display an error message and exit with errorlevel 2.
  279.  
  280. If you run FOSIL006.Com with a bad action request, it will display an
  281. error message, and exit with errorlevel 3.
  282.  
  283. If you run FOSIL006.Com with a bad port number, it will display an error
  284. message and exit with errorlevel 4.
  285.  
  286. If you ask FOSIL006.Com to send a string to the modem, and you don't
  287. specify a string, it will display an error message and exit with
  288. errorlevel 5.
  289.  
  290. If you ask FOSIL006.Com to send a command to the modem, and you don't
  291. specify a string, it will display an error message and exit with
  292. errorlevel 6.
  293.  
  294. If you ask FOSIL006.Com to activate the watchdog function and there is
  295. no carrier detected on the requested comm port, then the program will
  296. display an error message and exit with errorlevel 7.
  297.  
  298. So that's:
  299.         errorlevel 7 if there is no carrier detected on a watchdog init
  300.         errorlevel 6 if there is no string on a "command" request
  301.         errorlevel 5 if there is no string on a "send" request
  302.         errorlevel 4 if there is a bad port number
  303.         errorlevel 3 if there is a bad action request
  304.         errorlevel 2 if there are bad parameters
  305.         errorlevel 1 if FOSIL006 n P can't init the FOSSIL driver on port P
  306.  
  307.  
  308. About the Send action.  This was an after thought, really.  I needed a
  309. way to send information to the com port when a user was online, so I
  310. could say something like, "Hold on a minute, the game will take a little
  311. while to load...".  At first I just used the "echo Hold on... > com1:"
  312. command from the batch file.  This had a real drawback because I use
  313. some of the doors when I am in local mode.  When I use the doors in
  314. local mode, and that line echos the string out to the com port, then the
  315. modem sees the string in command mode.  Sometimes, if you are really
  316. unlucky, you can send a command to the modem to dial the phone or do
  317. some other annoying thing.  What the send command does when you call it
  318. is that it looks at the com port and if there is a carrier detected
  319. (CD), then the program will send the string (according to the command
  320. line format above) to the modem.  If there is no CD (ie., nobody online)
  321. then the program will only print the string on the local screen.  It
  322. will work on any com port (I think--I don't have 10 com ports to test it
  323. with <ahem>).  If the send action does see a CD on the requested com
  324. port, then the program will print "Sending:" on the line before the
  325. string.  That way you can tell when the program is sending stuff out to
  326. the modem (you can watch the modem, too, but not if you have an internal
  327. <grin>).
  328.  
  329. It has been my experence that if you do not turn the FOSSIL on and off
  330. properly, when the FOSSIL-usin' program in the other partition runs, it
  331. will steal the FOSSIL and not give it back.  I don't know how it does
  332. that.  If you do not turn the FOSSIL off on the side where it is active,
  333. before you try to turn it on, on the other side, FOSIL006.Com will not
  334. be able to turn the FOSSIL on.  It simply doesn't have access to the
  335. FOSSIL.  Make sure that you turn the FOSSIL off on one side before you
  336. turn it on on the other side, or it won't work.
  337.  
  338. With the current versions of both OPUS!COMM and X00, you can specify how
  339. many ports to support at any one time.  If you tell the FOSSIL to
  340. only use one port, it will *not* limit the FOSSIL to only com1:.  It
  341. only limits the FOSSIL to one port at any one given time.  *huh*?  What
  342. I mean is that you can limit the FOSSIL to one port, but it can be *any*
  343. port you want (and have installed on your machine).  If you look at the
  344. format for calling FOSIL006.Com, you will notice that you can specify
  345. which com port to use (through com16:).  You must be kinda carefull with
  346. this.  If you tell FOSIL006.Com to turn on a port which doesn't exist,
  347. *boom*!  It will lock up your system, and it'll be big-red-switch time.
  348. Also, when you turn the FOSSIL on with a certain port (ie.  FOSIL006 n 2
  349. for com3:) you must turn it off of *that* port (ie. FOSIL006 f 2 *if*
  350. you did a FOSIL006 n 2 before) before you can use the FOSSIL with any
  351. other port.
  352.  
  353. This program is not perfect.  There are a lot of things which I would
  354. like to see it do (although it has come a long way since I first started
  355. coding it!).  For starters, the program can't do more than one thing at
  356. a time.  For instance, you can't turn on the FOSSIL, send a string, then
  357. turn the FOSSIL back off without running the program three times.  Also,
  358. the program can't tell if the FOSSIL is running when it sends a string.
  359. So there are still lots of places to go with it, but in the mean time,
  360. let me know what you think of it.
  361.  
  362. This program is still in beta test (and may be forever).  That way I
  363. don't have to admit that I have a release version with a bug in it
  364. <grin>.  If you find problems with this program, please send me a note
  365. and explain, in as much detail as possible, what is going on.  If you
  366. could send me your batch files, it would really help, too.  For bug
  367. reports and latest updates, I can be reached at:
  368.  
  369. Flatland Center, Home of FLATWARE  Opus 1:302/1.0  1-801-563-5359, HST
  370.  
  371. This program is Copyright, (C) 1989, by Dave Bell.  It has been released
  372. for public consumption.  You may not sell this program or make profit
  373. via its distribution.  No contribution is requested for its use.  It is
  374. free of charge!  Enjoy...
  375.  
  376.                                                 Dave Bell, SysOp
  377.                                                 Flatland Center
  378.                                                 November 5, 1989
  379.  
  380.