home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / UBXP005.ZIP / UBXP.DOC < prev    next >
Text File  |  1990-12-17  |  19KB  |  520 lines
  1.  
  2.  
  3.                                -----------------                              
  4.  
  5.                                 UBX v0.05a.OS/2
  6.  
  7.                                -----------------                              
  8.  
  9.  
  10.                Users' Bulletin Express System for Maximus CBCS.               
  11.  
  12.  
  13.                             (C) David Luong, 1990.                            
  14.  
  15.                              All rights reserved.                             
  16.  
  17.  
  18.  
  19.                          FIDOnet address: 3:712/631.0                         
  20.  
  21.  
  22.  
  23. Distribution Rights 
  24. ^^^^^^^^^^^^^^^^^^^ 
  25. You  are  hereby granted a limited licence to use UBX in any way you see fit,
  26. and  to  distribute  it in any way you wish, so long as you don't charge  any
  27. money for it. If I catch you selling my software for profit, I'll sue you for
  28. every penny of it. So there!
  29.  
  30.  
  31. License fee & Support 
  32. ^^^^^^^^^^^^^^^^^^^^^ 
  33. Please  send  me  a  post  card if you decide to use UBX on your BBS. I enjoy
  34. collecting  postcards  from  _anywhere_ around the world and I mean ANYWHERE,
  35. doesn't matter even if it's from Sydney Australia! 
  36.  
  37. My postal address is included at the end of this document. 
  38.  
  39. If  you  have  any problems with the installation of UBX, then don't hesitate
  40. to contact me via netmail.
  41.  
  42.  
  43. Warranty 
  44. ^^^^^^^^ 
  45. I  grant no warranty of any kind, either expressed or implied. This includes,
  46. but is not limited to, implied warranties of merchantability, and fitness for 
  47. any   particular   purpose   with  respect  to  both  the  software  and  the
  48. documentation included in this package. 
  49.  
  50. In NO event shall I or any of EDEN BBS's principals be liable for any direct, 
  51. indirect,  consequential,  or  incidental  damages  arising out of the use or
  52. inability  to  use UBX even if I have been advised of the possibility of such
  53. damages or claim. 
  54.  
  55.  
  56. The  warranties  set forth above are in lieu of all other express and implied
  57. warranties,  whether  oral,  written,  or implied, and the remedies set forth
  58. above are your sole and exclusive remedies. 
  59.  
  60. This  document constitutes the entire agreement and understanding between the
  61. parties  and  supersedes any prior agreement or understanding whether oral or
  62. written, relating to the use of this package. 
  63.  
  64.  
  65. Absolute Requirements! 
  66. ^^^^^^^^^^^^^^^^^^^^^^ 
  67. * OS/2 v1.1 or higher is essential.
  68. * A  communications  library(COMM.DLL)  must  be present  to handle the high
  69. level  comm  port  communications  if UBX is to support remote callers. This
  70. 'COMM.DLL' library is distributed as part of the OS/2 Maximus CBCS package.
  71.  
  72.  
  73. Highlights 
  74. ^^^^^^^^^^ 
  75. *  UBX  is a _complete_ bulletins generation program. Both you(the sysop) and
  76. your callers can enter neatly presented bulletins with minimum fuss. 
  77.  
  78. *  UBX  is  a mini database - it's maintenance free! It comes with a separate
  79. auto  purging  and packing utility program. The optional purging of bulletins
  80. are based on the age of the bulletins and it's configurable. 
  81.  
  82. *  UBX bulletins can be viewed/listed forwards or backwards.
  83.  
  84. *  You  can  set  up as many UBX Special Interest Areas as you like. Each SIG
  85. area is maintained separately. 
  86.  
  87. *  UBX  has  an  'Express read-only'  mode. Ideal for inclusion as an Express
  88. News Items on your logon sequence.
  89.  
  90. *  The  built-in  line  editor for UBX is closely modeled around the look and
  91. feel  of  Maximus  CBCS  BORED line-editor but it is more advanced in its own
  92. right.  No  longer  do your callers have to put up with a totally   different
  93. editor for every door program they run! 
  94.  
  95. *  UBX comes with a separate utility program to add plain ASCII text files to
  96. the  UBX  bulletins  database.  Use your flavourite text editor to enter your
  97. bulletins,  then  use this utility to incorporate them into the UBX bulletins
  98. databases. 
  99.  
  100. *  All this and much much more............
  101.  
  102.  
  103. Special considerations 
  104. ^^^^^^^^^^^^^^^^^^^^^^ 
  105. *  UBX  in  its current form can only be run a single_line BBS. You can still
  106. use UBX in its 'Express READ_ONLY mode' on a multi-line setup provided that:
  107.  
  108.              You DON'T do anything funny like purging the UBX
  109.              database or killing/adding bulletins while someone
  110.              else is running UBX on one of your BBSs!
  111.  
  112.  
  113.  
  114. Contents of this archive 
  115. ^^^^^^^^^^^^^^^^^^^^^^^^
  116.     README.UBX     Last minute corrections to this manual.
  117.     UBXP.EXE       The  main UBX executable file.
  118.     UBXP.DOC       This document.
  119.     UBXP.HST       An UBX history file outlining the changes made between
  120.                    versions of UBX.OS/2
  121.     UBX.CTL        Sample UBX control file.
  122.     UBXDELP.EXE    The auto purge/pack utility for UBX.
  123.     UBX_ADDP.EXE   Utility to add text files to the UBX bulletin
  124.                    database.
  125.     UBX_NO.BBS     This file is displayed when the bulletin database
  126.                    is empty. Feel free to edit this file to your liking.
  127.     UBX_NO.GBS     The ANSI version of the above file.
  128.     SAMPLE.TXT     Sample text file to illustrate the format of
  129.                    an import file.
  130.  
  131.  
  132.  
  133. Demonstration: 
  134. ^^^^^^^^^^^^^^ 
  135. Here are a few things to try out before we go on with the detailed discussion 
  136. of the UBX package. 
  137.  
  138. For the purpose of this demonstration: 
  139.  
  140.     1. Copy all the files in this archive to a directory of your
  141.        choice.
  142.  
  143.     2. Modify the control file 'UBX.CTL'. For the purpose of the demo,
  144.        You'll only need to specify your name in UBX.CTL.
  145.  
  146.  
  147. Demo of the UBX Door Mode: 
  148. -------------------------- 
  149. *  Start up UBX in local mode like this:
  150.  
  151.       UBXP -K
  152.  
  153. *  Select '[R]ead bulletins' from the menu.
  154.  
  155. *  The  file  'UBX_NO.GBS'  will be shown seeing how the bulletin database is
  156. empty. 
  157.  
  158. *  You  might  like  to  have  a go at entering a couple of bulletins; select
  159. '[E]nter Bulletins' from the menu. 
  160.  
  161. Demo of the bulletins import utility:
  162. -------------------------------------
  163. Let's  add  a  couple  of  sample  bulletins to your UBX bulletin database by
  164. importing the text file 'SAMPLE.TXT'. 
  165.  
  166. * At the OS/2 prompt type:
  167.  
  168.       UBX_ADDP -isample.txt
  169.  
  170.  
  171. * That's it! It's done, simple eh? 
  172.  
  173. * Take  a  minute  to have a quick look  at the general format for the import
  174. text file, 'SAMPLE.TXT'. 
  175.  
  176. Demo of the UBX Express read mode: 
  177. ---------------------------------- 
  178. Now, let's see what the imported bulletins look like in a 'read-only' mode of 
  179. UBX. 
  180.  
  181. * At the OS/2 prompt type:
  182.  
  183.       UBXP -k -x+
  184.  
  185. * Like what you've seen so far? If the answer is 'yes', then read on! 
  186.  
  187.  
  188. UBX - The Users' Bulletin Express System 
  189. ---------------------------------------- 
  190. UBX operates in two distinct modes: 
  191.  
  192.         The Door mode:
  193.             Callers can enter bulletins here as well as read
  194.             bulletins entered by other callers.
  195.  
  196.             The sysop can delete individual bulletins through the
  197.             'Kill' option after reading them.
  198.  
  199.             This is the default mode unless you specifically
  200.             instructs UBX to operate in 'Express-read' mode with
  201.             a command line option.
  202.  
  203.         The Express mode:
  204.             This is a read-only mode, bulletins from a specific UBX
  205.             database will be displayed to the callers. The callers
  206.             can view the bulletins back and forth.
  207.  
  208.  
  209.  
  210. Command line syntax of UBX 
  211. ^^^^^^^^^^^^^^^^^^^^^^^^^^ 
  212.  
  213.        UBXP -Dfilename -X[ + | - ][ { | } ] -Pn -B -K -Tn
  214.  
  215.  
  216.        Command line options of UBX
  217.        ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  218.  
  219.            -d ,where filename is the prefix for the bulletins
  220.                database, if not given it defaults to 'UBX'.
  221.                This is how you can set up different sections(SIGs)
  222.                for UBX.
  223.  
  224.  
  225.            -x ,express 'read-only' mode. This can be utilised to
  226.                include a particular UBX bulletin database as part of
  227.                your logon sequence.
  228.  
  229.                For example:
  230.                -X- The '-' disables the 'Stop' option while reading.
  231.                -X+ The '+' leaves the 'Stop' option in place.
  232.                The optional '}' and '{' indicates the direction of
  233.                listing. '{' is reverse(ie. Latest first) and vice versa.
  234.                Default to the reverse listing '{'.
  235.  
  236.            -p ,specifies which comm port handle.
  237.                No default.
  238.  
  239.                IMPORTANT NOTE:
  240.                ---------------
  241.                * On a zero based comm port assignment, '-p0' does NOT
  242.                  necessarily mean COM1.
  243.  
  244.                * This comm port handle should be the one passed on by
  245.                Maximus's  '%L' or '%p' translation sequence for external
  246.                door programs.
  247.  
  248.            -b ,caller's baud rate(applicable to the DOS version only).
  249.                This option is ignored by this OS/2 version of UBX. UBX
  250.                does NOT need to change the current comm port's operating
  251.                parameters.
  252.  
  253.            -k ,forces local mode. No communication libraries required in
  254.                this mode.
  255.  
  256.            -t ,where n is the task number for this node.
  257.  
  258.                LEAVE THIS OPTION OUT COMPLETELY if the 'TASK' token is NOT
  259.                in effect in your MAX.CTL.
  260.  
  261.        NOTE:
  262.        * Command line options may be presented in any order.
  263.  
  264.  
  265.  
  266. Installation 
  267. ^^^^^^^^^^^^ 
  268. 1. Create a separate directory for UBX(will use c:\UBX for this example). 
  269.  
  270. 2. Copy all the files in this archive to c:\UBX 
  271.  
  272. 3. Modify the control file 'UBX.CTL'.  Please consult the sample control file
  273. for more information on the syntax of UBX.CTL.
  274.  
  275. 4.  Modify  your  BBS's  menus  to call up UBX and pass all necessary command
  276. lines to UBX. 
  277.  
  278.       ┌─────────────────────────────────────────────────────────────────────┐
  279.       │ TASK NUMBER?!?                                                      │
  280.       │ --------------                                                      │
  281.       │                                                                     │
  282.       │ * If you run a single line Maximus BBS and haven't specified a      │
  283.       │   'Task' number in your MAX.CTL, then LEAVE OUT the '-t%k' in       │
  284.       │   all the following examples.                                       │
  285.       │                                                                     │
  286.       │   UBX  uses the '-T' command line switch to find out which          │
  287.       │   'lastus??.BBS' to use.                                            │
  288.       │                                                                     │
  289.       │   For example:                                                      │
  290.       │                                                                     │
  291.       │         * If '-T' is ABSENT from the command line AND UBX is NOT    │
  292.       │           operating in the local mode, then UBX would look for      │
  293.       │           'Lastuser.bbs' for more info on the current caller.       │
  294.       │                                                                     │
  295.       │         * If '-T1' is present on the command line AND UBX is NOT    │
  296.       │           operating in the local mode, then UBX would look for      │
  297.       │           'Lastus01.bbs' for more info on the current caller.       │
  298.       │                                                                     │
  299.       └─────────────────────────────────────────────────────────────────────┘
  300.  
  301. Door mode example:
  302. ------------------
  303.  
  304. I have it set up in my bulletins menu in the Maximus MENUS.CTL as: 
  305.  
  306.  
  307.     Xtern_Run d:\ubx\ubxp.exe_%L_-t%k Normal "Users' Bulletins"
  308.  
  309. Express mode Example: 
  310. --------------------- 
  311.  
  312. On my BBS, 'news.bbs' is included as part of the logon sequence. In the MECCA 
  313. file 'news.mec' I have: 
  314.  
  315.       [LE Worthy] [xtern_run]d:\ubx\ubxp.exe %L -dnews -x-{ -t%k
  316.  
  317. Whereby,  all  callers  with  privileges less than or equal to Worthy will be
  318. presented  with  the  bulletins  in  the 'NEWS' UBX database. The listings of
  319. bulletins will be in reverse order( noticed the '{' in the -x option? ),  BUT
  320. the 'Stop' option is disabled while they're reading the bulletins(noticed '-'
  321. in the -x option? ).
  322.  
  323.  
  324.       [GE Privil] [xtern_run]d:\ubx\ubxp.exe %L -dnews -x+{ -t%k
  325.  
  326. Whereby,  all callers with privileges greater than or equal to Privil will be
  327. presented  with  the  bulletins  in  the 'NEWS' UBX database. The listings of
  328. bulletins will be in reverse order( noticed the '{' in the -x option? ),  BUT
  329. they  can  abort  the  display  of  bulletins  with the '[S]top' option while
  330. reading the bulletins( noticed '+' in the -x option? ).
  331.  
  332.  
  333.       Maximus will translate:
  334.            %L into either '-K' or '-Pn -bxxxx'
  335.               depending on whether the caller is remote or not.
  336.  
  337.            %k into the task number of this node.
  338.  
  339.  
  340.  
  341. UBXDEL - The UBX Database Maintenance Utility 
  342. --------------------------------------------- 
  343. This  is  where the maintenance-free part of UBX comes in. If you have a very
  344. busy and heavily used UBX bulletin forum, then you can include UBXDEL in your 
  345. daily maintenance routine to delete bulletins based on their 'age'. 
  346.  
  347. Each bulletin area maintained by UBX comes in two parts: 
  348.  
  349.         filename.IDX  This is the index file for the UBX bulletin
  350.                       database 'filename'.
  351.  
  352.  
  353.         filename.DAT  This is the actual data file for the UBX
  354.                       bulletin database 'filename'.
  355.  
  356. It is recommended that you: 
  357.  
  358. *  Only  instruct  UBXDEL  to purge(see below) old bulletins from the _index_
  359. file in your 'daily' maintenance routine. 
  360.  
  361. *  Run  UBXDEL  to  pack  the  data files perhaps once a week or maybe once a
  362. month. 
  363.  
  364. Of  course  there's  no  harm  in  running purge and pack together on a daily
  365. basis. Though in my humble opinion, it's a waste of time. <grin> 
  366.  
  367.  
  368. Command line syntax of UBXDEL 
  369. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
  370.  
  371.        UBXDELP -Dfilename -Kn -P
  372.  
  373.        Command line options of UBXDEL
  374.        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  375.  
  376.            -d ,where filename is the prefix for the bulletin
  377.                database, if not given it defaults to 'UBX'
  378.  
  379.            -k ,kills bulletins older than n days from the UBX index file.
  380.                No defaults.
  381.  
  382.            -p ,Instructs UBXdel to Pack the data files.
  383.  
  384.  
  385.  
  386. UBX_ADD - The UBX Text File Import Utility 
  387. ------------------------------------------ 
  388. Don't  you  just  hate line-editors? Well, I certainly do. It would have been
  389. nice to have a built-in full screen editor for UBX. But........ 
  390.  
  391. You can enter your bulletins on any plain ASCII text editor, then use UBX_ADD
  392. to  import the text file into the UBX bulletin database.
  393.  
  394. The  text  file  to  be imported is free form, though you should take note of
  395. following: 
  396.  
  397.            \\\    Three backslashes marks the start of a bulletin.
  398.                   The rest of the line following the backslashes
  399.                   will be taken as the heading for this bulletin.
  400.  
  401.                   All lines between the current heading and the next
  402.                   heading(or the end of file) will be considered as
  403.                   the body for the current bulletin.
  404.  
  405.  
  406.             ;     You might embed comments in your bulletins if you
  407.                   wish. But comment lines must start with a semi-colon.
  408.                   Comment lines will not be imported into the UBX
  409.                   bulletin database.
  410.  
  411. See the sample text file 'SAMPLE.TXT' for more info.
  412.  
  413.  
  414. Command line syntax of UBX_ADD 
  415. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
  416.  
  417.        UBX_ADDP -Dfilename -Ifilename
  418.  
  419.        Command line options of UBX_ADD
  420.        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  421.  
  422.            -d ,where filename is the prefix for the bulletin
  423.                database, if not given it defaults to 'UBX'.
  424.  
  425.            -i ,import text from filename into the UBX bulletin
  426.                database.
  427.  
  428. UBX Control File Syntax:
  429. ^^^^^^^^^^^^^^^^^^^^^^^^
  430.  
  431.       Key Words:
  432.       ----------
  433.  
  434.  
  435.        Lastuser_Path   This tells UBX where to find your 'lastus??.bbs'
  436.                        files. The 'lastus??.bbs' files are written out
  437.                        by Maximus each time an external program is
  438.                        called from within Maximus.
  439.  
  440.                        UBX make use of these files to find out the
  441.                        caller's name, time remaining etc.
  442.  
  443.                        For Example:
  444.  
  445.                               Lastuser_Path  D:\max\
  446.  
  447.  
  448.        SYSOP           Defines the Sysop's name. This will be the default
  449.                        user name when you start up UBX in local mode.
  450.                        Only the person defined as SYSOP here has the
  451.                        privilege to 'Kill' selected bulletins.
  452.  
  453.                        For Example:
  454.  
  455.                                SYSOP   David Luong
  456.  
  457.                         Note:
  458.                         -----
  459.  
  460.                         Do not double space your names; ie. don't leave
  461.                         more than one space between each word of your
  462.                         name. Otherwise UBX might get confused and not
  463.                         recognise you as the sysop.
  464.  
  465.  
  466.        COLOUR c1 c2 c3 c4 c5
  467.  
  468.                         Where c1..c5 are the five colour parameters for the
  469.                         display of bulletins. These are:
  470.                         border, title, byline, body and prompt respectively
  471.  
  472.                         For Example:
  473.  
  474.                                COLOUR 9 14 3 7 10
  475.                                <subtle colors>
  476.  
  477.                                COLOUR 23 30 113 112 79
  478.                                <strikingly attention-grabing colors>
  479.  
  480.                         Please consult your Maximus Documentation for a
  481.                         list of the colour codes.
  482.  
  483.  
  484.  
  485. Word of Caution
  486. ^^^^^^^^^^^^^^^
  487.  
  488. UBX's  indexing  scheme  is  purely  based  on  the  'Time'  when the
  489. bulletins are created.
  490.  
  491. UBX  would  function  fine  with OR  without  a time-zone environment
  492. variable (eg. TZ=GMT-10). BUT DON'T MIX AND MATCH! In other words, if
  493. you have the time zone variable set in your BBS task, then you should
  494. also have the same time zone environment set for all other OS/2 tasks
  495. where you plan on using any of the UBX's utilities. Failing to do so
  496. would result in incorrectly indexed bulletins.
  497.  
  498.  
  499. Hardcoded Error levels of UBX 
  500. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
  501.  
  502.       255: Fatal error. You should  take note of the error message on
  503.            the screen.
  504.  
  505.  
  506.  
  507. -=[WELL, THAT'LL BE ALL FOLKS]=- 
  508.  
  509.  
  510. POSTCARDS
  511. ^^^^^^^^^
  512.  
  513. Post cards should be directed to: 
  514.  
  515.                  Mr. David Luong
  516.                  308/232 Pitt Street,
  517.                          Waterloo, N.S.W. 2017
  518.                          Australia.
  519.  
  520.