Night Owl 25

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

/ Night Owl 25 / nopv25.iso / 040A / PBL30DOC.ZIP / SYSOP.DOC < prev

Wrap

Text File | 1997-02-28 | 48.0 KB | 743 lines

____________________________________________________________________________ @@@@@@@@@@@@@@@@@@@@@**^^""~~~"^@@^*@*@@**@@@@@@@@@ @@@@@@@@@@@@@*^^'"~ , - ' '; ,@@b. ' -e@@@@@@@@@ A Comprehensive Guide to @@@@@@@@*^"~ . ' . ' ,@@@@( e@*@@@@@@@@@@ Color Systems, Text File @@@@@^~ . . ' @@@@@@, ~^@@@@@@@@@@@ Control Codes and String @@@~ ,e**@@*e, ,e**e, . ' '@@@@@@e, "*@@@@@'^@ Macros for Programs that @',e@@@@@@@@@@ e@@@@@@ ' '*@@@@@@ @@@' @ are Compiled with PB-Lib @@@@@@@@@@@@@@@@@@@@@',e, ; ~^*^' ;^~ ' @ @@@@@@@@@@@@@@@^""^@@e@@@ .' ,' .' @ @@@@@@@@@@@@@@' '@@@@@ ' , ,e' . ;@ , /(/( @@@@@@@@@@@@@' ,&&, ^@*' , . i^"@e, ,e@e @@ ** }=\,\(,!, @@@@@@@@@@@@' ,@@@@, ; ,& !,,@@@e@@@@ e@@ {___(_\ @@@@@,~*@@*' ,@@@@@@e, ', e^~^@, ~'@@@@@@,@@@ ,) ,/ `--> @@@@@@, ~" ,e@@@@@@@@@*e*@* ,@e @@""@e,,@@@@@@@@@ @@@@@@@@ee@@@@@@@@@@@@@@@" ,e@' ,e@' e@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@" ,@" ,e@@e,,@@@@@@@@@@@@@@ Copyright (c) 1995-1997 @@@@@@@@@@@@@@@@@@@@@@@~ ,@@@,,0@@@@@@@@@@@@@@@@@@@ Branislav L.Slantchev @@@@@@@@@@@@@@@@@@@@@@@@,,@@@@@@@@@@@@@@@@@@@@@@@@@ /Gargoyle """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" "I am a dinosaur... Somebody is digging my bones!" King Crimson, Thrak [Topic] [Keyword] Overview and Scope ................................. /OVERVIEW Text Control Codes ................................. /TEXTCODES String Macros Reference ............................ /MACROS Options for Action Macros .......................... /OPTIONS Various Examples ................................... /EXAMPLES Hex Colors Reference ............................... /COLORS Differences with ProBoard .......................... /PROBOARD o v e r v i e w a n d s c o p e /OVERVIEW ─────────────────────────────────────────────────────────────────────────── The text display system built in all programs compiled with PB-Lib is very extensive and versatile. This document is provided as a general reference for any program compiled with this library. Even though there may be other restrictions, generally every text file displayed by the program can make use of text control codes, and any text prompt that may be edited in the language editor can contain string macros. A brief explanation of macros follows. This is generalised to refer to control codes too. A "macro" for our purposes is a sequence of characters with special formatting which, when encountered during output operations is replaced by the program with text it represents. Note that some macros can specify actions to be taken instead of text substitution. For macros which generate text strings, special formatting can be performed in order to restrict and/or justify the text within specified limits. Macros may not be nested. For people familiar with ProBoard (and any RemoteAccess-compatible) system, most codes will not be anything new. There are however some subtle diffe- rences as well as some new codes, so it is recommended that you at least look over the following sections. It is surprising what functionality can be accomplished with a seemingly restricted set of macros. Also, reference sections are provided for the supported color code systems. These are enabled by default (but this can be changed by the program; make sure you read the manuals that come with it) and can be used anywhere in text files or user-definable strings. The supported color systems include ANSi and Avatar/0 sequences, PCBoard @Xnn codes, Wildcat! @nn@ codes, the hexpipe color |nn code specification, ProBoard's \nn, \Lc, and \Hc language prompt color system, and the RemoteAccess' ^K[nn color codes. This enables you, as the Sysop, to choose what color system to use to best suit your need as well as use existing text display files in almost any common format known to the BBS scene. t e x t c o n t r o l c o d e s r e f e r e n c e /TEXTCODES ─────────────────────────────────────────────────────────────────────────── "Text control codes" are special characters embedded in text files which cause certain information to be displayed or action to be performed. All of them consist of a leading character (either ^F or ^K) and code character which specifies the type of the code. In the examples below, '^' means Ctrl (that is, ^K means Ctrl+K, which has the ASCii code of 11). These values can usually be entered with TheDraw or AcidDraw directly or in any text editor by holding down the Alt key and typing the ASCii code for the letter. For example, ^F can be entered as Alt+6 (on the numeric keypad). You should see the '' character when you do this. The table below lists the codes, the ASCii values for both characters and their meaning. Note that these codes ARE case-sensitive (i.e. ^FA is NOT the same as ^Fa), so you should be careful when entering them. ╒═══════╤═════╤══════╤════════════════════════════════════════════════════╕ │ ASCii │ Ctl │ Type │ Description and Notes │ ╞═══════╪═════╪══════╪════════════════════════════════════════════════════╡ │ 1 │ ^A │ exec │ Waits for the user to press Enter, no prompt shown │ │ 2 │ ^B │ exec │ Disables interruption by pressing 'S' │ │ 3 │ ^C │ exec │ Enables interruption by pressing 'S' (default) │ │ 4 │ ^D │ exec │ Enables 'More'-prompt when screen is full │ │ 5 │ ^E │ exec │ Disables 'More'-prompts │ │ 7 │ ^G │ exec │ Rings a bell (both local and remote) │ │ 12 │ ^L │ exec │ Clears the screen │ │ 23 │ ^W │ exec │ Pauses for 1 second │ ├───────┴─────┴──────┴────────────────────────────────────────────────────┤ │ codes dealing with the current user information record │ ├───────┬─────┬──────┬────────────────────────────────────────────────────┤ │ 06-65 │ ^FA │ text │ Current user's full name │ │ 06-87 │ ^FW │ text │ Current user's first name │ │ 06-49 │ ^F1 │ text │ Current user's handle (fixed alias) │ │ 06-67 │ ^FC │ text │ Current user's password │ │ 06-36 │ ^F$ │ text │ Current user's address (line 1) │ │ 06-39 │ ^F' │ text │ Current user's address (line 2) │ │ 06-38 │ ^F& │ text │ Current user's address (line 3) │ │ 06-66 │ ^FB │ text │ Current user's city │ │ 06-52 │ ^F4 │ text │ Current user's state │ │ 06-34 │ ^F" │ text │ Current user's country │ │ 06-68 │ ^FD │ text │ Current user's data phone number │ │ 06-69 │ ^FE │ text │ Current user's voice phone number │ │ 06-61 │ ^F= │ text │ Current user's fax number │ │ 06-53 │ ^F5 │ text │ Current user's birth date (xx-xxx-xxxx) │ │ 06-93 │ ^F] │ text │ Current user's comment in the user record │ │ 06-96 │ ^F` │ text │ Current user's sex (male/female/unknown) │ ├───────┴─────┴──────┴────────────────────────────────────────────────────┤ │ codes dealing with the current user system settings │ ├───────┬─────┬──────┬────────────────────────────────────────────────────┤ │ 06-86 │ ^FV │ text │ User's screen length (number of rows) │ │ 06-58 │ ^F: │ text │ Date of user's first call (if known) │ │ 06-70 │ ^FF │ text │ Date of last login (xx-xxx-xxxx) │ │ 06-71 │ ^FG │ text │ Time of last login (xx:xx:xx) │ │ 11-51 │ ^K3 │ text │ Date of the last password change │ │ 11-52 │ ^K4 │ text │ Date of the last new files check │ │ 06-54 │ ^F6 │ text │ Current user's expiration date, if any │ │ 06-55 │ ^F7 │ text │ Number of days to the expiration date, if any │ │ 06-79 │ ^FO │ text │ Current user's access level │ │ 06-72 │ ^FH │ text │ A flags setting (flags A through H) │ │ 06-73 │ ^FI │ text │ B flags setting (flags I through P) │ │ 06-74 │ ^FJ │ text │ C flags setting (flags Q through X) │ │ 06-75 │ ^FK │ text │ D flags setting (flags Y through 6) │ │ 11-47 │ ^K/ │ text │ Current user's flags setting (all 32 flags) │ │ 06-78 │ ^FN │ text │ Number of message last read in current area │ │ 06-81 │ ^FQ │ text │ Total number of files uploaded by the user │ │ 06-82 │ ^FR │ text │ Total KBytes uploaded by the user │ │ 06-83 │ ^FS │ text │ Total number of files downloaded by the user │ │ 06-84 │ ^FT │ text │ Total KBytes downloaded by the user │ │ 06-77 │ ^FM │ text │ Total number of messages written by this user │ │ 06-80 │ ^FP │ text │ Total number of calls by the user to the system │ │ 06-85 │ ^FU │ text │ Total minutes online ever for this user │ │ 06-88 │ ^FX │ text │ ANSi emulation status (on/off) │ │ 06-89 │ ^FY │ text │ Screen pausing enable (on/off) │ │ 06-90 │ ^FZ │ text │ ClearScreen codes enable (on/off) │ │ 06-48 │ ^F0 │ text │ Full-screen editor enable (on/off) │ │ 06-50 │ ^F2 │ text │ Command stacking enable (on/off) │ │ 06-56 │ ^F8 │ text │ Avatar/0 emulation status (on/off) │ │ 06-57 │ ^F9 │ text │ Avatar/0+ emulation status (on/off) │ │ 06-51 │ ^F3 │ text │ Extended ASCii characters enable (on/off) │ │ 11-53 │ ^K5 │ text │ Check for new mail enable (on/off) │ │ 11-54 │ ^K6 │ text │ Check for new files enable (on/off) │ │ 11-89 │ ^KY │ text │ Current message area name │ │ 11-49 │ ^K1 │ text │ Current message area number │ │ 06-41 │ ^F) │ text │ Current message group name │ │ 06-43 │ ^F+ │ text │ Current message group number │ │ 11-90 │ ^KZ │ text │ Current file area name │ │ 11-50 │ ^K2 │ text │ Current file area number │ │ 06-40 │ ^F( │ text │ Current file group name │ │ 06-42 │ ^F* │ text │ Current file group number │ │ 06-91 │ ^F[ │ text │ Download KBytes left today │ │ 11-79 │ ^KO │ text │ Minutes online left today │ │ 11-84 │ ^KT │ text │ Daily download limit, in kilobytes │ │ 11-81 │ ^KQ │ text │ Daily online time limit, in minutes │ │ 11-75 │ ^KK │ text │ Minutes online during this session only │ │ 11-76 │ ^KL │ text │ Seconds connected (always returns 0) │ │ 11-77 │ ^KM │ text │ Minutes online today (all sessions) │ │ 11-78 │ ^KN │ text │ Seconds used today (always returns 0) │ │ 06-126│ ^F~ │ text │ Download delay in minutes │ │ 06-33 │ ^F! │ text │ Minutes remaining until user allowed to download │ │ 06-76 │ ^FL │ text │ Netmail credit left to the user │ │ 11-86 │ ^KV │ text │ Name of the recipient of forwarded messages │ ├───────┴─────┴──────┴────────────────────────────────────────────────────┤ │ codes dealing with various system information │ ├───────┬─────┬──────┬────────────────────────────────────────────────────┤ │ 11-87 │ ^KW │ text │ Current node number │ │ 06-94 │ ^F^ │ text │ Total number of days the system has been active │ │ 11-65 │ ^KA │ text │ Total number of calls to the system │ │ 11-72 │ ^KH │ text │ Total number of users on the system │ │ 11-66 │ ^KB │ text │ Name of the last user on the system │ │ 11-67 │ ^KC │ text │ Number of messages in the Hudson messagebase │ │ 11-68 │ ^KD │ text │ Number of the first message in the Hudson base │ │ 11-69 │ ^KE │ text │ Number of the last message in the current base │ │ 11-48 │ ^K0 │ text │ Total number of messages in the active base │ │ 11-70 │ ^KF │ text │ Number of times the user has paged the Sysop │ │ 11-40 │ ^K( │ text │ Name of currently selected language (eg: ENGLISH) │ │ 11-71 │ ^KG │ text │ Day of the week (full name) │ │ 11-83 │ ^KS │ text │ Day of the week (abbreviated version) │ │ 11-73 │ ^KI │ text │ Current time (xx:xx:xx) │ │ 11-74 │ ^KJ │ text │ Current date (xx-xxx-xxxx) │ │ 11-80 │ ^KP │ text │ Version number of PB-Lib (x.xx) │ │ 11-82 │ ^KR │ text │ Baud rate (0 if the call is local) │ │ 11-85 │ ^KU │ text │ Minutes until the next system event │ ├───────┴─────┴──────┴────────────────────────────────────────────────────┤ │ codes dealing with various actions to be performed │ ├───────┬─────┬──────┬────────────────────────────────────────────────────┤ │ 11-42 │ ^K* │ exec │ Wait for Enter from user, with prompt displayed │ │ 11-88 │ ^KX │ exec │ Hang up the phone (regular programs terminate) │ │ 11-33 │ ^K! │ exec │ Display a text file: ^K!filename|, where the name │ │ │ │ │ of the file may not include a path or extension as │ │ │ │ │ the file is expected to be in the textfiles direc- │ │ │ │ │ tory and have an extension .AVT/.ANS/.ASC (in that │ │ │ │ │ order. Note the '|' at the end of the name). │ │ 11-36 │ ^K$ │ exec │ Execute another program: ^K$filename|, where the │ │ │ │ │ <filename> string can include path and extension. │ │ │ │ │ You can also pass parameters to the program; they │ │ │ │ │ must be separated with a space from the filename. │ │ │ │ │ You can use the *-codes in the options, if any. │ │ 11-93 │ ^K] │ exec │ Display language prompt: ^K]nn|, where "nn" is the │ │ │ │ │ number of the prompt to display (starting from 1) │ │ 11-126│ ^K~ │ exec │ Execute a pex program: ^K~filename|, where the │ │ │ │ │ filename may not contain a path or extension as it │ │ │ │ │ is expected to specify a file in the pex directory │ │ │ │ │ (and as such cannot have path specifications). You │ │ │ │ │ can use options, which should be separated from │ │ │ │ │ the filename by a space. Note the use of the '|' │ │ │ │ │ character to mark the end of the sequence. │ │ 11-91 │ ^K[ │ colr │ see the RemoteAccess colors reference /COLORS │ ├───────┴─────┴──────┴────────────────────────────────────────────────────┤ │ codes dealing with time bank balance and data │ ├───────┬─────┬──────┬────────────────────────────────────────────────────┤ │ 11-55 │ ^K7 │ text │ Time Bank time balance, in minutes │ │ 11-56 │ ^K8 │ text │ Time Bank KBytes balance │ │ 11-57 │ ^K9 │ text │ Time Bank time withdrawn (in minutes) │ │ 11-34 │ ^K" │ text │ Time Bank KBytes withdrawn │ │ 11-38 │ ^K& │ text │ Time Bank time loaned │ │ 11-39 │ ^K' │ text │ Time Bank KBytes deposited │ │ 11-41 │ ^K) │ text │ Time Bank date last used (xx-xxx-xxxx) │ │ 11-43 │ ^K+ │ text │ Time Bank time payback date (xx-xxx-xxxx) │ │ 11-58 │ ^K: │ text │ Time Bank time deposited, in minutes │ │ 11-61 │ ^K= │ text │ Time Bank KBytes payback date (xx-xxx-xxxx) │ │ 11-96 │ ^K` │ text │ Time Bank KBytes loaned │ ╘═══════╧═════╧══════╧════════════════════════════════════════════════════╛ Note that all "text" type codes can also justify their text within certain limits. To do this, place '@', '#' or '%' between the first and the last characters of the control code. The number of characters (including the two control code symbols) determine the maximum length of the field to display. If you use the '@' symbol, the text will be left-justified. To right-justify the string, use the '#' character. The '%' symbol causes the resulting text to be centered within the field. Note that if the text is longer than the field width requested, it will be truncated. Since you cannot have any special characters between the two control symbols except for the optional width symbols, you may need to place TheDraw (or similar drawing programs) in animation mode when you save the screen, rescan it and finally enter the control code. This will ensure that the codes do not have any ANSi escape sequences in-between. Now you can easily create complex ANSi screens with boxes and other neat things without worrying that the text, when replaced, will corrupt the display or "bleed over" into another field. s t r i n g m a c r o s r e f e r e n c e /MACROS ─────────────────────────────────────────────────────────────────────────── "String macros" are specially bound keywords which can be embedded in text prompts. Note that these are not usually used for display files (but they can be). Rather, these are used in any definable text string as specified by the program's language file. The string macros are formatted with a keyword (KEYWORD) bound between the delimeters ("@<" and ">@"). Note that the keywords are NOT case sensitive (that is, 'NAME' is the same as 'Name' or 'NaMe' as far as the program is concerned). Use this to your advantage in order to make your prompts more readable. You can also specify justification and length limiting values. The general macro looks like this: @<KEYWORD>@ ├┘├─────┘├┘ │ │ └─── last bounding characters │ └────────── the keyword (see the list below) └──────────── first bounding characters The 'KEYWORD' string in the example above will be replaced by the runtime information that it specifies. You can only use pre-determined keywords from the list below. Note that macros are divided into four groups: text substi- tution, action, environment access and color manipulation. There are some restrictions that apply to the different groups. Only "text" macros can use the justification and field width specification. Any of the "exec" macros that involve file names can specify the full file name and some of them allow command-line options to be passed to the program. ╒════════════════╤══════╤═════════════════════════════════════════════════╕ │ Keyword │ Type │ Explanation and notes │ ╞════════════════╪══════╪═════════════════════════════════════════════════╡ │ BAUD │ text │ Current baud rate (0 if local) │ │ CITY │ text │ Current user's city │ │ COUNTRY │ text │ Current user's country │ │ CURFILEAREA │ text │ Name of the active file area │ │ CURFILEAREA# │ text │ Number of the active file area, starting from 1 │ │ CURFILEAREADIR │ text │ Directory for the active file area │ │ CURFILEGROUP │ text │ Name of the current file group │ │ CURFILEGROUP# │ text │ Number of the current file group │ │ CURMENU │ text │ Name of the current menu (name only: GLOBAL) │ │ CURMSGAREA │ text │ Name of the active message area │ │ CURMSGAREA# │ text │ Number of the active message area (1..) │ │ CURMSGGROUP │ text │ Name of the active message group │ │ CURMSGGROUP# │ text │ Number of the current message group │ │ DATAPHONE │ text │ User's data phone │ │ DATE │ text │ Today's date (xx-xxx-xxxx) │ │ FIRSTNAME │ text │ User's first name │ │ HANDLE │ text │ User's handle (fixed alias) │ │ HIGHMSG │ text │ Highest message number in the current base │ │ ID │ text │ The level ID for this user (from the limits) │ │ LANGUAGE │ text │ Current language (root name only: ENGLISH) │ │ LASTDATE │ text │ Date of the last login (xx-xxx-xxxx) │ │ LASTTIME │ text │ Time of the last login (xx:xx:xx) │ │ LEVEL │ text │ User's access level │ │ LOWMSG │ text │ Lowest message number in the Hudson messagebase │ │ MNUDIR │ text │ Menu files directory │ │ MSGDIR │ text │ Hudson messagebase directory │ │ NAME │ text │ Full name of the current user │ │ NLDIR │ text │ Nodelist directory │ │ NODE │ text │ Current node number │ │ NUMMSG │ text │ Number of messages in the active messagebase │ │ NUMUSERS │ text │ Total number of users on the system │ │ NUMYELLS │ text │ Times the user has paged the sysop │ │ PASSWORD │ text │ Current user's password │ │ PEXDIR │ text │ Pex programs directory │ │ PVTDIR │ text │ Private uploads directory │ │ STARTDIR │ text │ Startup directory │ │ SYSDIR │ text │ ProBoard system directory │ │ SYSOPNAME │ text │ Name of the Sysop │ │ TIME │ text │ Current time (xx:xx:xx) │ │ TMLEFT │ text │ Number of minutes left online │ │ TMONLINE │ text │ Minutes spent online this session │ │ TOTALCALLS │ text │ Number of total calls to the system │ │ TOTALMSG │ text │ Total number of messages in the Hudson base │ │ TXTDIR │ text │ Text files directory │ │ UPDIR │ text │ Uploads directory │ │ USERREC │ text │ User record number in the base (starts from 0) │ │ VERSION │ text │ Version of the library (x.xx) │ │ VOICEPHONE │ text │ Current user's voice phone number │ │ PAUSE │ exec │ Wait for Enter (no prompt is displayed) │ │ CLS │ exec │ Clear the entire screen │ │ CLREOL │ exec │ Clear to the end of the current line │ │ BEEP │ exec │ Beep (both local and remote) │ │ WAIT │ exec │ Wait for 1 second │ │ HANGUP │ exec │ Hangup the phone (local programs will exit) │ │ %NAME │ env. │ Replaced by the contents of the MS-DOS environ- │ │ │ │ ment variable "NAME". Note the '%' symbol used │ │ │ │ in the macro. If the variable does not exist, │ │ │ │ the macro will NOT be parsed at all! │ │ !FILENAME │ exec │ Display a text file "FILENAME". Note that the │ │ │ │ file must be in ProBoard's textfiles directory │ │ │ │ and you should not specify an extension (.AVT, │ │ │ │ .ANS or .ASC will be used, as needed). │ │ ~FILENAME │ exec │ Run a PEX program "FILENAME". You cannot use a │ │ │ │ directory or extension. The pex file must be in │ │ │ │ the ProBoard's pex directory. You can specify │ │ │ │ command-line options to be passed to the pex, │ │ │ │ in which case you must separate them from the │ │ │ │ pex name with a space (they must be within the │ │ │ │ macro bounds, though). You can also use any of │ │ │ │ the *-code text substitution macros in the list │ │ │ │ of options. Refer to /OPTIONS section. │ │ $FILENAME │ exec │ Run a regular executable "FILENAME". Unlike the │ │ │ │ pex, you can specify the full path to the file │ │ │ │ to be run. If the extension is omitted, .COM, │ │ │ │ .EXE and .BAT will be tried, in that order. If │ │ │ │ no path is specified, a standard MS-DOS search │ │ │ │ will be performed: current directory first and │ │ │ │ then the directories in the PATH statement. │ │ ]nnn │ exec │ Display language prompt "nnn", where "nnn" is │ │ │ │ number of the prompt, starting from 1. This │ │ │ │ uses the currently ative ProBoard language file │ │ #n │ colr │ Change color. Refer to the /COLORS section for │ │ │ │ the acceptable color codes. Note that you can │ │ │ │ specify the foregroun color only (one digit), │ │ │ │ with the background defaulting to black in this │ │ │ │ case, or both background and foreground, in │ │ │ │ which case, the background must be specified │ │ │ │ first, and the foregroun - second after the '#' │ │ │ │ special character. This is the same as others. │ ╘════════════════╧══════╧═════════════════════════════════════════════════╛ There are also several special ways to justify the macro. The default is to display it left-justified. To specify the maximum length that the macro can occupy, you would specify the number after a colon, like this: @<KEYWORD:-nn>@ ├┘├─────┘││├┘├┘ │ │ │││ └───── last bounding characters (required) │ │ ││└─────── maximum field width (required, 1..80) │ │ │└──────── justification code (optional) │ │ └───────── colon separator (required) │ └──────────────── the keyword (see the list above) └────────────────── first bounding characters (required) Note that whenever you use a width specifier, the text replacement will be exactly that width characters long. If the text is shorter, it will be padded as necessary (depending on the justification mode). If it is longer, it will be truncated (also depending on the justification). If you only specify the keyword (and no colon with parameters), the macro will be replaced with the text it represents and the result will occupy exactly as many spaces as needed by the text, left-justified. If you want to limit the width of the field, you would use the maximum number of characters in the place where "nn" is show in the example above. Note that the character preceding it is optional and will change the text justification within the specified limit. You must use the limit number if you want justification any other than the default left (this makes sense as the program must know where the right boundary is in order to center the text, for example). To right-justify the text, you would use a dash ("-") for the justification code. To center the string, you would use the percent symbol ("%") there. Note that justification and width specification is only available for text substitution macros and cannot be used with any of the action macros, the special environment replacement macro, or the color change macros. o p t i o n s f o r a c t i o n c o d e s /OPTIONS ─────────────────────────────────────────────────────────────────────────── All action macros and control codes that run external programs (both pexen and exe's) can use any of the following *-code options in the parameter list to pass to the programs. These are compatible with ProBoard's Function No. 7 - Shell optional data arguments. Note, however, that only some will be available in .exe files (marked below). All of these can be used in pexen coded with PB-Lib as ProBoard will then perform the actual expansion. ╒══════╤═════════╤════════════════════════════════════════════════════════╕ │ code │ pex/exe │ description │ ╞══════╪═════════╪════════════════════════════════════════════════════════╡ │ ** │ pex/exe │ replaced by an asterisk ('*') │ │ *# │ pex/exe │ replaced by the node number │ │ *\ │ pex │ sends the message "Sysop is shelling..." to the user │ │ *! │ pex │ freezes proboard's system timer when shelling │ │ *= │ pex │ do not call any fossil functions when shelling │ │ *A │ pex │ writes user's handle to DORINFOx.DEF instead of name │ │ *B │ pex/exe │ current baud rate │ │ *C │ pex/exe │ full name & path of the command interpreter (COMSPEC) │ │ *D │ pex │ write 52-line DOOR.SYS file to the current directory │ │ *E │ pex │ writes RA 1.1x EXITINFO.BBS to the current directory │ │ *F │ pex/exe │ user's first name │ │ *G │ pex │ indicates whether user has ANSI (1) or ASCII (0) set │ │ *H │ pex │ do not disable the fossil driver when shelling │ │ *I │ pex │ maximum user-inactivity (seconds) │ │ *L │ pex/exe │ user's last name │ │ *M │ pex/exe │ proboard's start-up directory (including trailing '\') │ │ *N │ pex │ shell will NOT be logged in PROBOARD.LOG │ │ *O │ pex/exe │ (not zero!) the path of the current file area │ │ *P │ pex/exe │ com-port used by proboard (1-8). │ │ *Q │ pex │ don't let user know that proboard is shelling (!) │ │ *R │ pex/exe │ user's record number in USERS.BBS │ │ *S │ pex/exe │ proboard's system directory (incl. trailing '\') │ │ *T │ pex/exe │ time left for the user today (minutes). │ │ *V │ pex │ don't add 2 to graphic line in DORINFOx.DEF for Avatar │ │ *W │ pex │ runs the shell in a window, status line not cleared │ │ *X │ pex │ always swap to disk/ems, even if swapping is disabled │ │ *Y │ pex │ do not swap to disk/ems │ │ *Z │ pex/exe │ same as entering "*C /C <command>" (for batch files) │ │ *_ │ pex │ don't use underscores in user's last name, DORINFO.DEF │ │ *0 │ pex │ (zero) write DORINFO1.DEF instead of DORINFO<node>.DEF │ │ *1 │ pex │ redisplay the status line of first line of the screen │ │ *2 │ pex │ same as *1, but uses the bottom line of the screen │ ╘══════╧═════════╧════════════════════════════════════════════════════════╛ Also note that you can use the options anywhere in the data specification line (for example, to specify the program PBUTIL.EXE located in the system directory, you would use *MPBUTIL.EXE). For batch files (or when you want the PATH searched for the program specified on the command line), you need to use the *Z code instead if the *C code. For example, to run the batch file D:\SBIN\ROTATE.BAT, you would use "*Z D:\SBIN\ROTATE.BAT" as the data. v a r i o u s e x a m p l e s /EXAMPLES ─────────────────────────────────────────────────────────────────────────── Here are string macro examples for the text substitution keywords. We will use the keyword "NAME" in all examples. This keyword will be replaced by the user's full name at runtime by the program. @<NAME>@ - display name, left-justified, unbound length @<NAME:35>@ - display name, left-justified in a 35-character field @<NAME:-35>@ - display name, right-justified in a 35-character field @<NAME:%35>@ - display name, centered in a 35-character field Here are string macro examples for the action keywords. We will use the filename "hello" for an example filename (it may or may not include the directory specification and file extension, refer to the notes that came with your programs for relevant exceptions to this or some other restrictions or requirements the application may have). Note that you cannot use the formatting codes as in the text substitution macros. You can, however, use the *-codes (*P. *S, etc.) as parameters to the macros that run pex and exe programs. @<PAUSE>@ - stop until Enter is pressed, no prompt issued @<HANGUP>@ - hangs up the phone (or aborts local programs) @<!hello>@ - display HELLO.A?? file from the textfiles directory @<]159>@ - display prompt 159 from the current language file @<~hello>@ - run the HELLO.PEX program from the pex directory @<$hello>@ - run a HELLO.COM, HELLO.EXE or HELLO.BAT (must be in the PATH or in the current directory) @<~hello -y /35>@ - run HELLO.PEX with "-y /35" as commandline options @<$hello.exe *S>@ - run the HELLO program with *S expanded Here are string macro examples for the environment substitution keyword. Note that you cannot use justification or field with codes with this macro. @<%PROBOARD>@ - expands to the content of the environment variable PROBOARD. If none is defined, will not expand at all (i.e. @<%PROBOARD>@ will be displayed). While this may seem odd, it certainly makes easier to track down mistakes, which are common anyway. Here are string macro examples for the color change keyword. Note that these cannot contain any text justification or field width codes and that they are executed immediately when encountered. @<#7>@ - change attribute to grey on black @<#13>@ - change attribute to dark cyan on blue @<#F>@ - change attribute to bright white on black @<#8F>@ - change attribute to blinking white on black Note that these are absolutely the same as the other hex color systems except that it allows for the foreground color to be specified only, in which case the background is set to black. Also note that the handling differs slightly with the way ProBoard handles the color change macros. Here are text code examples that show the use of text substitution codes. We will use the user's name code (^FA) for simplicity. A - left justified, no maximum width specified @@@@@@@@@@@@@@@A - left justified, in a 17-character field (15+2) ###############A - right justified, in a 17-character field %%%%%%%%%%%%%%%A - centered, in a 17-character field Here are some examples that show the use of action codes. Note that you cannot use the special formatting and justification characters here. We will use the 'HELLO' string as a sample for a filename. Special notes are provided where necessary as to the expected whereabouts of the file. !HELLO| - displays text file HELLO.A?? in the textfiles directory $HELLO| - run the HELLO program. You can use full path for the name: $C:\BIN\HELLO.EXE|. If you do not provide an extension, the following will be matched (in this order): COM/EXE/BAT. If you do not provide a path, the current directory will be searched, and then the PATH environment will be used in an attempt to locate the file. It is advisable that you always use the full file name and extension to avoid costly errors. You can pass parameters: $HELLO /N*#|, where '*#' will be expanded to the current node number. ]129| Display language prompt 129 from the current language file. ~HELLO| Run the pex HELLO.PEX in the pexfiles directory. You cannot use directory or extension in the filename specification. You can pass options to the program, separated with a space from the name. You can use any of teh *-codes which will be expanded by the program: ~HELLO *S| h e x a d e c i m a l c o l o r r e f e r e n c e /COLORS ─────────────────────────────────────────────────────────────────────────── The hexadecimal color specification has gained a lot of popularity on the BBS scene. Most systems support slight variations of the same basic hex format. "Hexadecimal" is a number system which is based on 16 instead of 10 (which is the familiar decimal system we commonly use). The reason for using the hexadecimal system is simple - there are 16 possible colors in text mode applications today. There are a couple of rules which most of the supported formats follow: o the allowable characters are 0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F o the hex value always uses two characters o the first character is the background color o the second character is the foreground color o there are only 8 colors that vary in intensity and blink o to make the foreground blink, add 8 to the background o to make the foreground high intensity, add 8 to the foreground In the examples and notes that follow, "**" denotes the background/fore- ground color combination that forms the color attribute. The Hexpipe Color System uses |** to specify the color attribute (note that this is not the same as Renegade or IceEdit's color codes). PCBoard uses @X** to specify the color. Wildcat! uses @**@ for the attribute. RemoteAccess uses ^K[**, and ProBoard uses \**. There are slight variations with the ProBoard color system which are supported and are explained below. Note that while the PB-Lib interpreter is not generally case-sensitive, you should not assume that other applications are not as well. Therefore, you should always use the capital case letters for the hex colors. ╒═════╤═══════════════╤═══════════════════╤════════════╤════════════════╕ │ Hex │ Foreground │ Notes │ Background │ Notes │ ╞═════╪═══════════════╪═══════════════════╪════════════╪════════════════╡ │ 0 │ black │ low int. black │ black │ │ │ 1 │ blue │ low int. blue │ blue │ │ │ 2 │ green │ low int. green │ green │ │ │ 3 │ cyan │ low int. cyan │ cyan │ │ │ 4 │ red │ low int. red │ red │ │ │ 5 │ magenta │ low int. magenta │ magenta │ │ │ 6 │ brown │ low int. yellow │ brown │ │ │ 7 │ light gray │ low int. white │ light gray │ │ │ 8 │ dark gray │ high int. black │ black │ fore. blinking │ │ 9 │ light blue │ high int. blue │ blue │ fore. blinking │ │ A │ light green │ high int. green │ green │ fore. blinking │ │ B │ light cyan │ high int. cyan │ cyan │ fore. blinking │ │ C │ light red │ high int. red │ red │ fore. blinking │ │ D │ light magenta │ high int. magenta │ magenta │ fore. blinking │ │ E │ light yellow │ high int. yellow │ brown │ fore. blinking │ │ F │ light white │ high int. white │ light gray │ fore. blinking │ ╘═════╧═══════════════╧═══════════════════╧════════════╧════════════════╛ This chart allows you to easily see the effect on each hex digit when used either as a foreground or as background character. The notes that specify the intensity are provided for your convenience so you can discern the relationship between the 8 basic colors and their variations. It's all actually rather simple. Just don't forget that the first color code in the specification is the background character. Some examples follow. Hexpipe Color Examples. These are quite common within FILE_ID.DIZ file descriptions and the such. Very easy to use: |01 - dark blue on black |81 - blinking blue on black |10 - black on dark blue |90 - blinking black on blue PCBoard-style color codes. These are common on the underground BBS scene where some people prefer to use this format to ANSi (as the files that use it are still somewhat readable for humans... or so they claim). @X1E - bright yellow on blue @XFF - blinking white on light gray @X00 - black on black (hidden) @X80 - blinking black on black The Wildcat! color system is also very similar to PCBoard, except it uses a terminator character instead of the 'X' in the color string: @4C@ - bright red on red @5E@ - bright yellow on magenta @CLS@ - not color (clear screen) @6F@ - bright white on brown Because of the similarity of PCBoard and Wildcat! codes, if you choose to support one of them, the other is automatically supported too. Note that the special @CLS@ code is also used and will cause the screen to be cleared using the current color attribute. RemoteAccess supports special color codes in strings and text files. These can be used with PB-Lib programs too. The general format is somewhat close to the text control characters described earlier. You have a start of sequence character (^K), the '[' character, followed by the two digit color attribute (note that ^K is one character with ASCii value of 11) ^K[0F - bright white on black ^K[8F - blinking white on black ^K[CE - blinking yellow on red ^K[35 - magenta on cyan (yuick!) The ProBoard color code system (as used in the language files) is a little more involved as it allows for simplifications in the color specification. There are two distinct formats (the one is actually a string macro) and both of them have two variations each (talk about confusion!). To simplify things, I will list all the additional variations below. The first format uses \** for the color attribute. This is consistent with the previously discussed formats (most similar to the hexpipes): \01 - dark blue on black \09 - light blue on black \81 - blinking dark blue on black \89 - blinking light blue on black There is a simplified notation which allows you to specify the foreground color and its intensity only instead of the whole attribute. Note that this causes the background to be set to black regardless of the current value. You would use either 'L' (low) or 'H' (high) as the first letter to specify the intensity of the second (the foreground). You can no longer use the hexadecimal values for the foreground either. Here's the complete list of allowable codes (note that the second letter is a color mnemonic): \HB - bright blue \LB - dark blue \HG - bright green \LG - dark green \HC - bright cyan \LC - dark cyan \HR - bright red \LR - dark red \HP - bright purple (magenta) \LP - dark purple (magenta) \HY - bright yellow \LY - dark yellow (brown) \HW - bright white \LW - dark white (light gray) The other format actually uses the color change macro. It also allows for tow-character background/foreground specification, but also allows for a one character foreground-only attribute (in which case the background will be set to black regardless of the current value). Note the use of the '#' (pound sign) character to denote the macro type: @<#7>@ - black background, color is light grey @<#1F>@ - bright white on dark blue background (first character) @<#CC>@ - blinking bright red on dark red @<#F>@ - bright white on black background Now that you know you can use at least 6 different ways to change the colors, a question probably arises which one to choose. Well, it all depends. Most likely, the PB-Lib programs will have them all enabled unless otherwise noted in the application manuals. It is all a matter of personal preference. My choice would be either the hexpipe color system or the ProBoard \** colors. These produce a least cluttered string and are easy to follow. Note that you are not stuck with your choice, you can freely mix different codes in any strings (even though I fail to see how this can work to your advantage). Generally, do whatever you want! d i f f e r e n c e s w i t h p r o b o a r d /PROBOARD ─────────────────────────────────────────────────────────────────────────── This section outlines some major differences between the way that ProBoard handles text macros and control codes and the implementation in PB-Lib. While we strove to maintain compatibility with ProBoard, there are some nuances worth mentioning here. Invariably, all changes were forced by the need to improve on the current design. For example, ProBoard does not support any color system other than its native and the standard ANSi and Avatar/0 terminals. Also, it does not support any of the program execution macros and control codes. All text codes dealing with the time bank information have been added for PB-Lib and are not available in ProBoard. The flag formatting codes (for flags A, B, C, and D) do the same in ProBoard as the full 32-character string. We have a different implementation which allows you to split the flags into 4 chunks with 8 flags in each. ProBoard does not support macros or codes to display prompts from language files. This is a unique feature of PB-Lib and programs using it. The width specifiers for text control codes do not truncate longer strings in ProBoard. This sometimes messes up the display. PB-Lib will cut off all excess characters. The @<VERSION>@ macro and the ^KP text code return the version of PB-Lib and not the version of ProBoard. This makes a lot of sense in my dim-wit mind :-) A couple of new toggle reports have been added (check for mail/files). Also note that all strings for the on/off status display in lowercase (my personal preference as I always find capital letters harder to read). The sex reporting control code does not display the text from the language file. This is done on purpose. Now you can actually know how long the text is (it displays "male", "female" or "uknown"). The @<#n>@ color change macro behaves differently. When a single color is specified, it is the same as in ProBoard. The two-digit version is totally different (and offers more flexibility). The @<>@ macros let you center the text too (with the '%' justification code). ProBoard only lets you justify it to the left or right. There are probably other things that I can't recall right now. [eof] ───────────────────────────────────────────────────────────────────────────