home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / MISC / DEMO510.ZIP / UTI300.INS / SLUTI.DOC < prev    next >
Text File  |  1999-01-25  |  13KB  |  320 lines
  1.  
  2. Searchlight UTI Driver  --  Version 3.0    (For Searchlight BBS 3.0 & Later)
  3.  
  4.  
  5. Introduction
  6.  
  7. Searchlight UTI is a Universal Text Interface driver for Searchlight BBS. 
  8. This version works with Searchlight 3.0 and later.
  9.  
  10. A UTI driver is a series of programs that can convert messages between the 
  11. format used by a particular BBS program and a "Universal" format that is 
  12. recognized by various application programs. The specification for UTI was 
  13. developed by Kip Compton for use with his MegaMail offline reader software 
  14. and PCRelay network software. The Searchlight UTI driver allows you to run 
  15. MegaMail, PCRelay and other UTI applications on your Searchlight BBS system.
  16.  
  17. The Searchlight UTI physically consists of seven separate EXE files which 
  18. perform various functions, as described below. These programs are command 
  19. line driven, produce no screen output, and are designed to be called by a 
  20. UTI application (such as MegaMail) rather than directly from DOS or from a 
  21. batch file.  
  22.  
  23.  
  24. Installation
  25.  
  26. The Searchlight UTI driver should be installed simply by copying all the 
  27. executable files into any directory in your system that's part of the 
  28. command search path (so that the programs can be executed from any 
  29. directory).
  30.  
  31. The UTI driver is compatible with single or multinode Searchlight BBS 
  32. systems.
  33.  
  34. UTI driver programs expect to find the CONFIG.SL2 file in the current 
  35. directory when run. The UTI programs will also recognize an environment 
  36. variable, SLBBS, which should be set equal to the directory where the 
  37. Searchlight CONFIG.SL2 file is located. For example:
  38.  
  39.       SET SLBBS=C:\BBS\NODE1
  40.  
  41. If this environment variable is set, the UTI programs will look for the 
  42. CONFIG file in C:\BBS\NODE1, unless a CONFIG.SL2 file exists in the current 
  43. directory, in which case it will be used instead.
  44.  
  45. On multiuser systems, please be sure that when DOORS execute from a particular 
  46. node, and use the UTI driver, that the UTI driver is accessing the CONFIG 
  47. file for that node. If you use the SET SLBBS environment parameter, each DOS
  48. environment in which a Searchlight node runs should have the parameter set 
  49. to point to its own CONFIG.SL2 file. For example, if you run Desqview, you 
  50. would want to SET SLBBS as part of a batch file that launches each SL task, 
  51. rather than in your AUTOEXEC file when booting the system.
  52.  
  53.  
  54.  
  55.                                   Programs
  56.  
  57. Here is a summary of the UTI programs and parameters. Note: in all examples 
  58. except UTILSTRD.EXE, the filename may be omitted. Omitting the filename 
  59. causes the output to go to the console (screen) instead of a text file.
  60.  
  61.  
  62. High Message Number
  63. -------------------
  64. UTIHIGH.EXE <subboard> <filename>
  65.  example: UTIHIGH GENERAL HIGHMSG.TXT
  66.  
  67. This program returns the number of the highest message in a given subboard, 
  68. as a plain text (decimal ASCII) number, to the speicifed output file (or to 
  69. the console if no output file is given).
  70.  
  71.  
  72. Message Export
  73. --------------
  74. UTIEXPRT.EXE <subboard> <startmsg> <filename>
  75.  example: UTIEXPRT SLBBS 245 MESSAGE.TXT
  76.  
  77. The export utility exports all messages from a subboard from the given 
  78. message number to the end of the subboard. The messages are exported to the 
  79. given text file.
  80.  
  81. The <startmsg> need not specify the number of an existing message (if it 
  82. does not, output starts at the next highest message).
  83.  
  84. The format of the output file is the standard UTI format given in the UTI 
  85. specifications (see below for more information).
  86.  
  87.  
  88. Message Import
  89. --------------
  90. UTIIMPRT.EXE <subboard> <filename>
  91.  example: UTIIMPRT MAIL INPUT.TXT
  92.  
  93. The import utility reads the messages in the given file and imports them 
  94. into the specified Searchlight subboard. As shown in this example, you can 
  95. import (and export) private mail by specifying the MAIL subboard.
  96.  
  97. The import file is in the same format as the output file produced by 
  98. UTIEXPRT.EXE.
  99.  
  100.  
  101. Subboard List
  102. -------------
  103. UTILIST.EXE <filename>
  104.  example: UTILIST SUBLIST.TXT
  105.  
  106. Generates a list of subboards.  The list is always output in alphabetical 
  107. order and contains all subboards as defined in the SETUP program.
  108.  
  109. Each entry is 3 plain text lines. Lines 1 and 2 contain the subboard's name 
  110. (one to eight characters). Line 3 contains the subboard's long description.
  111.  
  112.  
  113. Last Read Pointers
  114. ------------------
  115. UTILSTRD.EXE [READ|WRITE] <filename> <username>
  116.  example: UTILSTRD READ LAST.TXT FRANK LAROSA
  117.  example: UTILSTRD WRITE LAST.TXT FRANK LAROSA
  118.  
  119. The READ parameter generates a list of the user's highest message read 
  120. pointers for each subboard in which the user is a member. Subboards in which 
  121. the user is not a member are listed as -1. The output goes into the named 
  122. output file. Subboards are listed in the same order as UTILIST.
  123.  
  124. The WRITE parameter updates the user's last read pointers using the values 
  125. in the named input file, which must be in the same order as the output file.
  126.  
  127. Although Searchlight allows read and write priviledges to be specified 
  128. independently, this is not supported by UTI applications. Therefore, 
  129. UTILSTRD will report a last read value of -1 for any subboard to which a 
  130. user does not have full read/write access.  
  131.  
  132.  
  133. Version
  134. -------
  135. UTIVER.EXE <filename>
  136.  example: UTIVER VERSION.TXT
  137.  
  138. Generates the version number (currently 2) and tag line, to the named output 
  139. file. Version 2 is the version of the UTI specification with which this 
  140. driver is compatible; not the version number of the driver.
  141.  
  142.  
  143. UTI Door File
  144. -------------
  145. UTIDOOR.EXE <filename>
  146.  example: UTIDOOR UTIDOOR.TXT
  147.  
  148. Generates UTI door information into the named output file.  The UTIDOOR 
  149. output file contains five lines in plain text:
  150.  
  151.  Line 1: User name
  152.  Line 2: Actual BPS rate
  153.  Line 3: Com port (0-4)
  154.  Line 4: Locked DTE rate
  155.  Line 5: Time remaining in seconds
  156.  
  157. Note: UTIDOOR is not a UTI driver in the sense that it is not directly 
  158. called by UTI applications. UTIDOOR is normally run as the first command of 
  159. a batch file which executes a UTI application (such as Megamail) in order to 
  160. generate the above file, for use by the application. The standard name for 
  161. this file is UTIDOOR.TXT.
  162.  
  163.  
  164.                                    Notes:
  165.  
  166. Errors
  167. ------
  168. The Searchlight UTI drivers will exit with an error level between 0 and 5 
  169. indicating the result of the program execution. All drivers share a common 
  170. error level list, as follows:
  171.  
  172. Level    Problem & Suggested Action
  173. -----    --------------------------
  174.   0       No error
  175.  
  176.   1       Could not open system files. Either your CONFIG.SL2 file is not
  177.           in the current directory, or the paths it contains are invalid,
  178.           your SLBBS data files are missing or corrupt, or the UTI driver
  179.           could not open the files due to operating system restrictions
  180.           (such as out of file handles).
  181.  
  182.   2       Could not open specified subboard. The subboard name specified
  183.           on the command line is not a valid name, or a DOS error occured
  184.           when attempting to open the files.
  185.  
  186.   3       Could not open input or output file. For input files, this usually
  187.           means the file did not exist. On output, it means that DOS was
  188.           unable to create the file.
  189.  
  190.   4       Error in input file. The format of an input file was not the 
  191.           expected UTI file format.
  192.  
  193.   5       Subboard full. Reported by UTIIMPRT if a subboard is full. To
  194.           correct it, delete messages from the subboard, increase the 
  195.           subboard's maximum message count, or enable auto delete on the
  196.           subboard.
  197.  
  198.   6       Invalid username. Reported by UTILSTRD if the username specified
  199.           on the command line is not valid.
  200.  
  201.  
  202.  
  203. Handling Private Mail
  204. ---------------------
  205. Because of the way personal mail is stored in Searchlight BBS, the UTI 
  206. driver at this time does not support the transfer of private messages via a 
  207. network such as PCRelay. However, private mail transfers to an offline 
  208. reader program are supported.
  209.  
  210. When UTIIMPRT imports messages into a public subboard (ie. any subboard 
  211. other than the MAIL subboard), messages marked as PRIVATE in the message 
  212. header of the UTI import file will be discarded. Since there are no public/ 
  213. private flags on messages in Searchlight public subboards, all messages 
  214. exported from public subboards will have a PUBLIC designation in the UTI 
  215. output file.
  216.  
  217. The MAIL subboard is treated as an exception. UTIIMPRT and UTIEXPRT will 
  218. work in conjunction with the MAIL subboard so as to provide a means of 
  219. importing and exporting private mail for use with offline reader doors. 
  220. UTIIMPRT, when called with the MAIL subboard as a parameter, will import any 
  221. message in the input file (regardless of the PUBLIC/PRIVATE flag) as a 
  222. private Searchlight mail message to the addressee in the message header. If 
  223. the addressee does not have a mailbox in Searchlight, one will be created 
  224. when the message is imported.  
  225.  
  226. UTIEXPRT, when called on the MAIL subboard, always exports only new messages 
  227. addressed to the currently logged on user. UTIEXPRT reads the "times read" 
  228. counter in the message headers to determine which messages are new, and 
  229. ignores the starting message number specified on the command line. The 
  230. "times read" indicator is AUTOMATICALLY incremented whenever a message is 
  231. exported from the MAIL subboard, so that message may not be exported again.
  232.  
  233. Note that the UTILSTRD program will read and write a user's correct high 
  234. message read pointer from the MAIL subboard, although that number will have 
  235. no effect on UTIEXPRT.
  236.  
  237. UTILIST will show the "MAIL" subboard as a regular subboard. When setting up 
  238. a PCRelay network, care must be taken to prevent the application program 
  239. from exporting from or importing to the MAIL subboard.  When setting up an 
  240. offline mail system, users should be allowed to select the MAIL subboard as 
  241. they would any other subboard.  
  242.  
  243.  
  244.  
  245. Textual Considerations
  246. ----------------------
  247. The UTIEXPRT program reformats messages to a maximum column width of 72 
  248. characters, as is required by UTI applications. Quoted text is handled by 
  249. stripping off the initial ">" character and any additional non-textual 
  250. characters, reformatting the paragraph, and adding back the ">" characters.
  251.  
  252. UTIEXPRT exports up to 40 characters for the message subject, although many 
  253. UTI applications limit the subject field to 25. Expect that subject fields 
  254. longer than 25 characters may be truncated by UTI applications.
  255.  
  256. UTIIMPRT does not reformat messages. Expect messages imported by UTIIMPRT to 
  257. have a maximum width of 72 characters.
  258.  
  259. UTIEXPRT removes Searchlight color codes (two-letter codes beginning with a 
  260. backslash) from outgoing messages. No modifications are made to incoming 
  261. messages.  
  262.  
  263. INCLUDE files are not expanded when exporting messages.
  264.  
  265.  
  266.  
  267. UTIRFLAG.EXE
  268. ------------
  269. The Searchlight UTI driver does not include this program, which is defined 
  270. as an optional utility in the UTI specification. Searchlight does not 
  271. require this program since the UTIEXPRT program automatically updates the 
  272. appropriate counter when private messages are exported.
  273.  
  274.  
  275. UTI Import Speed
  276. ----------------
  277. Because importation of new messages is usually the UTI's biggest job in a 
  278. network environment, the speed at which messages are imported is an 
  279. important concern.
  280.  
  281. Message import speed will vary widely according to the speed of the 
  282. computer, content of the messages, and configuration of the message bases.  
  283. Import time will increase if compression is used (but the size of the 
  284. Searchlight message file will decrease). Import time will also increase if 
  285. auto purge of old messages is required during the import.  
  286.  
  287. Suggestions to decrease message import times:
  288.  
  289.   - Place the import file on a different drive than the SLBBS message
  290.     files (use a ram disk if possible). This is highly recommended for
  291.     large import jobs.
  292.  
  293.   - Use disk cache software, allocating all unused RAM to the cache.
  294.  
  295.   - Turn data compression off on the target subboards.
  296.  
  297.  
  298.  
  299. Developing UTI Applications
  300. ---------------------------
  301. Programmers who wish to develop message base applications can call UTI 
  302. programs from their main program in order to simplify the task of reading 
  303. and writing messages from the message bases. Applications that conform 
  304. strictly to UTI specifications will be compatible with any BBS system that 
  305. provides a UTI driver.
  306.  
  307. For more information on UTI file formats and specifications, developers 
  308. should contact:
  309.  
  310.    Kip Compton
  311.    PO Box 206
  312.    MIT Branch
  313.    Cambridge, MA 02139
  314.  
  315.    BBS: 703-690-7361
  316.                     
  317.                                                            -----------------
  318.                                                            Frank LaRosa 5/91
  319.  
  320.