ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

home *** CD-ROM | disk | FTP | other *** search

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / BBS / RBBS_PC / RBBSDOCS.ZIP / RBBSDOCS.7 < prev next >

Wrap

Text File | 1990-11-05 | 87.4 KB | 1,892 lines

PLANNING YOUR USER INTERFACE 7-1 7. PLANNING YOUR USER INTERFACE -------------------------------- RBBS-PC provides each SysOp the maximum control over what is presented to callers. There are three areas of control: - The menus presented to novice callers. - What is included in the prompt all users get. - What symbol invokes a particular function. 7.1 Menus Shown to Callers -------------------------- The menus in RBBS-PC are external text files that are presented to novice users. RBBS-PC simply displays what is in these files to the callers. Therefore, SysOps are free to change the text in these files to whatever they desire. Simply edit the files. However, be sure to use an editor that produces only ASCII text files with no special embedded characters. Most word processing editors are not suitable because they insert special symbols in the file meaningful only to it. Menus can also contain graphics and color (see section 6.3). 7.2 Subsystem Prompts Shown to Callers -------------------------------------- RBBS-PC has several configuration options which allow each SysOp to select the prompts that are presented to callers. They are: - Whether the section name is displayed. - Whether the letters of the available commands are shown. The commands in RBBS-PC are divided into four sections: MAIN, FILE, UTILITY and LIBRARY. If RBBS-PC is configured to display the section name, the command prompt will read "<section> command", otherwise "Your command". The section name is shown by default. RBBS-PC normally prompts a caller with the commands the caller has sufficient security to invoke. Each command is a single letter and is shown separated from the others by a comma. The command letters can be suppressed in the prompt. By leaving them on a SysOp provides each caller with a terse but helpful reminder of what commands are available to them. 7.3 Commands Available to Callers --------------------------------- All primary commands in RBBS-PC are invoked by single letter commands. An attempt is made to associate the command with the first letter in a word which describes the function, so that the command letter appears to be a short abbreviation for the longer word. The command to invoke reading messages is R. The default symbols that would be shown in the command line for each section are: sect |? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y 1 2 3 4 5 6 7 -----|------------------------------------------------------------------- MAIN |? @ A B C D E F H I J K O P Q R S T V W X 1 2 3 4 5 6 7 | FILE |? D G H L N P Q S U V X | UTIL |? B C E F G H L M P Q R S T U X | LIB |? A C D G H L Q S V X | GLBL |? H Q X RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-2 Four commands, ? H Q and X, have the same meaning in every section and are known as "global." The other commands all have unique function specific for the section within which they are invoked. For example, S stands for S)can messages in MAIN, S)earch in FILE and LIBRARY, and S)tatistics in UTIL. Symbols 1-7 are used for SysOp functions. RBBS-PC allows the SysOp to substitute any symbol for any command. Y)ell may be substituted for O)perator page, or Y)our mail for P)ersonal mail. If a blank is substituted, the command is removed from the list and is no longer available. 7.4 RBBS-PC's "Wrap-around" Command Search ------------------------------------------ There is an option in CONFIG which gives the SysOp unusual flexibility in configuring the user interface. A caller is always "in" a section. RBBS-PC considers the user's current section when acting on commands. The "wrap around" option allows RBBS-PC to look further for a command when it is not found in the section the caller is in. If a SysOp substitutes a blank for the V>iew conference command in the main section (as mentioned in section 7.3) and a user enters the V command from the main section, the V)iew archive file command would be what the caller would have invoked. The fundamental idea is to look further in other sections, where the search order is circular, starting at the current section, and proceeding in the following order: -MAIN->FILE->UTIL->LIBRARY->GLOBAL->SYSOP- | | -------------------<---------------------- If wrap-around is used, RBBS-PC will search ALL sections, in order, to find a valid command that matches the user's input. Even if wrap-around is not used, GLOBAL and SYSOP commands are processed globally. The important feature that wrap-around supports is that a command with a unique letter works in all sections. Thus W)ho will work everywhere if wrap-around is enabled. If every RBBS-PC command is given a unique symbol, all commands become global and there is no effective difference between sections. This allows SysOps to make commands available on a single level and makes it unnecessary to "go" to a section before using a command in that section. 7.5 How to Have a Single Universal Command Line ------------------------------------------------ The command structure within RBBS-PC can be made "flatter" without making it absolutely flat. Suppose, for example, that a SysOp wants callers to be able to do all file functions without going to a files section. In effect, the file functions are available in the main section, or the file section is merged into the main section. To do this, the SysOp must eliminate the overlap in command letters between the two sections. The main section and the file section share the letters D, P, S, and V. V is used to "view" a conference in the main section and "view" what is contained in an archived file. D is difficult because both D)oors and D)ownload are entrenched and natural options. One could leave D for the most frequently used function, say download, then use a special but arbitrary symbol like # for doors. Similarly, V could be left for viewing conference mail in the main section and a special but arbitrary symbol like & for viewing archived files in the file section. S)earch for substrings PLANNING YOUR USER INTERFACE 7-3 could be replaced by F)ind since F for going to F)iles is no longer needed. This could be accomplished by disabling F)iles and substituting F for S in the files commands. P is used for personal mail in the main section as well as personal files in the file section. Leaving P in the main section for personal mail and selecting the symbol M for personal mail in the file section would have the least impact on callers. U is used for upload. Since Quit may be used to go to UTIL, we can disable U in the main menu. We can use W for W)rite user preferences and F to find who else is on (since the F for FILES section is no longer needed). We could then revise the main menu to read: R B B S M A I N M E N U ~~~~~~~~~~~~~~~~~~~~~~~~~~~ [A]nswer survey [H]elp (or ?) [P]ersonal mail [U]pload a file [B]ulletins [I]nitial welcome [$]Personal files [V]iew conference mail [C]omments [J]oin conference [Q]uit [&]View ARC files [#]DOORS [K]ill message [R]ead messsages [W]rite user pref [D]ownload [L]ist files [S]can messages [X]pert on/off [E]nter msg [N]ew files [T]opic msg scan [Z]ippy search [F]ind who's on [O]perator page [@]Library [G]oodbye Obviously the limitations of using a single section (as the more primitive bulletin board systems do) means that the number of commands must be restricted to either - 26 (letters in the alphabet), or - 36 (letters in the alphabet plus the numbers 0 through 9), or - full "words". With this artificial limitation of a single section, commands become limited in number, cryptic, or both. If the even more clumsy use of full "words" is chosen, the system must slow down as it can no longer act immediately upon seeing the first character of a command as RBBS-PC does. However, assuming that someone would actually want to configure RBBS-PC to be "flat" (i.e. have a single command line), let us continue. In order not to confuse the caller by being in a section and seeing only some of the commands we want him to use, the SysOp could elect not to show the section in the prompt (CONFIG parameter 37) and not to show the commands (CONFIG parameter 38). Callers would see simply "Your command?" as the prompt. This makes the expert mode quite terse, but that simply means users would spend more time in novice mode before using expert. Now suppose that only a single command line was desired and that the commands from the "Utilities" menu commands were to be added to the above. The "global" H, ?, Q, and X commands already are in the single command line. M for message margin can remain unchanged since it is unique to the Utilities subsystem. In order to accommodate the redundancy of letters that exist by including the Utilities subsystem's commands, the W command for the main message subsystem can be re-enabled and the remote SysOps commands be eliminated in order to re-use the numbers. The Utilities subsystem commands B, C, F, G, RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-4 L, R, and S could then be replaced by the numbers 1 through 9. The Utilities subsystem commands T, U, E, and P could be replaced by the commands <, >, \, and !, respectively. This final menu of all RBBS-PC commands could be re-written without any apparent sub-sections as follows and the screen that the would appear to the "novice" users as: R B B S C O M M A N D S ~~~~~~~~~~~~~~~~~~~~~~~~ [A]nswer survey [O]perator page [1] Change Baud Rate 300-->450 [B]ulletins [$]Personal files [2] Display time of day [C]omments [P]ersonal mail [3] Set file transfer protocol [#]DOORS [Q]uit [4] Set type of graphics mode [D]ownload [R]ead messages [5] Set page length [E]nter msg [S]can messages [8] Review callers preferences [G]oodbye [T]opic msg scan [9] Display system statistics [H]elp (or ?) [U]pload a file [<] Toggle users options on/off [I]nitial welcome [V]iew conference mail [>] Show the log of callers [J]oin conference [&]View ARC files [@] Library [K]ill message [W]ho's on other nodes [\] Change echo selection [L]ist files [X]pert on/off [!] Change password [M]argin set [Z]ippy search [N]ew files Your command? 7.6 RBBS-PC'S Programmable User Interface (PUI) ----------------------------------------------- The programmable user interface (PUI, pronounced "pee you eye") lets the SysOp take TOTAL CONTROL over what the caller is presented with, including: - the novice menu - the prompt line - the organization of commands into groups (sections) - the flow between sections - unlimited levels of nested menus. This allows the RBBS-PC interface that the caller sees to take on any appearance desired by the SysOp. In effect, the SysOp is limited only by the intrinsic functions of RBBS-PC that have been programmed into RBBS-PC source code. These functions can be assigned any command letter desired in CONFIG. PUI lets the SysOp completely control how these commands are presented to the user - allowing RBBS-PC to "emulate" virtually any other host communications environment that the SysOp's callers may be familiar with. If no PUI is provided, RBBS-PC defaults to dividing the commands into a MAIN, FILES, UTILITIES, and LIBRARY section. RBBS-PC's PUI gives each SysOp the flexibility to tailor RBBS-PC to meet special needs. In effect, RBBS-PC's PUI allows the SysOp to adjust RBBS-PC to what the SysOp wants, rather than forcing the SysOp and his callers to conform to RBBS-PC. However, unlike RBBS-PC, the PUI does not adjust the prompt to show only the commands that the user has sufficient security to do. And, of course, PUI takes much more time to design and implement. PLANNING YOUR USER INTERFACE 7-5 When the SysOp takes control of what the user is presented by using the PUI, RBBS-PC does what the SysOp has explicitly set up -- and nothing else! For example, RBBS-PC's "global" commands, like help and the expert toggle, are no longer automatically available everywhere. They are available only where the SysOp has indicated via the PUI. RBBS-PC's default user interface has evolved over the years to represent what the callers found useful (not the SysOps!). A great deal of time and thought went into RBBS-PC's default user interface, and it is easy to overlook important things when a SysOp goes about setting up his or her own. When using the PUI assume that a new user interface will take time to both develop and refine (based on your callers feedback). Designing and implementing a PUI is not a simple undertaking as it is a total replacement for RBBS-PC's standard user interface. 7.6.1 An Example Using PUI -------------------------- The main menu in RBBS-PC can represent a bewildering variety of commands, especially to a new user. Studies show that human beings can effectively deal with at most 7 choices at one time, whereas RBBS-PC has 10 more than that in its main section. To help people in this situation, the different choices in RBBS-PC are grouped into related commands, but the choices can still be overwhelming. Some SysOps have tried to simplify the main menu by breaking it up into more sections. The most tempting group of commands to spin off are the message commands. Suppose the main menu is to be simplified to look like: <F>iles <M>ail <U>ser preferences <G>oodbye The <M>ail command puts the caller in a section where commands related to messages become available in yet another menu, such as J)oin and E)nter. PUI is required because the commands are grouped into different sections. While the default menu of RBBS-PC could be edited to say this, the underlying commands would not be grouped as desired. 7.6.2 How to Implement PUI -------------------------- First, plan carefully on paper exactly what you want the caller to see and what happens with each command. Consider also, if you have a submenu, how users are to get out of it. Each menu or section of PUI is controlled by a file whose extension is "PUI". The PUI is installed by putting a "main" PUI file whose name is specified in CONFIG. The default is "MAIN.PUI". Each sub-board in RBBS-PC can have a different PUI system if desired. A PUI file consists of exactly 10 lines, and the format is: LINE CONTENTS 1 name of novice menu 2 prompt to display 3 valid commands, corresponding RBBS-PC commands 4 which valid commands are menus 5 names of PUIs that are menus 6 letter of quit command 7 prompt for quit command 8 valid sub-commands of quit command RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-6 9 which quit commands are PUIs 10 names of menu PUIs in quit command The text in the lines should NOT be enclosed in quotes, except possibly the two parts of line 3. The novice menu is just a text file displayed to novices, just like the default menus (MENU1, MENU2, etc.). The name can include a drive or path as well as an extension. The menu PUIs in lines 5 and 10 must be stored in the same drive/path as that in line 1. The prompt to display is what all callers see when asked for a choice, including experts. Normally this includes a brief listing of the commands available along with a request for a command. This prompt is NOT dynamically adjusted to reflect the security level of the caller, unlike the default prompt in RBBS-PC, which removes commands the caller cannot execute. Each PUI defines a "section" of RBBS-PC (just like RBBS-PC has main, file, library, and utility sections). The valid commands are the symbols for the acceptable commands in this PUI section. They must be upper case only. The first part is the names of the commands that the caller must give. Each symbol must be mapped to a corresponding internal symbol name in RBBS-PC which is set in CONFIG. This way the same letter in a given menu can be used for different commands in RBBS-PC, just as "S" stands for S)can messages in the main section and S)ubstring search in the files section. Since the default underlying RBBS-PC commands use the same letter in different menus, you should first reconfigure RBBS-PC to assign each RBBS-PC command a different underlying symbol. Then in the PUI file map the letter you want the caller to use to that underlying symbol. Be sure in configuration NOT to limit commands to the current section -- you must let RBBS-PC search in other sections for underlying commands when it does not find it in the current section. In addition to the normal commands available in RBBS-PC, the SysOp can include new commands which invoke other menus. These must be symbols in the list of valid commands. If a valid menu choice is picked, there must be a PUI file for that choice. Line 5 tells what prefix the PUI file has. Each PUI name must consist of exactly 7 characters. The PUI name can be shorter than 7 letters, but in the list you must blank fill out to 7 positions to the right. The first 7 characters are for the first valid menu command, the second 7 characters are for the second valid menu command, etc. RBBS-PC will automatically append the extension "PUI" to this file name. Note that all PUI files must be in the same drive/path as the novice menu in line 1. The last 5 lines in the PUI file concern how control goes from one PUI to another. The PUI processing supports a "quit to" command in which the caller can jump to other menus - which one is specified in the subcommands to the quit command (just like RBBS-PC's "quit" to command). Line 6 is the symbol (in the valid commands) which is the quit-to command. It must be a single capital letter. Line 7 is the prompt for the quit-to command, to be presented to callers after they select the quit-to command (type ahead is supported). PLANNING YOUR USER INTERFACE 7-7 Line 8 is the list of the valid sub-commands of the quit-to command. Each command must be a capital letter. Line 9 tells which of the valid subcommands are PUI commands. If a sub-command is valid but not a PUI command, control will be passed to RBBS-PC to process the quit-to command. For example, Quit-to S)ystem for hanging up would have to be processed this way. Line 10 tells what are the names of the PUI files for each PUI command in line 9. The format of the PUI names is exactly the same as in line 5 -- 7 characters blank filled to the right if shorter. The following file MAIN.PUI installs the example that was discussed in the previous section: MMENU Enter choice: <F,M,U,G> FGMU," G " FMU FMENU MAILM UMENU <5 blank lines follow> The name of the menu to be displayed initially is MMENU. The prompt users will see is "Enter choice: <F,M,U,G>?" (RBBS-PC adds the trailing "?" for prompts). The four valid commands are F, G, M, and U. Three of these commands invoke other menus (F, M, and U), and G is a non-menu command, i.e. one of the base RBBS-PC functions. The PUI file name for "F" is FMENU.PUI, MAILM.PUI for "M", and UMENU.PUI for "U". Each of these PUI files gives the same type of information as the main PUI. For example, MAILM.PUI might contain MAILM.MNU Enter choice: <E,J,P,Q,R,S,T> EJPQRST,EJPQRST Q MAIN <5 blank lines follow> The novice menu for the mail section is in file MAILM.MNU. This file might contain the following text: M A I L S U B S Y S T E M ~~~~~~~~~~~~~~~~~~~~~~~~~~~ E)nter a message J)oin a new message base P)ersonal mail (review) Q)uit to main section R)ead messages S)can msg headers T)opic msg scan The prompt will appear immediately below this line unless an extra blank line is included in the menu file. There is only one menu command: Q for getting back to the main menu. The PUI system can also be used to emulate the default RBBS-PC commands with 4 sections. Four sample files are provided for accomplishing this: XMAIN.PUI, XFILE.PUI, XUTIL.PUI, and XLIBR.PUI. For novice menus, each uses the standard default menu that comes with RBBS-PC. These require RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-8 RBBS-PC to be configured with the following symbols for the underlying RBBS-PC commands: MAIN = normal: ABCDEFIJKOPRSTUVW reconfigured: ABC>EFIJKOPRSTU\W FILES = normal: DGLNPSUV reconfigured: DGLNYZ^V UTIL = normal: BCEFGLMPRSTU reconfigured: !#E$<&M*()-+ GLOBAL = normal: H?QX reconfigured: H?QX SysOp = normal: 1234567 reconfigured: 1234567 LIBRARY =normal: ACDGLSV reconfigured: []{G}:' 7.7 RBBS-PC's Support of Sub-menus ---------------------------------- Sub-menu support means that an item on a menu can itself be another menu, so that selecting it results in a new menu being displayed from which the caller can select yet another option. The areas in RBBS-PC that can have sub-menu support include: answering surveys, bulletins, doors, joining a conference, and the file subsystem command to list directories. A primary use of sub-menus is to simplify the user interface, chiefly by allowing sub-categorization of the option. For example, suppose a SysOp has a complex system of doors, including multi-user games (TREK, NAPOLEON, 3DCHESS), single-user games (D&D, R&R, PICKUP), and demonstrations (DBIII, ORACLE, ADVENT). These could be presented on a single menu, such as: The following Doors are available: Multi-User Games TREK - explore the galaxy, compete with 12 other players NAPOLEON - be Russia, Italy, or England and fight the computer 3DCHESS - are you ready, Spock? Single-User Games D&D - the Unix dungeons and dragons! R&R - welcome to Taipei, Tokyo, or Bangkok, soldier! PICKUP - do you have what it takes? Demos - all self running DBIII - Special version of DB3 adopted for remote usage ORACLE - see the power of SQL. Full screen if you emulate ANSI. ADVENT - our own home brewed ... With sub-menus, the user could see a single, 3 item menu Doors are available for: MGAME - multi-user games SGAME - single-user games PLANNING YOUR USER INTERFACE 7-9 DEMO - self running demos When the caller picks one of these three, a new menu comes up that lists the particular doors for each category. For example, after picking MGAME the caller sees Multi-User Games available include: TREK - explore the galaxy, compete with 12 other players NAPOLEON - be Russia, Italy, or England and fight the computer 3DCHESS - are you ready, Spock? RBBS-PC's sub-menu capabilities allow SysOps to set up "tree-structured", "key word" paths to options. Bulletins provide an example where this type of structure can be very useful. Bulletins have two main uses: short, system-wide announcements, and a standard stock of text files for policies and procedures for a RBBS-PC. Some SysOps, however, have wanted to put up an elaborate system of announcements, where in fact these "bulletins" are a featured way of presenting data to callers. For example, an association published 300 short pamphlets under a dozen categories, and wants to make this information available on-line. Sub-menus fit this need very well. The main bulletin menu could read: Bulletins are available for: NURSES - nurses OB - obstetricians PED - pediatricians FAM - family physicians Please type in the category you want: OB, instead of being a bulletin, is a sub-menu that displays: The following bulletins are available for OBSTETRICIANS. Each entry shows the length and price per glossy copy. NAT - natural childbirth, 8 pages, $3 MIDW - midwives. 20 p., $5 NUTRI - special nutritional needs of pregnant women, 25p, $6 FPLAN - family planning services, 40 p, $3 DRUG - drugs to beware when pregnant, 50 p., $5 When the caller picks MIDW, the associated document is displayed. In this example, bulletins become a menu-driven way of selecting documents to browse. In order for the previous example to work, RBBS-PC utilizes "named" bulletins. For example, selecting "B" as the bulletin prefix, the above bulletins would be files BNAT, BMIDW, BNUTRI, BFLAN, and BDRUG. However, RBBS-PC's "new bulletin search" function will only search for named bulletins if they are listed in the file x.FCK (where x is the bulletin prefix). Also, named bulletins are not listed in the "new" bulletin list as numbered bulletins are. 7.7.1 How to Implement Sub-menus -------------------------------- If "XXX" is an option on a menu, simply create a file named "XXX.MNU" that has in it the text for the menu. Put this file in the same drive/path as RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-10 the non-menu options (e.g. where the "BAT" files go for doors, where the bulletin files to display are put, where the directory files are). For example, if "B" is the bulletin prefix, the above example would be implemented by adding the files "BNURSE.MNU", "BOB.MNU", "BPED.MNU", and "BFAM.MNU". Put these files on the same drive that the bulletins themselves go. The .MNU extension alerts RBBS-PC to the fact that the file is a menu. Thus, RBBS-PC will only LIST the menu file, rather than ACT on it (e.g. 3DCHESS.BAT is a door to be run, while 3DCHESS.MNU is a menu to be listed). 7.7.2 Shared Options Across Sub-menus ------------------------------------- RBBS-PC supports identical choices from different sub-menus. E.g. the main menu has sub-menus A and B, and BOTH of these sub-menus could have an option X on them, which triggered a different action (based on which sub- menu it X was selected from). The way that this works is RBBS-PC searches both for the global prefix and the user response as well as looking for the current prefix and user response. If the bulletin prefix is "B", and the structure of bulletins is as follows: / 1 BM is main bulletin menu, B is the prefix A ---- 2 BMA.MNU submenu get with choice A / \ 3 BMB.MNU submenu get with choice B / BMC.MNU submenu get with choice C / / 1 BM --- B ---- 2 BMA1, BMA2, BMA3 bulletins active at BA \ \ 3 BMB1, BMB2, BMB3 bulletins active at BB \ BMC1, BMC2, BMC3 bulletins active at BC \ / 1 C ---- 2 \ 3 7.8 RBBS-PC's "Macro" Command Support ------------------------------------- RBBS-PC's "macro" support expands a single keystroke into multiple keystrokes. It allows RBBS-PC to be tailored in even a greater variety of ways than before because a single command can be set up to invoke a sequence of multiple RBBS-PC commands. The concept is similar to the keyboard macro function found in many terminal emulators, except that in RBBS-PC the SysOp defines the macros and the caller invokes them transparently without knowing. Macros add a new dimension to RBBS-PC commands -- commands can be a full word rather than just a single letter. A macro is invoked by a name up to 8 characters. For example, "DOOR" and "OPEN" can be used to invoke doors. This makes it easy to make all commands available on a single level, since D could trigger a download, while the word DOOR will trigger the door function. Macros can be used to abbreviate a longer series of commands. If the SysOp wants to use "A)bandon conference", all that need be done is to add a macro called "A" whose content is "J M" (join main). Or if N)etmail is to be used to read Fido-net compatible message bases, a macro called "N" could be set up as "D NETMAIL" (use door called NETMAIL). RBBS-PC thus can have UNLIMITED commands. A string of RBBS-PC commands can be stored in a macro for many different types of purposes, including (but not limited to): PLANNING YOUR USER INTERFACE 7-11 setting up demos, showing a user what to do rather than just explaining it in words, automated testing of RBBS-PC features Macros can also be used to make the same type of function do different work. For example, the B)ulletin command basically displays a text file. Suppose an association wants to let persons order pamphlets and preview them on-line. Rather than bury the ordering function insider A)nswer questionnaire and the preview function inside B)ulletins, the commands PREVIEW and ORDER can be added as macros, where ORDER stands for "A ORDWHAT" AND "ORDWHAT" is a submenu listing what can be ordered. Each option on the submenu is a questionnaire. PREVIEW similarly is "B PREWHAT" where "PREWHAT" is a submenu listing the available pamphlets that are stored as text files. Macros can be built to provide interactive help to callers. For example, you can put up a macro called EZDOWN to help people download. It explains everything, asks for the file name and protocol, and tells the caller what they should be doing on their end, and then drives the download. Macros can be used to provide integrated data bases. Unlike questionnaires, you can totally control how data is written to a file. You can put in labels, or data only, put the values in quotes, separate the values by commas, etc. This is done by creating a template into which data values are written. Macros can be used to give "tours" of your RBBS-PC -- to showcase new or special features. Macros can be controlled via security level access, just like regular commands, and they can be forced to operate only in certain contexts. Macros can be - invoked anywhere within RBBS-PC -- including questionnaires, - unlimited in length, - used even when the caller has "turbo" key feature enabled, - used with SmartText (see section 7.9), - used to store responses that can be manipulated later, and - used to support graphics versions of text. It is important to remember that a macro will be ignored if its name is the same as any command. To replace a command with a macro, you must insure that the letter for the command has been reassigned. CONFIG parameters 30-34 allow such reassignments to be easily accomplished. Some contexts will not accept macros, such as when RBBS-PC prompts for a search string. Macro commands with more than one letter override all others. This means that the macro interpretation will prevail if more than one interpretation is possible. For example, in the absence of macros the command "door" would the interpreted as the command "d", so that saying "door" in the files section would be download. But a "DOOR.MCR" would be executed instead when it exists. One letter commands, however, will be executed when they match a command letter, and so any macros will be ignored that have the same one letter name the same as a command. RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-12 7.8.1 How to Set Up "Macros" ---------------------------- To use macros, two CONFIG parameters must be specified: the drive/path where macro files are stored (CONFIG parameter 79) and the extension the macro files will have (CONFIG parameter 80). The defaults are "C:" and "MCR". To create a macro named X, simply create a file with prefix X and the macro extension and place in it the macro drive/path. If you are not using any macros, RBBS-PC will run faster if you specify NO macro extension in CONFIG parameter 80. The first line within a "macro" controls access to the macro, both by security level, and a limitation on the scope of the macro, in which it will be operative, including - anywhere inside a section - anywhere inside a command - only at a section and not inside. The format of the first line is: <SecLevel>/<constraint> where <SecLevel> is the minimum security required to run the macro, and <constraint> is the section (M for main, F for file, U for utility, or @ for library) and command letter the macro is confined to (use original command letter, not the reassigned ones). For example 4/M means that security level 4 is required, and the macro runs only at or inside the main section prompt. 5/MB means that security level 5 is required and the macro runs only at or inside the main section bulletin command. Thus the macro file 1.mcr 2/MJ {EN RBBS means that when inside the main J)oin, the text "RBBS" will be substituted for "1". (So "J 1" does the work of "J RBBS".) The "{EN" means not to echo what the macro substitutes (user does not see "RBBS"). To make a macro operative only at a section prompt and not inside, add a " /" to the end of the section constraint. For example, 4/M / means that the macro applies only at the main section prompt. For example, the macro SP.MCR 4/M / {EN J SEMIPRV will substitute "J SEMIPRV" for "SP" when at the main prompt, but NOT for "SP" inside the message read command ("R SP L"). PLANNING YOUR USER INTERFACE 7-13 Note: a macro will be ignored if its name is the same as a command symbol. To use 1, 2, 3, etc. for macro commands, you must disable or substitute other symbols for the SysOp commands. The first line of a macro must be the minimum security level to use the macro. The macro will simply be ignored if the caller has insufficient security. The second line will be parsed and replace the macro name. The remaining lines will be read from disk and processed as required. Macro commands have the same structure as SmartText variables: <command prefix><command name> where <command prefix> is the SmartText command specified in CONFIG. The symbol "{" (ASCII 123) is the default. The <command name> consists of two characters. Lines that are not valid macro commands are simply passed to RBBS-PC as if the user had typed them in. There are three differences between SmartText variables and macro commands: (1) Macro commands must be the first three characters on a line, whereas SmartText variables can occur anywhere on a line. (2) Macro commands can have an argument after the command name, and( (3) A macro command can apply to a block of lines following it. 7.8.2 Macro Commands -------------------- RBBS-PC "Macro" Commands include the capability of having commands executed within the "macro" rather than simply passing keystrokes to RBBS-PC. In all prompts and blocks, substitution is supported for both stored answers SmartText variables. The following is a list and description of valid "macro" commands: *0 - display what follows on the line with no carriage return. *1 - display what follows on the line with a carriage return. *B - display what follows on subsequent lines. *F - display the named file that follows. nn - display a prompt and store result in work variable nn. WT - pause for the number of seconds specified after "WT". >> - append the following block of text to the file specified. ST - Stack the characters immediately following the "ST". M! - Execute the named macro that follows on the same line. ON - Case logic for branching within macros based on stored results. EY - Echo the text passed in macros as keystrokes. EN - Do not echo the macro keystrokes. << - Display fields from a file in a form. := - Assign value to a work variable LV - Verify that answer of one in a list NV - Verify that answer is between two integers CV - Verify that answer is between two character values LO - Set location for Fast File Searches for download, upload, view The syntax and an example of each command follows: *0 - display what follows on the line with no carriage return. {*0Press any key to continue RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-14 *1 - display what follows on the line with a carriage return. {*1{FN, I hope you enjoyed your tour of the board! The caller's first name is substituted for the SmartText variable "{FN." *B - display what follows on subsequent lines, each line with a carriage return, up to the line beginning with "{END". {*B This is an example of a macro's ability to display multiple lines. The macro command is {*B and it will display all lines until it encounters one beginning with {END. Like it, {FN? {END The caller will seen everything between the first and last lines, with the first name substituted into the last line displayed. *F - display the named file that follows. {*F L:\RBBS\HELP.LST will display the file HELP.LST. nn - use the text that follows on the line as a prompt and store the answer in an internal working variable numbered nn. nn must be two digits and can be 01, 02, 03, ..., 99. CONFIG parameter 94 controls the maximum # of work variables. {01Please enter the Department you work for: {02Please enter your Office number: This will store the answers in work variable # 1 and 2, which can be subsequently referenced as "[1]" and "[2]". You can have as many work variables as specified in CONFIG parameter 94. Variables that are reused have their values overwritten. WT - pause for the number of seconds specified after "WT". {WT 2 will wait for 2 seconds. >> - append the following block of text to the file specified on this line. {>> C:MACRO.DAT "{FN","{LN","[1]","[2]" {END will append the following line to the file named MACRO.DAT on drive C:, assuming the caller is KEN GOOSENS, and he responded to the above prompts for Department with "Controller" and Office # with "107". Then the line what would be written out is: "KEN","GOOSENS","Controller","107" PLANNING YOUR USER INTERFACE 7-15 As many lines can be included as desired. Simply end the block to be written out with "{END" as the beginning of the line. Some data base managers want fixed length files and this is possible in the macro append. Just add "/FL" on the macro command line. Rather than replace, the substitution will overlay the line at the "[", thus keeping the output fixed length. Lets suppose that the first work variable has "A" as a value, the second work variable has the value "123456", the third work variable has "Henry" as a value, and the caller's first name is KEN. Then {>> C:\RBBS\DAT.FIL /FL [1][2]....[3]...............{FN........ {END would add the following line into DAT.FIL A 123456.Henry.............KEN......... Normally, blanks would be put where dots are show. ST - Stack the characters immediately following the "ST". {ST will stack a carriage return (no characters). And {STD [1] [2] would stack "D RBBS-EXE.ARC Z" - as if they were typed and ENTER pressed - if the first work variable had "RBBS-PC.EXE" and the second work variable held "Z". It is important to note that "macros" are so transparent to RBBS-PC that if you use macros to display text at an RBBS-PC prompt like "Enter command? ", RBBS-PC will continue to sit there waiting for an answer. A stacked carriage return at the end will cause the prompt to be redisplayed, though the effect of the stack will vary with the particular prompt. M! - Execute the named macro that follows on the same line. E.g. {M! ORDER will execute the macro called ORDER. RBBS-PC does NOT return to the invoking macro when the named macro is complete. Also, The full file name of the macro to execute is not here used (i.e. ORDER.MCR), only the file prefix -- ORDER. As is shown in the example of the ON command, the macro name can have a drive/path and/or extension. If only a prefix is put in, RBBS-PC will automatically add the drive/path and extension for macros specified in CONFIG parameter 79 and parameter 80. Putting in a drive/path/extension that is different from CONFIG's assures that no caller can invoke the macro -- it only can be used internally by your application. ON - Case logic for macros. This allows responses to be tested against and branching logic developed within a "macro". An example would be: {ON 1 RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-16 {==A {M! D:\HIDDEN\CHOICEA.MCR {==B {*1You have selected option B {02Why did you select B? {==C {M! D:\HIDDEN\CHOICEA.MCR {END ON EY - Echo the text passed in macros as if keystrokes. The default is to echo. EN - Do not echo the macro keystrokes. An example would be: {EN {*1 The following commands will be executed but now shown {01 Press Enter when ready R L A {EY {*1 now you will see the responses to the prompts {01 Press Enter when ready R L A << - Display fields from a file in a form. This is one of the most powerful macro commands. It allows data to be stored in compact, data format but retrieved into a form for display to a caller. There are 5 parameters that can follow the macro command: <file name> <file format> <data#> <submode> <rec-pause> where: "<file name>" is the name of the data file that has records to read, "<file format>" is "/V" if data is stored in variable length format and "/F" if fixed length format, "<data#>" is the number of separate fields in a record for variable length data and the length of the data if fixed length, "<submode>" is the mode used to substitute data in the following form "/FL" if the form is fixed length, meaning that data is overlaid into the form so as not to change any lengths. "<rec-pause>" should be "/1" if you want to pause after each record rather than when the screen fills. An example of a "macro" that uses this capability is as follows: {*1 -TOPIC- - DATA # - - VOICE # - -First Name- -Last Name- {<< C:\RBBS\RHLP.DAT /V 5 /FL [1] [2] [3] [5] [4] {END Note that spaces occur after the "[4]". If the file RHLP.DAT contains "DOORS","703-978-6360","0","Ken","Goosens" PLANNING YOUR USER INTERFACE 7-17 "PROTOCOLS","407-627-6969","407-627-9767","Doug","Azzarito" then the caller would see -TOPIC- - DATA # - - VOICE # - -First Name- -Last Name- DOORS 703-978-6360 0 Ken Goosens PROTOCOLS 407-627-6969 407-627-9767 Doug Azzarito The same example using fixed length data would be {*1 -TOPIC- - DATA # - - VOICE # - - Name - {<< C:\RBBS\RFLH.DAT /F 69 /FL [1](34:12) [1](46:12) [1](58:12) [1](1:33) {END where RFLH.DAT contains: Ken Goosens DOORS 703-978-63600 Doug Azzarito PROTOCOLS 407-627-6969407-627-9767 This would produce the following for the caller: -TOPIC- - DATA # - - VOICE # - - Name - DOORS 703-978-6360 0 Ken Goosens PROTOCOLS 407-627-6969 407-627-9767 Doug Azzarito Note that work fields support sub-field references in the format: [n](x:y) where n is the work field number, "x" is the beginning column, and "y" is the # of bytes to get. If work field two had a value "123abcde" then "[2](3:4)" would have "3abc" as its value. Fixed length records are always referenced as work variable one. := - Assign a value to a work variable. Work variables can be assigned a value inside a macro. The command to do this is ":=". E.g. {:= 5 OK assigns string "OK" to work variable 5. LV, NV, and CV - Macros can edit the responses to questions. Edits can constrain the answer to - one of a list - a numeric value between two values - a character value between two values An editing constraint must be put in front of the actual macro question it applies to, and a constraint applies only to the next question and does not remain operative. The commands for these are respectively "LV" (List Verify), "NV" (Numeric Verify), and "CV" (Character Verify). The list verify uses the first character after the command as a delimiter between valid responses. E.g. "{LV;R;A;E;" means that only "R", "A", and "E" will be accepted as answers ("{LV/R/A/E/" would have the same effect). RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-18 Semi-colon is the best delimiter in general because it cannot be entered as a value. Numeric and Character verify check inclusive ranges. Thus "{NV 7 11" will accept 7, 8, 9, 10, or 11. The numeric value must be an integer between -32,768 and 32,767. To accept answers B through E, the macro edit command is "{CV B E". Whenever an answer fails an edit, the message "Invalid answer <...>" is given with the answer received between brackets, and the question is asked again. An example of a macro with edits is: 4 {*1 Verification macro {*1 now checking list... {LV;A;F;W; {01 Enter A, F, or W {*1 now testing numeric range... {NV 5 15 {01 Enter a number between 5 and 15 {*1 now testing character range... {CV D J {01 Enter a character between D and J LO - Sets location that a file is to be searched for in an upload, download, or view request. Followed by a drive path. Useful when want to have a macro execute in front of a download or upload for a file which is really available (see section 12.9). Applies only to Fast File Search. For example, {LO F:\DF1\ would set the file location to drive F subdirectory DF1. 7.8.3 A Sample Macro -------------------- Suppose A)bandon conference is to be implemented in RBBS-PC. To do this, the command A)nswer questionnaires must be assigned a different letter. Else A will always invoke answer instead. Then the macro file could contain 5 J M The command "A" will then be followed by "Rejoining MAIN". Incidentally, if the macro had been implemented by 5 J M The only difference is that the prompt for what conference to join will be displayed, "M" then would be displayed as if the caller had typed it, and then main would be rejoined. The difference is caused by the fact that the first line after the security level is what replaces the macro name, so in the first case "M" preempts the prompt but not in the second. PLANNING YOUR USER INTERFACE 7-19 7.8.4 On-line Data Base With Macros & Questionnaires ---------------------------------------------------- RBBS-PC provides the SysOp with the ability to offer callers access to an on-line database both internally (using macros and questionnaires) and externally to RBBS-PC (see Appendix R). RBBS-PC's internal Remote Data Base feature gives the SysOp the ability to: - set up unlimited numbers of named data bases - set up menus to interact with the user - prompt users for data - use Metavariables - both work variables and SmartText variables. - store user's answers in work variables. Any subfield in a work variable can be referenced. - display, or store all metavariables - process commands conditionally - save Metavariables to file through templates, allowing data to be stored in virtually any format desired - retrieve data into templates for display. - do full screen data entry RBBS-PC's support for "full screen" questionnaires and macros takes some work on the SysOp's part. The SysOp must use ANSI screen commands. The SysOp must then arrange to transmit the "template" that clears the callers screen and writes the appropriate static text (lines, labels, etc.) on the callers screen. Then the data the user is to see is transmitted onto the caller's screen. The "full screen" support does not allow the caller to use keys like tab and cursor arrows to move around on the screen. It is "full screen" in the sense that the caller sees all the data that is to be entered and the cursor moves from field to field. On-line Database Example ------------------------ This application manages a data base of callers who are willing to help with RBBS-PC by topic. It is controlled at a high level by the following questionnaire. C:DUMMY.DAT,4 * This questionnaire is for finding help with RBBS-PC by topic. * Please register yourself if you * - are willing to help others, and * - know enough about a topic to help * * Examples of topics people need help with: * Desqview Modem models (HST, Everex, USR Internal, etc.) * PC-Slaves Protocols Conferences FMS * Doors DoubleDos Sub-boards PUI * Questionnaires 10-Net Macros Uploads * MU-Purge File maint. Personal dnld Caller Analysis * :-[prompt]- T ? V)iew database, E)nter new data, Q)uit (V,A,Q) =V-[view]-=E-[add]-=Q-[quit]-= -[prompt]- :-[view]- M C:\RBBS\VIEWHELP.MCR >-[prompt]- :-[quit]- @ RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-20 :-[add]- * 703-978-6360 ?1 BBS data number * 703-978-4339 ?2 Voice # (evening, 0 not to give) * You can specify as many topics as desired, one at a time. * :-[topic]- ?3 RBBS-PC topic you will help others with, or Q)uit =Q-[prompt]-= -[addrec]- :-[addrec]- * -Topic- - Data # - - Voice # - Last Name First Name */FL[3] [1] [2] {LN {FN T ?Really add this record (Y,N) =Y-[really]-=N-[topic]-= -[addrec]- :-[really]- M C:\RBBS\ADDHELP.MCR >-[topic]- Two macros are used by this questionnaire: VIEWHELP.MCR for displaying the data base, and ADDHELP.MCR for appending new data to the data base. VIEWHELP.MCR contains 5 {*1 -Topic- - Data # - - Voice # - Last Name First Name {*F RBBSHELP.DAT ADDHELP.MCR contains 5 {>> RBBSHELP.DAT /FL [3] [1] [2] {LN {FN {END Full Screen Example Full screen is available only in a color graphics version of questionnaires and macros. A long application for collecting BBS information is given in these following files: REGRBBS.DEF - Questionnaire driver, TTY version REGRBBSC.DEF - Color graphics version of questionnaire driver VUNRBBS.MCR - View data base macro, TTY version VUNRBBSC.MCR - View data base macro, Color graphics version SVRBBS.MCR - Macro to save data to a comma separated data file These files can generally be download from most bulletin board systems. However, they are definitely available on Ken Goosens' RBBS-PC system at (703) 978-6360. Hints for Building Remote Data Base Applications ------------------------------------------------ Generally you will have: PLANNING YOUR USER INTERFACE 7-21 - a questionnaire driver that gives caller option to exit, view database, or Enter new data - a macro to retrieve data from file to a form - a macro to save data in a data base format - a data entry routine in the questionnaire. Creating a "full-screen" application is more complicated that than a line- at-a-time (i.e. TTY) application. For full-screen applications, you will want to: - paint a template with everything but the data values, such as row and column labels and titles. - clear out the existing values in a form and then put in the new values. Only the changes to the screen are transmitted rather than retransmitting the entire screen when only a part changes. ANSI commands are used to control the screen. Where [ESC] stands for the one-character Escape (ASCII 27), the most useful ANSI commands to know are: [ESC][2J - clear the screen. [ESC][K - clear from current cursor position to end of line. Cursor position after clearing is same as before. [ESC][X;Yf - position the cursor on row x and column Y. E.g. "[ESC][5;10f" positions on column 10 of row 5. Case is significant in ANSI commands, so beware that "[ESC][k" will NOT clear to end of line, and "[ESC][1;7F" will not position the cursor. You can use ANSI commands to set color and blink characters. An easy way consistent with RBBS-PC is to set colors using the SmartText variables C0, C1, ..., C4, where 1-4 are the colors set in CONFIG parameter 323, parameter 324, parameter 325, and parameter 326. C0 is "emphasis off," and restores normal text color preference of the caller. An example that clears the screen, sets color to 1, positions on line 1, column 15, prints "-Sample Title-", sets color to caller's text preference, prints 2 spaces, and then prints value of work variable 1 is as follows: [ESC][2J{C1[ESC]1;15f-Sample Title-{C0 [1] 7.9 RBBS-PC's "SmartText" Variables ----------------------------------- SmartText allows the SysOp to substitute pre-defined variables in text files as menus, bulletins, help, welcome files, as well as macros and questionnaires. This allows the SysOp to present to each caller an interface that is not only "programmable", as discussed in section 7.6, but also tailored to the specific caller. Some applications for SmartText include: addressing the caller by name, as well as referring customized variables for the caller, such as city/state. For example, the welcome file could say, "Hi, <first name>, how's the weather in <city/state>?". SmartText variables can also be used for status line reports in menus, showing such things as security, minutes remaining, and current time. RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-22 To utilize RBBS-PC's SmartText files, CONFIG parameter 17 must be set to the decimal value of a delineation character that the text editor used by the SysOp can handle. The character you select should have three characteristics: 1. It should be visible on the screen and when printed. This allows the SysOp to see where the control sequence is when designing the text files to be used as SmartText files. 2. It should not be a character that might be used for any other purpose in the text files. The character can still be used in text files, but the chances are slight that RBBS-PC will interpret the character as a SmartText sequence. 3. It should not be a character that might be interpreted, when printed, as being a printer command (i.e. start double spacing). IMPORTANT: While RBBS-PC currently allows you to select the SmartText character, we STRONGLY suggest you use the default character (the { character, decimal 123). Future versions of RBBS-PC will no doubt rely heavily on standard SmartText, and as such will probably NO LONGER allow you to change this character. CONFIG parameter 17 can have any value between 0 and 255. If 0 is selected, RBBS-PC's SmartText capability will be turned off. A RBBS-PC SmartText control sequence consists of the control character that was selected in CONFIG parameter 17 followed by a SmartText double- character command. These SmartText double-character commands MUST be entered as upper case characters! There are two kinds of SmartText variables: those which substitute text, and others which control how substitution is done. The commands are: COMMAND NAME MEANING BD "Bytes Downloaded" Displays the bytes downloaded today. BN "BBS Name" Displays the name of the BBS. CS "Clear Screen" Overrides RBBS-PC's automatic screen depth management so that the next "Press Enter to Continue" will not come halfway through a page. CT "City/state" Displays the caller's city & state. C0 "Color 0" Resets color to the user's selection for text. C1 "Color 1" Changes color to the user's selection for Foreground Color One. C2 "Color 2" Changes color to the user's selection for Foreground Color Two. C3 "Color 3" Changes color to the user's selection for Foreground Color Three. C4 "Color 4" Changes color to the user's selection for Foreground Color Four. DB "Dnld (tot) Bytes" Inserts the total number of bytes ever downloaded by the caller. DD "Downloads Today" Inserts the total number of files downloaded by the caller today. DL "DownLoads" Inserts the total number of files ever downloaded by the caller. DT "Date" Inserts the current date, MM-DD-YYYY, into the text file. PLANNING YOUR USER INTERFACE 7-23 FI "FileName" Inserts current work Filename into the text file FN "First Name" Inserts the user's FIRST NAME into the text file. FS "First Name SySop" Inserts the SysOp's FIRST NAME into the text file. LN "Last Name" Inserts the user's LAST NAME into the text file. LS "Last Name SysOp" Inserts the SysOp's LAST NAME into the text file. ND "Node Number" Inserts the RBBS-PC Node Number for this node. NS "Non Stop" This causes the rest of the current file to be displayed in RBBS-PC's "none stop" mode. Page breaks will be ignored following a NS command. PB "Page Break" Causes RBBS-PC page break message, "MORE (Y/N/NS/A)" or the "PRESS ENTER.." prompt to appear after the line is printed. RP "Reg Period" Inserts the number of days in the registration period. RR "Reg Remaining" Displays the days remaining in the caller's registration period. SL "Security Level" Inserts the user's current security level into the text file. TE "Time Elapsed" Inserts the user's elapsed session time (hh:mm) into the text file. TM "Time" Inserts the time (hh:mm AM/PM) into the text file. TN "Trim NO" Substitute as is (the default) TY "Trim YES" Remove leading and trailing spaces first Note: a setting for trimming remains in effect until another trim command is encountered. TR "Time Remaining" Inserts the number of minutes left in the user's session into the text file. UB "Upload Bytes" Displays the total number of bytes ever uploaded by the user. UL "UpLoads" Displays the total number of file ever uploaded by the user. VN "Overlay NO" Insert into the text file (the default). VY "Overlay YES" Overlay into the text file (do not change length) Note: an overlay setting remains in effect until explicitly replaced. When designing SmartText files, each SysOp should take into account that the some of the SmartText commands (i.e. the user's name) may significantly extend the length of a line. It is important that this line elongation be taken into consideration so that, when the actual text substitution occurs, the line seen by the caller does not exceed 80 characters. What follows is an example of a SmartText file that demonstrates how all of the above commands might be used. The following example assumes that CONFIG parameter 17 has been set to the decimal value 123 for the SmartText delineation character -- {. Introducing...{C1SmartText!{C0 RBBS-PC allows the SysOp to customize the text seen by each caller. For instance, if the SysOp wanted to make sure this message didn't scroll off the screen, he could pause the display like this: {PB Or, the SysOp may want to show the caller that today's date is {DT and the time is {TM. The SysOp may even want to include a personal greeting to {FN {LN. RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-24 The SysOp can tell the caller that their security level is {SL and that they have been on-line for {TE, and have {TR minutes left in this session. This kind of capability illustrates RBBS-PC's on-going commitment to nurturing each SysOp's creativity and avoiding the dogmatic. 7.10 "Colorizing" the RBBS-PC User Interface -------------------------------------------- "Colorization" refers to the utilization of color within RBBS-PC text files and prompts. RBBS-PC has long supported graphics versions of external text files, and is even distributed with graphics menus. RBBS-PC supports "colorization" as follows: 1) In files shown to the callers including: All menus, All bulletins, The Welcome file, The file for new users, All on-line help files, Standard file directories, and FMS file directories (see item 6 below). 2) Via highlighted text in searches of messages, in searches of files, in announcing new personal mail waiting, for locked out users, and the SysOp user maintenance (function 5). Highlighting supports a limited but extremely functional use of colorization - to make it easy for the caller to spot significant bits of text on a screen. 3) Within the Programmable user interface (PUI). The PUI file can have graphics versions just like text files. The file XMAIN.PUI that was used in the example in section 7.6.2 can have a graphic's equivalent named XMAING.PUI and a color equivalent named XMAINC.PUI. Color codes can be embedded in the prompts in the PUI as well as external text files. Each SysOp has total freedom to colorize prompts as well as menus. 4) Within text internal to RBBS-PC. This applies to standard (non-PUI) prompts, such as the main command prompt, and to formatted reports, like the message scan and message read. This type of "colorization" is controlled by whether highlighting has been turned on in CONFIG. 5) Within RBBS-PC's "short" prompts. Caller foreground color 4 is used to mark the commands the user can type. Emphasis is used to mark the default selection. This colorization is based on a scan of the text to be printed: [...] : will be highlighted (default answer) (xxx) : will be put in foreground color 4 (text to type in): if xxx is not longer than 2 characters and is in caps <...> : will be put in foreground color 4 (collective choices) and if there are words before this, the first will use foreground 1 and the second, foreground 2. PLANNING YOUR USER INTERFACE 7-25 "Short" prompts colorization applies to ALL text displayed by RBBS-PC before an answer is expected. For example, by using the above conventions, questionnaires can be colorized. This is controlled by whether highlighting is on. 6) Within FMS file directories. The "colorization" of the FMS file directories is based on the four colors specified in CONFIG and is controlled by whether or not the caller has selected to be in color graphics mode or not. There are two extremes on the use of color: use none or use it everywhere. By using no colorization, RBBS-PC's performance is optimized. RBBS-PC does not have to go through the overhead of transmitting special instructions to control the caller's screen. The two chief functions of BBSs, transmission of textual information and file exchange, do not essentially involve the use of color. Of course, there are those who want their RBBS-PC's visual displays to convey as much as the text or the files themselves (i.e. the message is in the medium). These are the SysOps would elect to use color everywhere. With the use of color, plain text begins to look drab and uninteresting and attention tends to focus on the colorized text. For this reason, some SysOps find it difficult to use color in some places and not in others. Colorization is implemented in RBBS-PC with ANSI display commands. In order for a caller to see the colors as RBBS-PC displays them, the terminal emulator used by the caller MUST be ANSI-compliant. CONFIG allows the SysOp to activate and customize colorization on screen 17, "RBBS-PC Color Parameters". 1) Use CONFIG's parameter 321 to put in a string for turning EMPHASIS on. The recommendation is a bright foreground on red background ("[27][1;41m"). 2) Use CONFIG's parameter 322 to set the string for normal text. This is the general default color and is used to turn off emphasis. The recommended color is amber (normal yellow) ("[27][0;33m"). 3) Use parameter 323, 324, 325 and 326 of CONFIG to set the four caller foreground colors. CONFIG uses natural language phrases to set these, so it is very easy. The recommendation, in order, is: bright green, bright yellow, bright purple, and bright cyan. These colors are all used in the message header and general command prompt. Foreground 4 is used to highlight the commands the caller actually needs to type in to select that option. No colors will be displayed if these parameters are set to empty strings. Callers can turn off the colorization simply by going into Utilities and T)oggle H)ighlite to "off". The default in RBBS-PC is for colorization to be OFF. RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-26 Colorization is based on the ANSI standard. Special codes are sent by RBBS-PC to the callers system, which must then be interpreted by the caller's communications software. 7.11 RBBS-PC's Automatic Operator Page Option --------------------------------------------- RBBS-PC will "automatically page" the SysOp whenever a specified caller or group of callers logs on to RBBS-PC or joins a specific "sub-board". The selection criteria can be a specific caller's name, a range of security levels, or whether the caller is a new user. A SysOp may wish to be notified for any number of reasons including: - A caller has been causing trouble on the bulletin board and needs to be monitored. - The SysOp wants, for security reasons, to be notified when anybody logs on with a SysOp security level. - The SysOp wants to chat with a friend but does not want to continually monitor RBBS-PC's activity. AutoPage is controlled by a file whose name is specified in CONFIG parameter 18 (the default name is AUTOPAGE.DEF). Each line in the file is a separate AutoPage command. The line contains 4 parameters separated by commas. The format is <condition>,<notify caller?>,<# of times>,<music> <condition> Can be a NAME enclosed in quotes, the string "NEWUSER", or a security level range specified in the format /<min sec>/<max sec> where: <min sec> is the minimum security level <max sec> is the maximum security level <notify caller?> Is "N" if the caller also is to be notified that the SysOp has been notified when the caller logs on. Anything else means the caller will not know that the SysOp has been paged automatically. <# of times> Is the number of times that the PC's speaker will be sounded. <music> Is a BASIC music command to be used instead of a beep. If nothing is specified, a beep will be used. Warning: on some PC's the playing of music produces "out of string space errors". Test any music before using. Beeps always work fine. Examples: "SEXY DEVIL",,1,L4EDC AutoPage when a caller named SEXY DEVIL logs on, do not notify the caller, and play "L4EDC". "GREGG SNYDER",N,2, AutoPage when GREGG SNYDER logs on, notify the caller, and beep the speaker twice. PLANNING YOUR USER INTERFACE 7-27 "NEWUSER",,1, AutoPage when any new caller logs on, do not notify the caller, and beep the speaker once. /10/12,N,2, AutoPage when anyone with security 10 through 12, inclusive, logs on, let them know that the SysOp wants to be notified that they are on, and to beep the Speaker twice. The status line at the bottom of the RBBS-PC screen will read "AP!" for the duration of the caller's session if RBBS-PC has automatically paged the SysOp. This allows the SysOp to know that the AutoPage took place, even if the SysOp was not present at the beginning of the call. If the caller triggers more than one AutoPage command, the first condition encountered will be used. Since each "sub-board" can have a different AutoPage command file, the SysOp has the option to be automatically paged based on different criteria for each "sub-board". 7.12 Enhancing the File View Function ------------------------------------- Within the File Subsystem of RBBS-PC the V)iew function, allows the caller to get a list of files that are "archived" inside a single file. RBBS-PC supports .ARC, .LZH, .PAK, and .ZIP compression formats, as well as ANY format using SysOp-installed external procedures. RBBS-PC assumes that the file extension will identify the type of compression. Hence, the SysOp can install a View function for files with extension ".XYZ". All the SysOp must do is put a .BAT file with the name "Vxyz.BAT" on the same disk and path specified for COMMAND.COM via CONFIG parameter 105. If such a file is present, RBBS-PC will shell to the command in Vxyz.BAT whenever a caller asks to V)iew any file with the extension .XYZ. SHELLing requires extra system RAM beyond what RBBS-PC uses. If your system has little or no free memory, you may be limited to using the internal V)iew feature of RBBS-PC. RBBS-PC includes the following files for external View support: ARCVIEW.COM Compiled C program for view of DWC, PAK, ZOO, and ARC files. Used in VDWC.BAT, VZOO.BAT. VDWC.BAT Processor for DWC files VZOO.BAT Processor for ZOO files Each BAT file contains in it: ARCVIEW [1] > [2] RBBS-PC will SHELL to the above program (not to the BAT file) after first substituting the name of the file to be listed for "[1]" and the name of the file to place the results of the listing for "[2]". The ">" is the DOS "redirect" function, which causes the output to be placed in the file instead of on the local screen. The file specified in [2] is named "NODE?WRK" when the wildcard "?" is the node id (1,2,3,...). RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-28 How to Implement Your Own View function --------------------------------------- Your view program must have a way to receive from RBBS - the name of the file to list - the name of the file to write the listing to. RBBS-PC will interface with your program in two different ways, depending on how many lines your BAT file contains. If the BAT file contains exactly 1 line, RBBS-PC will shell to the line in the BAT file and not to the BAT file itself. RBBS-PC will dynamically scan for "[1]" and "[2]" in the line and substitute the names of the file to be listed and the file to write the results to, respectively. Everything else will be left intact. If the BAT file contains more than one line, RBBS-PC will shell to the BAT file, passing as command line parameters the name of the file to list, and the name of the results file. For example, the following BAT file could be used: ECHO OFF ECHO %1 >> VIEW.LOG ARCVIEW %1 > %2 ECHO ON The statement "ECHO %1 >> VIEW.LOG" will create a list of all files selected for view. ">>" means to append the view file name to a file called "VIEW.LOG". Using ZIPTV ----------- Ziptv is a program distributed by Samuel H. Smith which supports not only View, but the ability to list any file inside of a ZIP file, thus allowing users to view documentation before downloading a file. Many SysOps will want to install ZIPTV to replace the internal RBBS-PC View function. To do so, create a VZIP.BAT as follows: DEL %2 <path>ZIPTV -P%3 %1 Where <path> is the drive and subdirectory where you have placed ZIPTV.EXE. 7.13 Bulletins and News ----------------------- RBBS-PC has very powerful and flexible features for broadcasting system- wide information to callers. The following table describes the various NEWS options: PLANNING YOUR USER INTERFACE 7-29 ┌───────────────────────────┬─────────────────────────────────────────────┐ │ When the caller will see │ Which file will the caller see │ │ the news │ │ ├───────────────────────────┼─────────────────────────────────────────────┤ │Every time the caller logs │The file PRELOG is displayed before callers │ │on. │are asked their names. This information │ │ │should be kept very brief. │ ├───────────────────────────┼─────────────────────────────────────────────┤ │Only when a NEW USER logs │The file NEWUSER is shown to new users only │ │on. │the first time they log on. │ ├───────────────────────────┼─────────────────────────────────────────────┤ │On every call, after the │The file WELCOME is displayed after a │ │caller logs on. │successful logon. For graphic and color │ │ │versions of this file, see section 6.3. │ ├───────────────────────────┼─────────────────────────────────────────────┤ │Only when the SysOp has │The NEWS file is displayed if the date of │ │updated information since │last log on is the same or earlier than the │ │the last time the caller │date of the news file. The news file also │ │was on the BBS. │can be read by using the "B N" command │ │ │(Bulletin News). │ ├───────────────────────────┼─────────────────────────────────────────────┤ │Every time the caller logs │The logoff questionnaire, EPILOG.DEF is │ │off. │processed at logoff, and can be used to │ │ │display news at this time. See section 19. │ ├───────────────────────────┼─────────────────────────────────────────────┤ │Available on request by │The RBBS-PC general Bulletin files. │ │the caller. │ │ └───────────────────────────┴─────────────────────────────────────────────┘ General Bulletin Files ---------------------- General bulletins are text files prepared by the SysOp that can be viewed by the callers when they first log on, or at any time during the caller's session. To configure bulletins, you must first decide if you will used NUMBERED bulletins, NAMED bulletins, or both. The only difference between numbered and named bulletins is in how RBBS-PC scans for new bulletins when a caller logs on. With numbered bulletins ONLY, RBBS-PC uses the number of bulletins specified in CONFIG parameter 62 to find new bulletins. If the SysOp uses NAMED bulletins, each bulletin must be identified to RBBS-PC (in the file BULLET.FCK) in order to scan for new bulletins. To create a bulletin, use CONFIG parameter 61 to set the location and name of the bulletin menu, and set parameter 63 to the desired bulletin prefix. If you are using numbered bulletins, also set parameter 62 to the number of bulletins. Ex: Set parameter 61 to: C:\RBBS\BULLETIN\BMAIN.MNU Set parameter 63 to: B When RBBS-PC looks for bulletins, it will use parameter 61 for the location of each bulletin, and parameter 63 to build the file name. If you would like a bulletin named TEST, RBBS-PC will look for the file C:\RBBS\BULLETIN\BTEST. Any TEXT editor can be used to create bulletins. The bulletin can contain ASCII text, extended ASCII graphics, or ANSI color. By naming the bulletins properly, RBBS-PC's graphic support will display the proper bulletin to the caller (e.g. BTESTC. would be the COLOR version of bulletin TEST). See section 6.3 for details. RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 7-30 The bulletin menu defined in CONFIG parameter 61 should contain a list of available bulletins. The .MNU extension activates RBBS-PC's sub-menu feature (see section 7.7). If only numbered bulletins are used, RBBS-PC will be able to scan for new bulletins automatically (as long as parameter 62 has the proper setting). For named bulletins, you must create a list of bulletins for RBBS-PC to scan. The list should be in the file <prefix>.FCK in the same directory as all the bulletins. The <prefix> is what is specified in parameter 63. In our example, this file would be called B.FCK. Each bulletin should be listed, without the prefix, one per line. Ex: TEST 1 2 RBBS-PC would check the date of the files BTEST, B1, B2 and BRBBS-PC. Note that B1 and B2 are considered Numbered bulletins, but if B.FCK is used, ALL bulletins are considered Named bulletins. News Bulletin File ------------------ The NEWS file is a special bulletin that is automatically displayed to a caller at login if it has been updated since his last call. The NEWS bulletin is NOT located with the general bulletin files. It should be placed in the same directory as the WELCOME file. The name of the NEWS file is <conference>.NWS. The <conference> is the name of the RBBS-PC conference to which the news belongs (each conference can have a separate news file). The MAIN news file, shown to callers at login, is named MAIN.NWS. News files can support color and graphics (see section 6.3).