DP Tool Club 12

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

/ DP Tool Club 12 / CD_ASCQ_12_0294.iso / vrac / sap408_a.zip / STOCK.DOC < prev next >

Wrap

Text File | 1994-01-01 | 28KB | 629 lines

=========================================================================== === === === STOCK FILE BASICS === === === =========================================================================== Stock files are files that contain "stock" (i.e. generic) text -- material that is displayed frequently. For example, the BBS sign-on logo is contained in a stock file (named LOGOXX.STD). The welcoming message is also contained in a stock file, and so on. To modify a stock file, you need a text editor, such as DOS EDLIN or EDIT, or a programmer's editor, or a word-processor in non-document (generic DOS text) mode. We recommend that you try out one of the excellent shareware editors such as QEdit (address given later). Each stock file contains text, and sometimes contains comments; any line that begins with a semi-colon is not displayed when the stock file is shown. Stock files can also contain color controls and special programming commands -- these will be described later on. In order to browse through the various stock files, enter the following command at the DOS prompt: SEE *.STD This will let you select and display all files with a STD extension. (Stock files also use the GRA and ANS extensions.) The SEE command can also print the file. Before you modify the file, it is a good idea to either print it out or make a backup copy. You can make backup copies of all STD stock files by entering the following DOS command: COPY *.STD *.OLD This creates a second copy of each stock file, named <filename>.OLD. (For example, LOGOXX.STD would be duplicated in LOGOXX.OLD) Thus, if you make a mistake and Sapphire no longer understands the file, you can restore it to its original form with the command: COPY <filename>.OLD <filename>.STD ------------------------------ THE THREE TYPES OF STOCK FILES ------------------------------ Stock files come in three varieties, identified with the STD, GRA and ANS file extensions... EXTENSION MEANING --------- ------- .STD Contains standard ASCII (no value greater than 128) .GRA Contains IBM-PC extended ASCII ("graphics") .ANS Contains ANSI controls For example, a standard stock file might be named MAINXX.STD, while its graphic equivalent would be named MAINXX.GRA and its ANSI equivalent would be named MAINXX.ANS. A user will normally see only the standard stock files (i.e. those with the STD extension). However, the user can use Sapphire's GRAPHICS command to turn on the GRA or ANS stock files. (Under certain circumstances, the user's ability to display ANS stock files is detected automatically by Sapphire. See SYSOP:CONFIG:BASIC:SECURITY:SIGN-ON for details.) See SYSOP:INFO:FILES for a description of the purpose of each stock file. ---------------------------- STOCK FILE NAMING CONVENTION ---------------------------- Most of the stock files that come with Sapphire follow the naming format of four characters and two X's for the root name (e.g. LOGOXX.STD). These files will be displayed to any user who encounters the situation in which it is appropriate to display the stock file. You can exercise a measure of control over which files get displayed, depending on how you name the stock files. The "XX" part of the file name holds the key: FORMAT: AAAABC.DDD EXAMPLE#1: UPFNXX.GRA EXAMPLE#2: MAINX1.STD In the FORMAT given above, the letters have the following meaning: AAAA Four letters identifying the purpose of the stock file. In the examples, UPFN is the file that is displayed when the user has to supply an UPload File Name. MAIN is displayed as the MAIN menu. B User membership level (1 to 8) C User expertise level (1 to 3) DDD File extension (STD, GRA or ANS -- as explained previously) Whenever Sapphire has to display a stock file, it will first try to find a file that matches the user membership and expertise level (expertise level is set via the EXPERT command). Thus, a level 3 user with expertise set at level 1 would see a file named MAIN31.STD when it is time to show the main menu. That is to say, he would see the file if it existed. If it does not exist, Sapphire tries to find a file that matches but has an X in one or both positions. It will then pick the one that matches best. EXAMPLE: User is at membership level 4, expertise 3. FILES: MAIN43.??? would be shown (??? here means STD, GRA or ANS) MAIN4X.??? would be shown if MAIN43.??? didn't exist MAINX3.??? would be shown if the previous two didn't exist MAINXX.??? would be shown if none of the previous existed Nothing would be shown if none of the previous existed The final line introduces an important concept in the use of stock files. By leaving out XX files for a given stock file application, you will prevent certain people from seeing that type of file. The most obvious application is for the main menu. In the standard Sapphire package, only MAINX1 is defined, which means that any membership level can see that file, but only if their expertise level is set to 1. If their expertise level is set to 2 or 3, they will NOT see a menu. You may wish to define some additional main menus. This is, in fact, an ideal way to get familiar with stock file operations. In order to provide complete coverage of all membership and expertise levels, you could define the following 48 files (where ??? means both a STD and GRA file): MAIN11.??? MAIN12.??? MAIN13.??? MAIN21.??? MAIN22.??? MAIN23.??? : : : : : : MAIN71.??? MAIN72.??? MAIN73.??? MAIN81.??? MAIN82.??? MAIN83.??? In actual practice, however, you probably won't define menus for users at expertise level 2 or 3, so you'll actually define the following files... MAIN11.??? to MAIN81.??? which is a more manageable task -- only 16 files. ------------------------------- DRAWING WITH GRAPHIC CHARACTERS ------------------------------- In order to put graphic (extended ASCII) characters into a .GRA stock file, you can use one of the following methods: 1. Press and hold the ALT key, followed by three digits on the numeric keypad. This lets you enter any extended ASCII character. For example, to enter a solid block character, hold down ALT then press (on the numeric keypad) 2, then 1, then 9. Release the ALT key. The problem with this method is that it is more than a little cumber- some, and it does not work on all machines. Also, some pop-up (TSR) programs may prevent it from working. 2. Define the graphics characters via a keyboard macro program, such as Cruise Control, NewKey, PRD+, ProKey, SmartKey or SuperKey. If you would like an example of how we set up SuperKey macros to perform this task, just drop us a line asking for our SuperKey PC-ASCII macros, enclosing $3 to defray the cost of the disk and postage. 3. Obtain a copy of an ANSI animator program that has the ability to save straight ASCII. One example is the shareware program TheDraw. For more information, write to: Ian Davis TheSoft Programming Services 1929 Whitecliff Court Walnut Creek, CA U.S.A. 94596 4. Most text editors have a rudimentary capability for drawing with graphic characters. The QEdit editor is a very fast, reasonably powerful editor available in shareware. For information, contact: SemWare 4343 Shallowford Road #C3A Marietta, GA U.S.A. 30062-5022 Phone: (404) 641-9002 Fax: (404) 640-6213 BBS: (404) 641-8968 ---------- ANSI FILES ---------- ANSI files (stock files with an ANS extension) can be prepared with an ANSI animator program such as TheDraw (address given earlier). When preparing ANSI files, you should avoid initializing with a Clear Screen command; the user can specify via the GRAPHICS command whether or not he wants his screen cleared. You may also have to edit the file afterwards with a text editor to remove trailing linefeeds. Sapphire transmits all ANSI codes in the file to the remote user. At the console, it implements ANSI x3.64 commands in the following way: ESC[y,xH Cursor position y,x (the H is sometimes a lowercase "f") ESC[H Means y=1 x=1 ESC[nA Cursor Up n lines, default 1, no wrap takes place ESC[nB Cursor Down n lines, default 1, no wrap takes place ESC[nC Cursor Forward n characters, default 1, no wrap takes place ESC[nD Cursor Backward n characters, default 1, no wrap takes place ESC[s Save cursor position (saved for the current stock file only) ESC[u Restore cursor position (if saved during this stock file) ESC[2J Erase display (clear and home) ESC[K Erase to end of line (including clear of cursor position) ESC[n;...nm Set colors and attributes, as follows: 0 All attributes off (sets Dim White [Light Gray] on Black) 1 Bold (e.g. turns Light Gray into White) 2 Dim (e.g. turns White into Light Gray) 3 Not defined 4 Underline (ignored) 5 Blink 6 Not defined 7 Reverse video (swaps foreground and background colors) 8 Invisible (sets foreground color to background color) Foreground Colors Background Colors ----------------- ----------------- 30 Black 40 Black 31 Red 41 Red 32 Green 42 Green 33 Yellow 43 Yellow 34 Blue 44 Blue 35 Magenta 45 Magenta 36 Cyan 46 Cyan 37 White 47 White ESC[nL (NANSI code -- ignored) Insert n blank lines at cursor line. ESC[nM (NANSI code -- ignored) Delete n lines including cursor line. ESC[n@ (NANSI code -- ignored) Insert n blank chars at cursor. ESC[nP (NANSI code -- ignored) Delete n chars including cursor char. ESC[n;ny (NANSI code -- ignored) Output character translation ESC["str"p (Ignored) Keyboard Key Reassignment. ESC[y;xR (Ignored) Report cursor position ESC[6n Request cursor position. This is used for automatic ANSI detection (see SYSOP:CONFIG:BASIC:SECURITY:SIGN-ON) but is not used in stock files. ESC[=nh (Ignored) Set mode ESC[=nl (Ignored) Reset Mode If any other codes are encountered that seem to follow the ANSI pattern (i.e. Escape followed by an open bracket), the code is ignored. Some characters may be lost if an unknown code is encountered, because Sapphire will have no way to know how long the code is supposed to be. By the way, Sapphire contains its own ANSI processing code -- you do NOT have to load a DOS driver (such as ANSI.SYS) in order to support ANSI stock files. =========================================================================== === === === STOCK FILE PROGRAMMING === === === =========================================================================== STD and GRA stock files (though not ANS stock files) can contain, apart from text, special lines that the user does not see. These are as follows: CATEGORY COMMAND EXAMPLE MEANING -------- ----------- --------------- -------- Display ;<number> ;8 Keeps lines together on screen ;FNC color ;FNC WOE Sets functional color of the display ;EXP number ;EXP 2 Quits for higher expertise levels ;LEV number ;LEV 2 Quits for lower membership levels ;NSK ;NSK Turns off spacebarring ;SKI ;SKI Turns spacebarring back on (default) Logging ;<space> ; My stock file A comment ;LOG text ;LOG Pistachio Places text in system (OBSERVE) log ;FIL ;FIL XYZ.TXT Opens a logging file ;TLN ;TLN Attention! Logs text, followed by a new line ;TXT ;TXT ATTENTION: Logs text but stays on same line ;QLN ;QLN Your name? Question, followed by new line ;QUE ;QUE Name: Question, but stays on same line ;QNM ;QNM Your age: Asks for a number ;QPH ;QNM Phone? Asks for phone number ;QCH ;QCH YN Okay? Asks for a single-character answer ;QYN ;QYN Agreed? Asks a Yes/No question (default Y) ;QNY ;QNY Agreed? Asks a Yes/No question (default N) ---------------- THE KEEP COMMAND ---------------- The "semicolon number" command is known as "The Keep Command". It is used when you want to ensure that certain text in a stock file is kept together on one screen, instead of being broken in the middle with a "More, Jot, Quit" prompt (which is displayed when the screen is full). Let's say you had placed, in a stock file, a list of phone numbers that was 8 lines long. It would be annoying to the reader if it was broken up in the middle. So you could start the table like this: ;8 PHONE NUMBER CONTACTS ------------ -------- 514-345-9578 Pinnacle Voice Support 514-345-8654 Pinnacle Free Files BBS : etc. The ;8 line will ensure that the next 8 lines are always presented on the same screen, even if it means presenting the "More, Jot, Quit" prompt a little early. For examples of the keep command, refer to the stock file HINTXX.STD. ---------------------- FNC (FUNCTIONAL COLOR) ---------------------- The "functional color" command lets you specify the color of the following text. Normally, stock files are displayed in light gray. You can switch colors by using the ;FNC command. The command works this way: COMMAND COLOR USED THEME OR FUNCTION ------- ---------- ----------------- ;FNC HLP Yellow Helpful or explanatory information ;FNC INP Light Cyan User input ;FNC QUE Light Green Text preceding user input (a prompt) ;FNC WOE Light Red Something unusual or troublesome is happening ;FNC INF Green Regular information and progress messages ;FNC FIL Light Grey Stock and message file output ;FNC HDG Light Blue A heading or title ;FNC INI Light Grey Initializes an alternating-color list ;FNC LIS LtGry/Cyan Switches to opposite color in list ;FNC HEY Lt Magenta Emphasized output The INI and LIS colors are a little different from the others. When you specify INI, it initializes "list color processing". Thereafter, every time Sapphire sees ;FNC LIS it will switch between Light Grey and Cyan. This technique is very handy for distinguishing lines in a list. --------------------------------- EXP AND LEV (EXPERTISE AND LEVEL) --------------------------------- The EXP command skips the rest of the stock file if the user's expertise is above the specified level. This lets you bail out of a file before it gets into details that an expert user doesn't need to hear. For an example of EXP, see SETRXX.STD: although this is an XX stock file (and thus would be seen by all expertise levels), it uses EXP 2 to keep people at expertise level 3 from having to read the text. You could do the same thing by creating two files (named SETRX1.STD and SETRX2.STD) but in this particular case, it is simpler to use one file and the EXP command. The LEV command skips the rest of the stock file if the user does not have a sufficiently high membership level. See GIMMXX.STD for an example. ------------------------------ NSK AND SKI (NO-SKIP AND SKIP) ------------------------------ Normally, a user can skip a stock file by pressing the spacebar. If you have something particularly important to convey, you can turn this off with the ;NSK command. After you have conveyed the vital part of your message, you can make spacebarring possible again with the ;SKI command. ---------------- COMMENTS AND LOG ---------------- The comment and logging commands are self-explanatory. You can find examples of both in the file UPDFXX.STD, which is the stock file that is displayed when the user tries to upload and there is not enough free space on the disk. In such case, you want to log this fact to the OBSERVE log so that you will find out about it when you read the log later on. You can use the LOG command to record the "Off" time in the OBSERVE log (normally Sapphire only reports when the user connected). To do this, enter the following command in the file GDBYXX.STD: ;LOG User disconnected This will pace the line "User disconnected" in the OBSERVE log when the user displays the stock file GDBYXX.STD, which is to say, when he logs off. -------------------- FIL (OPEN TEXT FILE) -------------------- The FIL command opens a file for the text and questionnaire commands. For example, if you created a stock file which contained: ;FIL MYFILE.TXT ;TLN Hello world! The phrase "Hello world!" would be saved at the end of the file MYFILE.TXT every time the stock file is displayed. If you omit the FIL command, the text and questionnaire commands will use the file name "ANSWERS.TXT". Only one FIL command is permitted per stock file. If you do not specify a full path name, the FIL command assumes you mean the current directory (i.e. your main Sapphire directory). You can, however, place the file in another directory. For example: ;FIL C:\MYFILE.XYZ ;TLN This text will be saved in a file called MYFILE.XYZ in the ;TLN root directory of the C: drive! Obviously, any file that grows without limit can fill up your disk, though in actual practice it is quite unlikely that your users could fill out that many questionnaires if you have a reasonably uncluttered hard disk. Never- theless, to make it impossible for questionnaires to fill up your disk, Sapphire permits you to set a level at which answers to questions are not saved to disk. See SYSOP:CONFIG:ADVANCED:GENERAL:STOCK-FILES. (In the unlikely event your disk did fill up, many warnings would be placed in the OBSERVE log to attract your attention to the problem.) ------------------------ TLN AND TXT (WRITE TEXT) ------------------------ As shown in the description of the FIL command, you can use TLN to place a line of text in a file. This file can later be viewed with the SEE program (included with Sapphire) or loaded into a text editor program. The TXT command also puts text in the file, but it does not place an "end of line" in the file. For example: ;FIL MYFILE.TXT ;TLN This is a test ;TXT This is also ;TLN a test After the stock file is displayed, MYFILE.TXT would contain: This is a test This is also a test The TXT command is useful for labelling the results of questions, as in this example: ;FIL C:\ANSWERS\ANSWER.TXT ;TXT Name: ;QLN What is your name? This would ask the user for his name, which would be written to the file. But before that is done, "Name:" is written to the file. So the file would read something like this: Name:Fred Jones If you want to place some spaces at the end of the Name: text, you may find that your text editor removes them; many text editors have a "strip trailing blanks" feature. You can specify the blanks by enclosing the text in double quotes, as follows: ;FIL TEST.TXT ;TXT "Address: " ;QLN What is your address? This would write the answer to the question to the file TEST.TXT, resulting in something like this: Address: 1024 Disque Drive, Byteville, Oregon -------------------------- QUE AND QLN (ASK FOR TEXT) -------------------------- The QUE command can ask a question, get user input, and save the input in a text file. For example: ;FIL HELLO.TXT ;QUE Where are you calling from? If you put these commands in the stock file NEWUXX.STD (which is displayed when somebody signs up), it would display the question and save the user's answer in the file HELLO.TXT. Sapphire places appropriate spaces after colons (:) and question marks (?) when asking a question. However, if you want to line up your answers on the screen, you will want to pad out the question with spaces. Since some text editors remove trailing spaces, Sapphire lets you specify the spaces by enclosing the question text in double quotes: ;FIL ADDR.TXT ;QUE "Where are you calling from? " ;QUE "Where did you hear about this BBS? " This would line up the answers nicely on the screen. If you also want to line up the answers in the output file, you can use the TXT command: ;FIL ADDR.TXT ;TXT "Calling from: " ;QUE "Where are you calling from? " ;TXT "Heard about us from: " ;QUE "Where did you hear about this BBS? " The QLN command does the same thing as QUE but starts on a new line. This is important if you think the user's input might require the full width of a line. For example: ;FIL ADDR.TXT ;QLN What is your street address? This would give the user a full line to enter his street address. ---------------------------------------- QNM AND QPH (NUMBER AND PHONE QUESTIONS) ---------------------------------------- The QNM command works like the QUE command except that it only accepts digits. This lets you prompt for a number, as in this example: ;FIL C:\ANSWERS\ANSWER.TXT ;QNM How old are you? The user could type a number, then press Enter, but letters and special characters would be ignored and would not show up on the screen. The QPH command asks for a phone number, using the phone number format you specified in SYSOP:CONFIG:BASIC:GENERAL:PROMPTS. If you blanked out the phone number format, however, there is no compelling reason to use QPH because there will be no phone number format to impose. Here is an example of the QPH command: ;FIL PHONENUM.TXT ;QPH What is your phone number? This would ask the user for his phone number, filling in any special characters automatically. This is the same method that is used during the standard sign-up procedure. --------------------------------------- QCH, QYN AND QNY (SINGLE-KEY QUESTIONS) --------------------------------------- The QCH command allows you to ask for a single character of input, accepting only a certain set of characters. For example, you could display a menu of choices, and let the user choose one, as in this example: ;FIL QUERY.TXT A) Order our catalog B) Order our press kit (includes catalog) C) Have a salesperson call me today! D) None of the above ;QCH ABCD Your choice: This would allow the user to press A, B, C or D -- all other keys will be ignored, except the Enter key. If the user presses that key, it will automatically select the first letter in the list of choices. Thus, in the example given above, the user would get choice "A" if he pressed Enter, and that letter would be written to the file QUERY.TXT. If a user hangs up, it simulates the pressing of the Enter key. (This applies to nearly all Sapphire inputs.) The QYN and QNY commands are variations of QCH. They accept Y or N (for Yes and No) only. QYN defaults to Y, while QNY does the opposite, assuming that Enter means N. For example: ;FIL YESNO.TXT ;QYN "Are you enjoying your visit to this BBS? " ;QNY "Do you like any BBS's more than this one? " The default answer to the first question is Yes, while the default answer to the second question is No. Note the use of quotes for trailing blanks. ---------------------------------- DESIGNING EFFECTIVE QUESTIONNAIRES ---------------------------------- Experience has shown that a questionnaire is most effective when: (1) You warn the user in advance how many questions you will be asking (2) You don't ask too many questions (3) You don't ask questions that the user might consider irrelevant Many new sysops feel that they should know the address of the people who call their board. Some sysops ask for personal information such as the caller's gender and age. It's your computer, so you have the right to ask whatever you want. However, unless you plan to use the information in some way, you should consider settling for their phone number. A short, snappy sign-on procedure is the best way to keep the user happy, which makes it much more likely that you will get accurate information.