The World of Computer Software

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

/ The World of Computer Software / World_Of_Computer_Software-02-385-Vol-1of3.iso / d / demos301.zip / DEMOSYS.DOC < prev next >

Wrap

Text File | 1993-01-15 | 81KB | 1,771 lines

DEMOSYS.DOC Last revised 01/15/93 Page 1 The DEMO System Wayne Software 113 Sheffield St. Silver Spring, MD 20910 General user documentation and tutorial -------------------------------------------------------------------------------- Table of Contents Table of contents ............................................... 1 What is The DEMO System? ........................................ 2 Shareware notice ................................................ 3 Legal stuff ..................................................... 3 Registration form for The DEMO System ........................... 4 The DEMO System documentation ................................... 5 Documentation syntax ............................................ 5 The DEMO System programs: DEMOMAKE.EXE .................................................. 6 The DEMO System viewer ........................................ 6 DEMOSAVE.EXE (registered users only) .......................... 6 Input files required to create the self-viewer................... 7 Commenting code ................................................. 7 Tutorial: Screen pages .................................................. 8 Program Example 1 ........................................... 9 Settings (SET) statements ..................................... 11 List of SET commands ........................................ 11 The screen display ............................................ 12 Program Example 2 ........................................... 13 ^ codes ..................................................... 14 Program Example 3 ........................................... 14 Environmental variables ..................................... 15 List of pre-defined environmental variables ............... 15 Program Example 4 ........................................... 16 Action commands ............................................... 17 List of action commmands .................................... 17 Primary vs alternate screens ................................ 18 Key definitions ............................................... 19 Program Example 5 ........................................... 21 Full-screen activities ........................................ 23 Program Example 6 ........................................... 24 How input fields are determined and how to do multi-column menus ..................................................... 26 Program Example 7 ........................................... 27 Keys defined by default ....................................... 29 Self-running demos ............................................ 30 Creating menuing systems ...................................... 31 Program Example 8 ........................................... 33 Using (GLOBAL) ................................................ 35 More labor-saving techniques .................................. 36 (SETn) statements ........................................... 36 Macros ...................................................... 38 Program Example 9 ......................................... 39 Included text ............................................... 40 DEMOSYS.DOC Last revised 01/15/93 Page 2 -------------------------------------------------------------------------------- What is The DEMO System? The DEMO System can can be used to create demonstration programs for text-only products. It allows you to specify branching to different display screens. It allows you to define unique actions based on almost any keyboard entry. This is an ideal vehicle for demonstrating bulletin boards and CD-ROM products without requiring the user to have any hardware. The DEMO System can be used to create menu systems. You can pop up a menu with several dozen options, allowing the user to pick an option or view more options. The user can be prompted for information. The DEMO System can be used to create help and tutorial systems. You can arrange help information in a tree-like structure and have the user branch around as necessary. The DEMO System creates an EXE version of your demonstration. This EXE version has imbedded CRC checks that prevent unauthorized tampering. The EXE version can be distributed without royalty payments. The EXE's are relatively small and can be placed on bulletin boards and floppy diskettes. DEMOSYS.DOC Last revised 01/15/93 Page 3 -------------------------------------------------------------------------------- Shareware notice The DEMO System is a shareware product. This is a "try it before you buy it" concept. If you find The DEMO System useful, you should pay the registration fee (US $50.00) to Wayne Software. Wayne Software 113 Sheffield St. Silver Spring, MD 20910 Upon registration, you will receive: * Fax support for problems. * A program called DEMOSAVE.EXE which takes EXE files created by the The DEMO System and recreates the control card statements. DEMOSAVE.EXE is not for re-distribution and is available only to registered users. * A disk copy of the current release of DEMOMAKE.EXE. You will also receive a current copy of all of Wayne Software's other freebie software products. Please print the following form, fill out a copy of it, and send it back to Wayne Software with payment. -------------------------------------------------------------------------------- Legal stuff No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any other language or computer language in whole or in part, in any form or by any means, whether it be electronic, mechanical, magnetic, optical, manual or otherwise, without prior written consent of Wayne Software. Wayne Software disclaims all warranties as to this software, whether express or implied, including without limitation any implied warranties of merchantability, fitness for a particular purpose, functionality, data integrity or protection. DEMOSYS.DOC Last revised 01/15/93 Page 4 -------------------------------------------------------------------------------- Registration form for The DEMO System Your name: _____________________________________________________________ Your company (optional): ____________________________________________________ Mailing address: ____________________________________________________________ ____________________________________________________________ City, State, ZIP: ___________________________________________________________ Country if not USA: _________________ Voice phone number: _________________________________________________________ Fax phone number: _________________________________________________________ Disk size (check one): 360K 5.25" ____ 1.2MB 5.25" ____ 720K 3.5" ____ 1.44MB 3.5" ____ Please register me as a paid user of The DEMO System. A check or money order for $50.00 (US) is enclosed. (Sorry. No credit card orders at this time.) Registration entitles you to: * Fax support for problems. * A program called DEMOSAVE.EXE which takes EXE files created by the The DEMO System and recreates the control card statements. DEMOSAVE.EXE is not for re-distribution and is available only to registered users. * A disk copy of the current release of DEMOMAKE.EXE. You will also receive a current copy of all of Wayne Software's other freebie software products. Mail to: Wayne Software 113 Sheffield St. Silver Spring, MD 20910 Additional comments? DEMOSYS.DOC Last revised 01/15/93 Page 5 -------------------------------------------------------------------------------- The DEMO System documentation The DEMO System documentation consists of two manuals: DEMOSYS.DOC: This manual explains the basics of how to create and compile the files used by The DEMO System. It includes a tutorial with examples. DEMOSYS.REF: This manual is a reference manual that explains each of the commands and how they are used. It also describes the syntax used by the DEMOMAKE.EXE program as well as by the viewer. While programming techies are inclined to skip tutorials, you should at least look through the sample control files (which are stored in the SAMPLES.ZIP file in the distribution file). Unlike other programs, the DEMOMAKE.EXE program itself is not interactive. You are expected to understand the program somewhat before you attempt to use it. -------------------------------------------------------------------------------- Documentation Syntax Throughout this documentation, required items are capitalized. Variables appear in lowercase letters. So "MD directory" indicates that you must type exactly the letters "M" and "D" (in either lowercase or uppercase form) whereas "directory" is to be filled in with some other word. Options are specified in square brackets. They can be left out if desired. "RUN [ string ]" indicates that you can use the RUN command on its own (which will leave you at the DOS prompt) or you can include a command to be executed (at which point you'll be returned to the demonstrator). When several options are available for a given command and, if any are used, you can only pick one, the options appear within one set of brackets and a vertical bar separates each. So "CALL screen [ KEYn | parms ]" says you can either use "CALL screen", "CALL screen KEYn", or "CALL screen parms". DEMOSYS.DOC Last revised 01/15/93 Page 6 -------------------------------------------------------------------------------- The DEMO System programs The DEMO System consists of three distinct programs: - DEMOMAKE.EXE: This program takes a control card file and (typically) stand-alone screen files, verifies and compiles the code, and generates a load file. DEMOMAKE.EXE then appends The DEMO System viewer to this file to make a single demonstration file. DEMOMAKE.EXE need not be distributed with your demonstration program; it is needed for creating demonstration programs, not for viewing them. - The DEMO System viewer: This program presents your demonstration presentation to the end user. The viewer is a self-contained program which will be called anything you want it to be. The DEMOMAKE.EXE program creates this viewer file for you. - DEMOSAVE.EXE: This program is distributed only to registered users and can *not* be distributed with your demonstration program. DEMOSAVE.EXE allows you to uncompile the demonstration file, allowing you to make changes even if you're missing some of the original input screens. It also provides you a complete list of all keys that are valid during any given screen, resolving all GLOBAL statements for you. DEMOSYS.DOC Last revised 01/15/93 Page 7 -------------------------------------------------------------------------------- Input files required to create the self-viewer At a mininum, The DEMO System requires an input file which contains control card statements. Typically, it also requires screen files. At least initially, the screen files are stored as separate files external to the control card file. All input files are ASCII text files. They should not contain any tab, page eject, or other non-printable characters. -------------------------------------------------------------------------------- Commenting code (I put this in its own little section because in most application language manuals, it's almost impossible to find out how to enter comments.) Comments can be imbedded within control cards in several ways: - You can include blank lines between control cards. - You can begin a line with either ":", ";", or "'". - You can designate a comment within a command line by beginning it with "/*". All comments are ignored by the DEMOMAKE program and do not end up in the compiled code that is actually processed by The DEMO System viewer. The use of comments is heavy recommended. DEMOSYS.DOC Last revised 01/15/93 Page 8 -------------------------------------------------------------------------------- Tutorial Screen pages: There are a great many types of commands available in the demonstration program. There are at least 35 unique commands, 12 settings, and several special operations. Despite the variety, the standard "unit" of the demonstrator is a screen page. Each screen page can have unique key-press logic assigned to it (pressing "G" may take you to another screen on one screen page, or it may take you out of the demonstrator entirely). Each screen page can also have other unique settings: the shape of the cursor can change, the constant logo (if any) can change, the colors can change. All standard screen pages have text screens attached to them; text which is displayed (such as a menu) presenting the user with information so they can select the desired options or else text displayed for informational purposes (as in a help screen). There are several special screen pages. These pages do not have any text screens attached to them. The special pages are: labels (subroutines which are executed at a key press), global definitions (key and other settings which apply to all screens defined after the global definition), set definitions (key and other settings which can be defined once and then invoked later in different screens on an as-desired basis), and "once" definitions (operations which are done once when the program loads and then are not done again; these might including loading unique fonts so you can have you logo appear as graphics characters). Screen pages are identified within your control file as statements that begin with a dash. All of the screen page statements have same basic format: - filename [ description ] /* Screen text is external - *ref [ description ] /* Screen text is imbedded - @label [ description ] /* Action-only pages - (GLOBAL) [ description ] /* Establish defaults for later - (SETn) [ description ] /* Provide recallable settings - (ONCE) [ description ] /* Done once only The "description" field is totally optional. It can be recalled by your program later if necessary using the environmental variable ^EFDESC^. Unlike comments, descriptions stay with the data and are retrieved if DEMOSAVE is run on the file. DEMOSYS.DOC Last revised 01/15/93 Page 9 Each regular screen page can consist of four classes of commands. Each of these classes of commands are optional for any given screen. Most screens will only have three of the four classes of commands and some types of screens cannot have one or more of the types. Each class is processed in the following order: (1) settings (cursor shapes, colors, etc; these are processed immediately when the screen is loaded) (2) the screen display (NOT allowed within labels, Global, Set, and Once-only screen pages) (3) action commands (these commands are processed sequentially after the screen is displayed; typically, action commands are only used within label screen pages; their use within Global screen pages is strongly discouraged and they are ignored within Set screen pages) (4) key definitions (what commands to do when a given key is pressed; these are processed only if the user presses the desired key; typically, key definitions do not appear within label pages) Although the classes are in fact processed in the above order, they can typically appear within the control card file in any order. A screen page is defined as ending when the first of any of the following conditions are met: - The end of the main control file is reached - Another screen page control statement is reached. - A QUIT, GOTO, SCREEN, KEYPRESS, or POP action command is encountered. Program Example 1: Let's start with a very simple control file. You want the program to pop up, say "Hello world", and then return to DOS. (For some reason, this is the standard "first program" example in most programming language books.) This example doesn't require a text screen at all (we'll add one later); you just need the following control card file: - @HI! A label screen page without much to it ECHO Hello world QUIT The first statement designates that this is a label screen page. The "A label screen page without much to it" is the description for the page. The description, again, was totally optional and you could have put anything you wanted to here. DEMOSYS.DOC Last revised 01/15/93 Page 10 The next two statements are action commands. They execute sequentially, without regard to key presses. Each statement is explained in the reference section below but the "ECHO" command displays a character string to the viewer's screen and "QUIT" gets you out of the program. Every demonstration program should have at least one "QUIT" statement in at least one screen page. Save these text lines as an ASCII file called EXAM01.CTL. Then issue the following command: DEMOMAKE EXAM01.CTL EXAM01.EXE When you run the EXAM01 file, you'll see some screen activity and get a final screen that looks something like this: DEMOMAKE (c)Copyright 1993, Wayne Software Last revised xx/xx/xx 23:24:56: Begin 23:24:56: Begin Pass 1 Processing 3 line 3 screen 1 in EXAM01.CTL Maximum number of keys per screen (including globals and actions): 6 23:24:57: Begin Pass 2 Reading screen 1 @HI! A label screen page without much to it Processed Macros: 0 Variables: 1 Strings: 4 Screen lines: 0 Keys (and actions): 6 23:24:57: Creating EXAM01.EXE 23:24:57: Done Not a heck of a lot to it. When you type the command EXAM01.EXE, you'll get something like the following: DEMO (c)Copyright 1993, Wayne Software Last revised xx/xx/xx -Hello world Well, not very exciting, was it? You could have added a CLS command to get rid of the copyright stuff but it basically worked the way you expected it to. Note that all programming examples are contained in the SAMPLES.ZIP file within the distribution file. DEMOSYS.DOC Last revised 01/15/93 Page 11 Settings (SET) statements: Settings (SET) statements are defined once for each screen page. If they are not defined by you, The DEMO System assigns certain default values for you. The setting statements available to you are as follows: SET CASE OFF /* The keypress "g" will be treated as "G" SET CASE ON /* "g" and "G" can each have their own actions SET CLS ON /* Clear the screen before this text page SET CLS OFF /* Do not clear the screen before this text page SET COLOR settings /* Define up to 8 color sets for color monitors SET CURSOR string /* Define a cursor to be used during full-screen SET KEYS CLEAR /* Clear all global key settings SET KEYS SETn /* Bring in key settings from setting "n" SET LOGO string /* Display a logo (text) somewhere on the screen SET MONO settings /* Define up to 8 color sets for monochrome users SET SETTINGS SETn /* Bring in SET settings from setting "n" SET TOP screen /* Define top level that program can POP to Most of these options won't make sense at this point and, frankly, you'll never use some of them. Commands which are needed in the examples will be explained briefly on an as-needed basis. Each command is fully discussed in the reference section. For reference, the default values (where applicable) for each of these are as follows: SET CASE OFF SET CLS ON SET COLOR 151 154 152 117 097 153 001 157 SET CURSOR _ SET MONO 150 070 007 157 150 070 007 157 DEMOSYS.DOC Last revised 01/15/93 Page 12 The screen display: For screen pages that allow a screen display, the screen itself is a block of text consisting of at most 25 lines, each usually no more than 80 characters in length. Initially, you can create the screen pages with either a text editor or by using a text capture program (such as PC Magazine's PRN2FILE program). For most presentations, you will end up using both techniques. These text pages can be stored as either separate external files (each file containing just one screen's worth of information) or else they can be imbedded within the control card file. The DEMOSAVE program (available only for registered users) recreates the control cards with all screens being imbedded. The chief advantage of imbedded screen files is one of control; it's easier to maintain a single combined file than it is to have lots of little screen files. The disadvantages are several; risks increase with only one file (lose the control file and you have to recreate everything from scratch or else use DEMOSAVE), larger files are typically harder to edit and maneuver around, and the DEMOMAKE.EXE program will actually have to process any imbedded text lines twice instead of once so compilation is slower. If the screen files are external, the screen page control card follows this format: - filename [ description ] /* Screen text is external The "filename" can include drive and path information if desired. Otherwise, the program will look for the file in your default directory unless you've provided a DATADIR command telling it to look for the files elsewhere. For imbedded screen files, the control card looks like this: - *ref [ description ] /* Screen text is imbedded The "ref" is a unique and short (one word) clue for what the screen text does (you can always add a fuller "description"). The shorter the better as far as the program is concerned but each reference must be unique. If the screen files are internal, the contents of the screen must be defined before the next screen control card statement is encountered. The screen is defined in a block of text that begins with "/." by itself on one line, followed by the up-to-25 lines of text, followed by "./" on a line by itself. DEMOSYS.DOC Last revised 01/15/93 Page 13 Program Example 2: Let's do the "Hello World" example using an imbedded screen file instead of the ECHO command. To do this, create the following control file as save it as EXAM02.CTL: - *DEMO An imbedded screen file /. Hello world ./ QUIT Remember the rules for what defines the end of a screen page. Among other things, a screen page ends when it hits a QUIT (or POP, GOTO, SCREEN, or KEYPRESS) action command. If you had placed the QUIT command before the imbedded text, the program would have misplaced the imbedded text and would have given you an error message. Compile this text file ("DEMOMAKE EXAM02.CTL EXAM02.EXE") and then run it ("EXAM02"). The screen will clear, the words "Hello there!" will appear, and you'll be left at the DOS prompt. DEMOSYS.DOC Last revised 01/15/93 Page 14 ^ codes: The screens themselves can include codes which establish colors, input locations, and other things. There are seven types of control codes that The DEMO System accepts in text strings (including logos and cursor indicators) but one of them (the "^Prow,col" indicator) should not be used within a screen. These codes are as follows: ^Cn /* Set the color to color (or monochrome) set "n" ^K /* Establish this as a keyboard-input field ^Evar^ /* Print an environmental variable here ^Tn /* Print "n" non-destructive spaces here ^Sn /* Print "n" destructive spaces here (used only /* to reduce the size of your input file; The DEMO /* System automatically uses space compression when it /* encounters five or more spaces together) ^Pr,c /* Locate the cursor at row "r" and column "c": /* this setting is not allowed within text screens /* themselves and should only be used in SET CURSOR, /* SET LOGO, ECHO, PROMPT, etc commands ^_ /* Ignored. Typically used only if you want to /* print out one of the other control key sequences Any text that is not part of these control codes (including spaces) are treated as text and is printed as is. Program Example 3: Okay, back to the "Hello world" example. In this case, we're going to print a text screen which contains the words "Hello world", then print a "Goodbye world" string on top of that screen, and then quit. Create the following control cards and save them as EXAM03.CTL: - *Overprinting Doing a screen, overprinting it, and then quitting /. ^S20^C1Hello ^C0world ./ ECHO ^P20,20^C2Goodbye ^C3world QUIT After compiling the program ("DEMOMAKE EXAM03.CTL EXAM03.EXE"), then running it ("EXAM03"), you'll see the screen clear, print a blank line, skip to column 20, print "Hello world" in two different colors, then skip 18 lines and print "Goodbye world" in two different colors underneath it. While these examples work as expected, they don't sound like anything you'd like to demonstrate, do they? We're getting there! DEMOSYS.DOC Last revised 01/15/93 Page 15 Environmental variables: Most text strings (including input pages) can contain both real and pseudo-environmental variables. These can include any variable defined in your DOS environment (such as PROMPT or PATH). The pseudo-variable can also include several variables within The DEMO System, passed variables, and user-defined variables. They also include variables that are defined in PROMPT statements and some others. All environmental variables appear as "^Evar^" (without the quotes). The DOS prompt, for example, is represented as "^EPROMPT^". If this character string appears as part of an output block (either a screen, or a logo, prompt, or ECHO result), the variable will be expanded into the proper string. (Some times, this will present problems. Avoid putting an environmental variable in a row that will not fit on the screen. Results are uncertain in these cases.) The variables predefined by The DEMO System include those listed below. Some of them may not have an immediately useful value but future changes to The DEMO System will make them relevant. ^EDATE^ the current system date (in mm/dd/yy format) ^ETIME^ the current system time (in hh:mm:ss format) ^EETIME^ the elapsed time that the user has used this program (in hh:mm:ss format) ^EFNAME^ the name of the screen input file ^EFDESC^ the description (if any) of the screen input file ^EFPAGE^ the sequential number of the screen input file ^EDIR^ the current default directory for the default drive (no slash appears at the end of the name) ^EINITDIR^ the initial default directory when the program was loaded (no slash appears at the end of the name) ^EDISPLAY^ the current display type (COLOR or MONO) ^EDISPLAYN^ the current display type (1=COLOR, 2=MONO) ^EFIELD^ the current field number ^ECOL^ the current screen column number ^EROW^ the current screen row number In addition, when using CALL and GOTO statements, you can pass one of more variables. These variables are assigned sequentially to the pseudo-environmental variables ^E1^ to ^E9^. Note that you can change regular DOS environmental variables (like PROMPT) but they are redefined only until your program completes. Once you go back to DOS, they're reset to whatever they started off to be. You can usually concatenate environmental variables with other variables and character strings. For example, the following usually works: KEY (PGDN) GOTO *006 KEY^EFIELD^ DEMOSYS.DOC Last revised 01/15/93 Page 16 Program Example 4: In this example, we'll generate a output screen that shows you the current definition of all of the environmental variables. Note that some of the variables won't really have applicable values unless they're used in specific cases. Create the following control cards and save them as EXAM04.CTL: - @MAIN This is the main screen CALL @FILE Apples are good for you! QUIT - @FILE This is the screen that displays everything ECHO DATE = ^EDATE^ ECHO TIME = ^ETIME^ ECHO ETIME = ^EETIME^ ECHO ECHO FNAME = ^EFNAME^ ECHO FDESC = ^EFDESC^ ECHO FPAGE = ^EFPAGE^ ECHO ECHO DIR = ^EDIR^ ECHO INITDIR = ^EINITDIR^ ECHO ECHO FIELD = ^EFIELD^ ECHO COL = ^ECOL^ ECHO ROW = ^EROW^ ECHO ECHO Passed parms: (1)=^E1^ (2)=^E2^ (3)=^E3^ ECHO Passed parms: (4)=^E4^ (5)=^E5^ (6)=^E6^ ECHO Passed parms: (7)=^E7^ (8)=^E8^ (9)=^E9^ POP Other than the environmental variables, there is a new action command included in this example. The CALL statement brings in another screen page. The word after the "CALL" must correspond to a page defined in a screen page statement. In this case, the screen page is a label page with no text screen at all. All information is displayed using ECHO commands. At the bottom of the page is the command "POP" which returns control to the statement after the call. CALL and GOTO are the primary way used to move from one display screen to another. CALL (and the related GOTO) command allow you to pass in up to 9 words (separated by one or more spaces) which become environmental variables ^E1^ to ^E9^. You could pass in file names, control ("^") text codes, or anything else you want. In this example, "Apples are good for you!" is passed in. "Apples" is assigned to ^E1^, "are" is assigned to ^E2^, etc. Variables ^E6^ to ^E9^ are left as blank. Compile this code ("DEMOMAKE EXAM04.CTL EXAM04.EXE") and then test it out ("EXAM04"). It will display some information on the screen and then quit. DEMOSYS.DOC Last revised 01/15/93 Page 17 Action commands: We've already used four action commands: CALL, ECHO, POP, and QUIT. There are 35 or more action commands available within The DEMO System. These are listed below. Some of them will be used in later examples and all are explained in the reference section at the end. Note that most action commands actually appear within label pages, not screen pages. Most of these action commands can be used in KEY statements (discussed next) but some (like RUN) will typically require a REDRAW command after executing; since you cannot assign two functions to a single keystroke, you will want to move these to label pages anyway. Action commands are ignored within SET pages and are not recommended within Global pages. Also note that most of the parameters can be replaced by environmental variables where desired. ASSIGN ^Evar^ [ string ] /* Assign a value to an environmental /* variable BEEP /* Beep BUFFER [ keys ] /* Put input characters into a buffer /* so self-running demoes can be done CALL screen [ KEYn | parms ] /* Call a label or screen, with the /* intention of returning to the /* current location CD directory /* Change to a given subdirectory CDD drive:directory /* Change to a given drive and subdir CLS /* Clear the screen COPY file1 file2 /* Copy file1 as file2 DELETE filename /* Delete a specified file DISPLAY COLOR /* Use SET COLOR color settings DISPLAY MONO /* Use SET MONO color settings DISPLAY TOGGLE /* Toggles between COLOR and MONO DRIVE letter /* Set the default drive ECHO [ string[@] ] /* Display a given string ECHOA [ string[@] ] /* Display a given string to the /* alternate screen FIELD change /* Move to a particular input field GOTO screen [ KEYn | CLEAR | parms ] /* Branch to a label or screen, /* intending to not return to the /* current screen KEYPRESS /* Wait for a keypress (automatically /* done in any screen text screen) LOCATE row col /* Move to a given row and column on /* the screen, can also be done with /* ^Pr,c in display string itself MD directory /* Make a subdirectory NONE /* Don't to anything; only used in /* key assignments DEMOSYS.DOC Last revised 01/15/93 Page 18 PAUSE [ seconds ] /* Wait for seconds to pass or until /* key is pressed PAUSEA [ seconds ] /* Wait on the alternate screen PAUSE BREAK ON /* Allow people to escape out of /* buffered sequences PAUSE BREAK OFF /* Don't allow people to escape PAUSE DEMO seconds /* Wait specified number of seconds /* before processing next key in the /* buffer PLAY string /* Play a given musical string PLAY ON /* Activate all PLAY commands PLAY OFF /* Turn off all PLAY commands POP [ TOP | 1 to 20 ] [ KEYn ] /* Return to some CALL statement PROMPT ^Evar^ pattern string /* Prompt user for some input QUIT [ return_code ] /* Return to DOS RD directory /* Remove a subdirectory REDRAW /* Redraw the current screen RUN [ string ] /* Run a DOS command RUNA [ string ] /* Run a DOS command to the /* alternative screen SAVE filename /* Save the current screen SCREEN change /* Switch to another screen WRITE filename string /* Write a line to a text file Action commands are executed sequentially after the screen text (if any) is displayed and before any user keypresses are processed (unless KEYPRESS appears). While several of the normal computer programming branching constructs, like GOTO and CALL statements, are implemented in The DEMO System, you will typically find they are implemented unusually in The DEMO System and you will need to develop work-arounds for some of them. Primary vs alternative screens: There are actually two screens that The DEMO System uses. The first screen, the "primary screen", is used automatically for all text screens and by most of the commands. The second screen, called the "alternate screen", is typically used when you want to run a DOS command and not have the output from this command affect the text screen the user is viewing. Sometimes, you will want the output of the command to disappear completely. There are are number of commands that provide the capability of writing to either of these two screens: ECHO and ECHOA, PAUSE and PAUSEA, PROMPT and PROMPTA, and RUN and RUNA. In most cases, stick to the command without the suffix. DEMOSYS.DOC Last revised 01/15/93 Page 19 Key definitions: Okay. Time for the meat and potatos command within The DEMO System. Key definitions tell the program what it should do if the user presses a given character. Each key definition statement follows this basic format: KEY key[,key]... action_command [ options ] where, at least for some of the action commands, the options are, in fact, not optional. The "key" portion of the statement can be any regular character, like "R" (without the quotes). If you want to assign an action to them, there are four characters that have to be coded specially: = code as (EQUAL) space code as (SPACE) ( code as (LPAREN) , code as (COMMA) You can also define just about any other character on the keybard to do something. All of these keys are coded as a word in parentheses. These include all of the following keys which should be self-evident: (DEL) (ENTER) (INS) (PGUP) (UP) (DOWN) (ESC) (LEFT) (RIGHT) (F1) to (F12) (END) (HOME) (PGDN) (TAB) as well as some keys that may not be readily apparent or be standard: (BS) backspace key (A-key) Any letter key or F1 to F12 with Alt key pressed (A-n) Any key sequence generated by pressing the Alt key down, and, while keeping it down, pressing one to three digits on the numeric keypad (C-key) Any letter key, ENTER, BS, or F1 to F12 with Ctrl key pressed (S-key) TAB, DEL, INS, END, DOWN, PGDN, F1 to F12, etc with shift key pressed Note that all one-letter control keys are in fact defined as something else too. (C-M) internally is the same key as (ENTER), (C-I) is the same as (TAB), etc. You should watch out for this when you define your key sequences; only the first key assignment will win. You should also watch for this when you use the (A-n) convention. Most keys in the (A-32) to (A-126) range can be entered directly. Most of the keys before (A-32) are in fact keys like (ENTER) and (BS). If you have one key assigned with something like (A-62) and another key defined as ">" (decimal value 62), the first key defined will always win. DEMOSYS.DOC Last revised 01/15/93 Page 20 You can assign multiple keys to the same action if desired, either on separate KEY statements or else by separating each key with a comma *only* (don't put any spaces around the comma). Three mouse-related "keys": (MOUSER) right mouse button pressed (MOUSEL) left mouse button pressed (MOUSEB) both left and right mouse buttons pressed Full-screen field related keys: @1 to @90 field-selections 1 to 90 And two very special "keys": (ELSE) any non-defined key was pressed (ANY) any key was pressed (LASTKEY) the last user key pressed; only allowed in BUFFER cmd The "action_command" and "[ options ]" part of the KEY statement is the same as were mentioned above. Typically, you will have key presses either call another screen or go to another screen. The difference between a CALL and a GOTO is whether you want to be able to return easily to where you were when you issued the command. You might use a CALL statement from a main menu, which offers the user several choices and then ultimately returns the user to the menu. You might use a GOTO statement when you have several pages of information to present to a user and you want PgDn to simply goto the next screen of information. DEMOSYS.DOC Last revised 01/15/93 Page 21 Program Example 5: It's time for a more useful example. In this case, you're going to have a menu with two branching options as well as a "quit" option. The program will contain three screens: a main menu and the two subsequent screens (one of which is a label screen). We won't use any full-screen options at this point. Create your control card file EXAM05.CTL: - *001 Main menu KEY A,(MOUSEL) CALL *002 KEY B,(MOUSER) CALL @003 KEY Q,(MOUSEB) QUIT /. Select an option: A. Display the current date and time (left mouse button) B. Do a directory of the default subdirectory (right mouse button) Q. Quit (both buttons) ./ - *002 Display the current date and time KEY (ANY) POP /. Current date: ^EDATE^ Current time: ^ETIME^ Elapsed time: ^EETIME^ Press any key to return to the main menu ./ - @003 Do a directory RUN DIR /W ECHO Press a key to return to the main menu PAUSE POP DEMOSYS.DOC Last revised 01/15/93 Page 22 This example has three KEY statements appearing in the first screen alone: KEY A,(MOUSEL) CALL *002 KEY B,(MOUSER) CALL @003 KEY Q,(MOUSEB) QUIT When an "A" character or the left mouse button is pressed, the first KEY statement calls screen "*002", which has some imbedded text. When a "B" character or the right mouse button is pressed, the second KEY statement calls the label "@003", which has some RUN and ECHO commands in it. "SET CASE OFF" is the default setting so "a" and "A" are treated the same as are "b" and "B". The third statement quits the program when a "Q" (or "q") or both mouse buttons are pressed. Screen *002 contains another KEY statement: "KEY (ANY) POP". This says that if the user presses any key (including either mouse key), the program will return to the previous CALL statement. In this case, it will return to *001, from which the CALL statement was made. Several new action commands are used here. The "RUN DIR /W" command shells out to the DOS command processor, and runs a directory command with the "/W" (wide) option. "PAUSE" waits for the user to enter any keystroke and then goes on. The ^Evar^ items (like ^ETIME^) in *002 are environmental variables which were discussed above. Compile this code ("DEMOMAKE EXAM05.CTL EXAM05.EXE") and then test it out ("EXAM05"). The screen will clear, you'll get a small menu, you can pick any of the options by using the first character. When you're done, press Q and you'll be returned to DOS. This is a typical example for a demo set up for a bulletin board. In BBS's, you typically select an item by pressing a mnemonic key. There is usually no ability to do any selections using cursor keys. Non-BBS applications, on the other hand, allow users to select options based on moving the cursor and pressing Enter. For this, you need to know some full-screen functions. DEMOSYS.DOC Last revised 01/15/93 Page 23 Full-screen activities: Full-screen systems typically allow the user to move around the menu using the cursor keys. For example, a list of 10 items might be presented vertically on the screen and you're able to use the up and down cursor keys to position the cursor to the item you want. Then you press Enter. The DEMO System allows this as well. There are a number of things that have to be decided: * What user-selectable fields are there? What format will they have on the screen? Are they arranged in columns or vertically? Or are they some combination of both? * What keys can be used to maneuver around the screen and what do they do? A vertical list might support just the up and down arrow keys. But typically, you will also want to support the Home and End keys to move to the first and last item on the list. If you have a menu with vertical lists in several columns, you may want to add support for the right and left arrow keys. * What should the cursor look like? Should it be something like a greater-than symbol (">"). Or should it be a different-colored text block? Or should it be parentheses around the current item, perhaps also in a different-colored text block? * Where do you want the cursor to start in each field? One space before the item? Two spaces? Three? Maybe the cursor is "==>"; four would be appropriate for that. Maybe the cursor appears *after* the item? In The DEMO System, all input screens are in fact text screens. If you want to designate fields within the screen, you use the "^K" character combination where you want the field location to begin. You can designate up to 90 input areas per screen. For single-column presentations, you can skip lines all you want. For multi-column presentations, there are some other things to consider. We'll cover the simpler single-column presentation first. DEMOSYS.DOC Last revised 01/15/93 Page 24 Program Example 6: In this example, we're going to do a short menu based on the screens in example 5. This menu will allow the user to use the arrow keys to get around. The input selections are arranged in a single column (you can guess what example 7 will cover!). Create your control card file EXAM06.CTL: - *001 Main menu SET CURSOR ^C2=> KEY (UP) FIELD -1 KEY (DOWN) FIELD 1 KEY A,@1 CALL *002 KEY B,@2 CALL @003 KEY Q,@3 QUIT /. Select an option: ^K A. Display the current date and time ^K B. Do a directory of the default subdirectory ^K Q. Quit ./ - *002 Display the current date and time KEY (ANY) POP /. Current date: ^EDATE^ Current time: ^ETIME^ Elapsed time: ^EETIME^ Press any key to return to the main menu ./ - @003 Do a directory RUN DIR /W ECHO Press a key to return to the main menu PAUSE POP The *002 and @003 screens are identical to what they were originally. What's been added are the full-screen commands in the first screen. Checking the changes line by line, the first new statement is: SET CURSOR ^C2=> This establishes a cursor as "=>" which will be printed using color set 2 (which defaults to white on green). The next lines establish what happens when the up and down arrow keys are used: KEY (UP) FIELD -1 KEY (DOWN) FIELD 1 DEMOSYS.DOC Last revised 01/15/93 Page 25 If (UP) is pressed, the cursor will move from the current field to the previous field. If it's at the top item, it will be moved to the bottom item. If (DOWN) is pressed, the cursor will move from the current field to the next field. If it's at the bottom item, it will be moved to the top item. These two keys don't actually select any of the items on the list. They simply determined where the cursor would be placed. If Enter is pressed, the key statement designated with that input field's number will take affect: KEY A,@1 CALL *002 KEY B,@2 CALL @003 KEY Q,@3 QUIT If the cursor is at the first field when Enter is pressed, page *002 will be executed. If it's at the second field, then label page @003 will be executed. If it's at the third field, the user will drop to DOS. The actual designation of what fields are defined in done in the screen portion: /. Select an option: ^K A. Display the current date and time ^K B. Do a directory of the default subdirectory ^K Q. Quit ./ The "^K" combination is used three times so there are three user-selectable fields. Note that there are three spaces between the "^K" and the item letter. This means that there will be one space between the cursor (which is two characters long) and the item letter. Note that the cursor will skip all lines that don't contain a ^K designator. Compile this code ("DEMOMAKE EXAM06.CTL EXAM06.EXE") and then test it out ("EXAM06"). The screen will clear, you'll get a small menu, and you can pick any of the options by using either the first character or by using the cursor keys and then pressing Enter. When you're done, press Q or move the cursor to the Q option and press Enter. You'll then be returned to DOS. DEMOSYS.DOC Last revised 01/15/93 Page 26 How input fields are determined and how to do multi-column menus: The DEMO System detects input fields in the order they are found in the screen file. The fields are numbered from the first column to the last column, first line to last line. The "KEY (DOWN) FIELD 1" statement tells The DEMO System to move the cursor from the current field location to the next field location. If that field location is on the next line, the cursor will physically move down. If, on the other hand, that field is on the current line, the cursor will instead move physically right instead of down. The DEMO System does not try to make the (DOWN) key move to the next line. As far as The DEMO System is concerned, the key sequence for (DOWN) is defined as an action command; that action command, not the key itself, are processed during a demonstration. If you have a multicolumn input screen, you will have to select your key locations more carefully. Typically, you will want to insure that all columns have the same number of input fields. You will want to do this even if there are cells that are missing in a given column. (The reason for this will make sense in the example that follows.) Keep in mind that any keys that aren't defined for The DEMO System are in fact ignored. If someone positions the cursor at a field for which you don't have any KEY statements and presses Enter, nothing happens. Let's design a screen with multi-column user inputs. DEMOSYS.DOC Last revised 01/15/93 Page 27 Program Example 7: In this example, we're going to do a multi-column menu. The menu selections don't actually do much (we need to keep the example short). This menu will allow the user to use the arrow keys to get around. Create your control card file EXAM07.CTL: - *SCR Basic input screen SET CURSOR ^C2(^T8) KEY (RIGHT) FIELD 1 KEY (LEFT) FIELD -1 KEY (UP) FIELD -3 KEY (DOWN) FIELD 3 KEY (HOME) FIELD TOP KEY (END) FIELD BOTTOM KEY @1 CALL @DISPLAY Field 1 KEY @2 CALL @DISPLAY Field 2 KEY @3 CALL @DISPLAY Field 3 KEY @4 CALL @DISPLAY Field 4 KEY @5 CALL @DISPLAY Field 5 KEY @6 CALL @DISPLAY Field 6 KEY @7 CALL @DISPLAY Field 7 KEY @8 CALL @DISPLAY Field 8 KEY @10 CALL @DISPLAY Field 10 KEY @11 CALL @DISPLAY Field 11 KEY @13 CALL @DISPLAY Field 13 KEY @14 CALL @DISPLAY Field 14 KEY @15 QUIT /. Use the cursor keys to select a cell below: ^K Field 1 ^K Field 2 ^K Field 3 ^K Field 4 ^K Field 5 ^K Field 6 ^K Field 7 ^K Field 8 ^K ^K Field 10 ^K Field 11 ^K ^K Field 13 ^K Field 14 ^K Quit ./ - @DISPLAY ECHO ^P10,10^C2You selected ^E1^ ^E2^ PAUSE 2 /* Waits for two seconds or a user keystroke POP For instructional purposes only, the text screen labels the fields sequentially in the order that the program sees them (left to right, top line down). There's no reason you'd have the user see something like "Field 4" when they selected something. The (RIGHT) and (LEFT) KEY statements do about what you'd expect them to do. They move the cursor one field to the left or right ("KEY (RIGHT) FIELD 1" moves it one field to the right). When the cursor is on the last field of a row, pressing (RIGHT) will move it to the first field of the next row. Pressing (LEFT) will do the reverse. DEMOSYS.DOC Last revised 01/15/93 Page 28 The (UP) and (DOWN) key statements had to trick the program. If you want the cursor to move down to the cell immediately below the current one, the program has to be told to move the cursor over three fields. If, for example, the cursor is on field 1, "SET (DOWN) FIELD 3" tells the program to move to field 1 --> 2 --> 3 --> 4 and stop there. If you want to, test out this example eliminating those "unused" ^K designators. When the (ENTER) key is pressed, if there is a key field defined on the screen, the program checks to see where the cursor is currently positioned. It then executes any KEY statement found for that particular field position. These KEY statements provide the field position as "KEY @n action_command", where "n" is the field number. (Any "KEY (ENTER) action_command" statements are ignored if there are fields defined on the screen. You have to use cursor movements if you've defined fields.) There are two fields, fields 9 and 12, which don't have an text next to them. If you look through the key assignments, you'll notice there are no corresponding "KEY @9 action_command" or "KEY @12 action_command" statements. These are dummy fields. The cursor will be allowed to rest on these fields but if the user presses (ENTER), nothing happens. Notice the SET CURSOR assignment too. This one: SET CURSOR ^C2(^T8) sets the cursor to a different color, prints a left parenthesis, skips 8 characters (not printing over what's already there on the screen), and then prints the right parenthesis, still in the different color. This is fairly common in full-screen systems. Compile this code ("DEMOMAKE EXAM07.CTL EXAM07.EXE") and then test it out ("EXAM07"). The screen will clear, you'll get a small menu, and you can pick any of the options by using the cursor keys and then pressing Enter. When you're done, press Q or move the cursor to the Q option and press Enter. You'll then be returned to DOS. DEMOSYS.DOC Last revised 01/15/93 Page 29 Keys defined by default: The DEMO System pre-defines four key combinations for you. They are defined for debugging and "whoops!" purposes. These assignments are: SET (C-C) QUIT SET (C-F1) ECHO ^P25,65^EFNAME^@ SET (C-J) RUN SET (C-R) REDRAW The first assignment provides a QUIT definition, allowing you to get out of the program. This is often necessary because it frequently turns out that even when you remember to code one of more QUIT statements in your program, you code a screen that leaves you in any infinite loop. (The most common way to do this is to have a page which calls itself.) The second assignment tells you the current screen name. This is useful when you're viewing a demo and you notice that you need to make a change to a particular screen. Maybe you forgot to code a key assignment or the characters don't align properly. The third assignment allows you to jump to DOS. You need to say "EXIT" at the command line in order to be returned to The DEMO System. This is useful for checking directories, making sure required files are present, etc. The fourth assignment redraws the current screen for you. This is frequently useful when you've done something like run a DOS command which has messed up your display screen and you need to get the menu back on. (You can also do this with a "SCREEN 0" command although that command behaves somewhat differently. See the reference manual.) You can reassign these keys if desired by doing specific reassignments (e.g. "SET KEY (C-C) GOTO @HOME" or "SET KEY (C-F1) (NONE)"). They provide some useful functionality though and defining other keys to do the same thing is recommended if you need these key sequences for something else. DEMOSYS.DOC Last revised 01/15/93 Page 30 Self-running demos: You may find yourself wanting to create some self-running demos, where the user's keys are in fact pressed for them. The user will see the results of each key press (e.g. the cursor will move). This may be desirable for an entire presentation or just for parts of a presentation. Several action commands relate to this capability: BUFFER [ keys ] KEYPRESS PAUSE BREAK ON PAUSE BREAK OFF PAUSE DEMO seconds The BUFFER command pushes keystrokes into a keystroke buffer. Each keystroke is retrieved sequentially on a first-in, first-out basis whenever a KEYPRESS command is encountered or whenever the program awaits a keypress in a normal text screen. You can clear the buffer by skipping the "keys" parameter. The KEYPRESS command is typically used in a label screen to get a keypress from the buffer. Since label screens never wait for a keypress otherwise (except when executing PAUSE or PROMPT commands), this is the only way to have them register any user-defined inputs. PAUSE BREAK ON says that a user can escape out of buffered keystrokes by pressing the Escape key. Doing so clears the keystroke buffer. This is useful if you want them to be able to do something on their own instead of getting stuck with your keystrokes only. PAUSE BREAK ON is the default in The DEMO System. PAUSE BREAK OFF is the opposite of PAUSE BREAK ON. PAUSE BREAK ON is the default for The DEMO System. Note that it's possible to crash The DEMO System (as well as your reputation) through poor placement of a BUFFER command. Placing a BUFFER command in a screen that is frequently executed may result in the BUFFER being filled up and provide no convenient way for the user to get out. If you have PAUSE BREAK OFF in effect, you may provide yourself will no way out of an overflowing buffer. Having said this, PAUSE BREAK OFF is clearly necessary in some cases. PAUSE DEMO seconds tells The DEMO System to wait a specified number of seconds before processing each keystroke. The user can press a key before the number of seconds is up, in which case the next keystroke will be activated (or, if PAUSE BREAK ON is in effect and they press Escape, they'll clear the buffer). The default value for this is PAUSE DEMO 1. Other than PAUSE DEMO 0 (which operates too quickly to be seen on some systems), PAUSE DEMO 1 is as fast as you can go. Note that the contents of the buffer is not applied to PROMPT or PAUSE/PAUSEA action commands. The system will not take the buffered input to answer a prompt or get out of a wait condition. DEMOSYS.DOC Last revised 01/15/93 Page 31 Creating menuing systems: The DEMO System provides enough functionality to create your own menuing system, providing menu access to basic DOS commands as well as a program launcher for other application products. You can set up a series of screens which let the user select applications to run or execute various DOS functions for them. Several action commands provide DOS functionality and closely correspond to the standard DOS commands. These are listed below without explanation. See the reference manual if any of them don't make sense to you. CD directory CDD drive:directory COPY file1 file2 DELETE filename DRIVE letter MD directory RD directory RUN [ string ] Several action commands are a bit more obscure. These are listed below and described afterward: PROMPT ^Evar^ pattern string QUIT [ return_code ] RUNA [ string ] WRITE filename string The PROMPT command prompts the user for a response and sets an environmental variable to their response. It consists of several parts (which are described completely in the reference manual): * "^Evar^" is the environmental variable that stores the results of the user's input. * "pattern" defines the type of input that is expected. The "pattern" can be replaced by any of the following words: FILESPEC A DOS file specification VFILESPEC An existing DOS filename MM/DD/YY A valid date PATH A DOS file path VPATH An existing DOS file path or by any combination of the following characters: A alpha input (A-Z) (either upper or lower case) B Boolean input (T/F/Y/N; translated to Y/N on output) N numeric input (digits 0 to 9 only) U uppercase alpha (A-Z) only (translated to uppercase if provided in lowercase) X any character (decimal 32 to 125) (no translation) ! uppercase any character (decimal 32 to 125) (translated to uppercase if provided in lowercase) else any other characters in the pattern are left in the result verbatim; spaces are not allowed DEMOSYS.DOC Last revised 01/15/93 Page 32 * "prompt" is what the user sees before filling in their answer. The prompt and can include the normal control codes (^Cx, ^Prow,col, etc) that are allowed for most strings in The DEMO System. The QUIT command has already been used in a few examples to get out of the program. It also provides the ability to pass a return code to DOS. Quitting and looking for a return code is one way that a menu batch command can run another application without running out of memory. An easier method is to create a batch file in the menuing system and test for this batch file on exit. The easier method is demonstrated below. The RUNA command switches to the alternate screen before running a DOS command. You will see the command run but it probably won't permanently affect your menu display. Many applications will take charge of your screens anyway and they'll affect the menu. Note that using RUN or RUNA means The DEMO System remains in memory while your command is run. The DEMO System requires close to 100K of RAM. If your program needs more than about 500K, you will have to exit the system (using QUIT), run a batch file, and then return to The DEMO System. This is demonstrated below. The WRITE command writes a line to a text file. This is typically used for creating a batch file from scratch. It can also be used to create accounting records saying that a particular command was run at a particular date and time. DEMOSYS.DOC Last revised 01/15/93 Page 33 Program Example 8: This is going to be a fairly complicated example. For most real menuing systems, you need to set up a batch file that calls The DEMO System and then optionally calls another batch file which has commands to execute. This is done for any command that is too big to fit into memory. In this example, most of the options in the menu are directly available from The MENU System but one, running WordPerfect, is not. We presume for the sake of this example that you have a batch file called WP.BAT that invokes WordPerfect, changing the subdirectory and drive if necessary, and running it will all of the proper options. You could have many batch files if you wanted to. The DEMO System also allows you to create files (such as batch files) on the fly using the WRITE action command. You also have a batch file that you're running The DEMO System from. We'll call it EXAMMENU.BAT and it looks like this: ECHO OFF :Restart EXAM08 IF NOT EXIST EXAM08X.BAT GOTO :Done CALL EXAM08X.BAT GOTO :Restart :Done This batch file loads The DEMO System's program (EXAM08.EXE in this case). Once the program runs, the batch file checks to see if it has created a file called EXAM08X.BAT. If yes, that batch file is run and then The DEMO System is entered again. If not, then the user is returned to DOS. EXAM08.EXE is the file you're creating with The DEMO System this time. Its source control cards look like this: /* Creating a sample user menu - (ONCE) DELETE EXAM08X.BAT /* Killing off the temporary batch file - *000 Main menu KEY (UP) FIELD -1 KEY (DOWN) FIELD 1 KEY @1,A CALL @SHELLRUN WP.BAT KEY @2,B CALL @RUN CHKDSK KEY @3,C CALL @RUN DIR /W KEY @4,D CALL @RUN FORMAT A: KEY @5,E CALL @SHELL KEY @6,Q,(ESC) GOTO @QUIT /* EXAM08X.BAT is gone so batch program st SET CURSOR ^C1==> /. Sample menuing system: Pick an option: ^K A Run WordPerfect ^K B Run CHKDSK ^K C Do a directory ^K D Run FORMAT A: ^K E Drop into DOS DEMOSYS.DOC Last revised 01/15/93 Page 34 ^K Q Quit ./ - @RUN Running a command while staying in The MENU System CLS /* Unnecessary, but it looks better RUN ^E1^ ^E2^ ^E3^ ^E4^ ECHO Press a key to continue PAUSE POP - @SHELLRUN Running a batch command. /* Copying the file as EXAM08X.BAT which is tested for in the /* main batch file. COPY ^E1^ EXAM08X.BAT QUIT - @SHELL Leaving the user in DOS itself ECHO ^P20,1Enter EXIT and then (ENTER) to go back into The MENU System RUN POP - @QUIT Quitting ECHO ^P20,1Thanks for your interest! QUIT The entire menuing system consists of just five screens in this example, three of which are labels and one of which is a (ONCE) declaration. This leaves just one visual screen for the user to see. You could easily create a multiple-page menuing system which allowed the user to branch through a long series of commands and such. The very first screen is a (ONCE) statement that deletes the file EXAM08X.BAT. A (ONCE) statement contains statements that you only want run when The DEMO System first starts up. EXAM08X.BAT is the file that is tested for in the EXAMMENU.BAT file and whose non-existance means that there's nothing more for the program to do ("IF NOT EXIST EXAM08X.BAT GOTO :Done"). The only way that file is recreated is in label @SHELLRUN; any other way out of the program will result in the file not being there so the user will be left in DOS. The first KEY assignment gives control to this @SHELLRUN label. It passes the name of the batch file that should be copied over EXAM08X.BAT. (You could create the batch file on the fly with WRITE commands but it's easier to take an existing one if you can.) The passed parameter becomes environmental variable ^E1^ (subsequent ones would have become ^E2^ to ^E9^). The @SHELLRUN label expands ^E1^ into "WP.BAT" and then copies this file over EXAM08X.BAT. It then quits to DOS, at which point the EXAMMENU.BAT file kicks in, runs the program, and then puts you back into The MENU System. There are several RUN commands in the program but all of the programs they're running can be done within about 520K of memory so they do not cause problems. Try the command out (the EXAMMENU.BAT file is also in the SAMPLES.ZIP file) and see if it works the way you expect it to. DEMOSYS.DOC Last revised 01/15/93 Page 35 Using (GLOBAL): It's time to backtrack a bit. Six screen page statements were introduced back at the beginning of this tutorial: - filename [ description ] /* Screen text is external - *ref [ description ] /* Screen text is imbedded - @label [ description ] /* Action-only pages - (GLOBAL) [ description ] /* Establish defaults for later - (SETn) [ description ] /* Provide recallable settings - (ONCE) [ description ] /* Done once only So far, we've covered the first three of these without saying much about the remaining ones. The (GLOBAL) statement is used when you have a lot of similar screens and you want to avoid coding the same basic KEY statements or SET statements for each of them. For example, say you have a series of screens, all of which should have the same cursor shape and all of which should uniformly treat (RIGHT), (LEFT), (UP), and (DOWN). You could of course code the same KEY and SET statements in for each of these screens. Alternatively, you could establish a default for KEY and SET statements and all screens defined after that default is set will share those defaults. In our case, you could say: - (GLOBAL) Establishing certain defaults KEY (RIGHT) FIELD 1 KEY (LEFT) FIELD -1 KEY (UP) FIELD -3 KEY (DOWN) FIELD 3 KEY (ESC) POP SET CURSOR ^C2(^T8) - TEST01.SCR First screen - TEST02.SCR Second screen - TEST03.SCR Third screen Presuming that the files TEST01.SCR, TEST02.SCR, and TEST03.SCR all share the same types of field assignments, this would work fine. (GLOBAL) is presumed for any statements that appear in the control file before the first real screen is encountered. You only *need* to use the (GLOBAL) if you want to redefine the defaults part-way through a control file. Whenever (GLOBAL) is encountered, all previously-defined (GLOBAL) KEY assignments are cleared but SET statements are not. You cannot put regular action command (like RUN) in a (GLOBAL) section although they can be assigned to a keystroke in that section. Otherwise, you'd end up with an action command being performed at the start of every screen. DEMOSYS.DOC Last revised 01/15/93 Page 36 More labor-saving techniques: The (GLOBAL) statement (discussed above) is one way to save yourself from adding a lot of repeating lines to your control file. Other labor-saving tools exist and this section discusses them. These include (SETn) statements, Macros, and included text. (SETn) statements: There can only be one set of (GLOBAL) statements defined at a time. Frequently, you will want to have alternative defaults that you bring in. For example, let's say you have a presentation which has some screens with single input columns, some with double input columns, and some with only horizontal selections (e.g. "Pick a drive: A B C D E F G"). You could spend your time trying to make sure that all screens with similar characteristics follow each other in sequence but that might destroy the "natural order" of your control file. The first easy way to get around this is to use (SETn) statements. These are of the format: - (SETn) [ description ] /* Provide recallable settings You can define up to ten (SETn) definitions, where "n" is a digit from "0" to "9". In our example, we could define three (SETn) statements: - (SET0) Single-column input SET KEY (DOWN) FIELD 1 SET KEY (UP) FIELD -1 SET KEY (HOME) TOP /* Takes you to first field on screen SET KEY (END) BOTTOM /* Takes you to last field on screen SET KEY (ESC) POP - (SET1) Dual-column input SET KEY (RIGHT) FIELD 1 SET KEY (LEFT) FIELD -1 SET KEY (UP) FIELD -2 SET KEY (DOWN) FIELD 2 SET KEY (HOME) TOP SET KEY (END) BOTTOM SET KEY (ESC) POP - (SET2) Horizontal input SET KEY (LEFT) FIELD -1 SET KEY (RIGHT) FIELD 1 SET KEY (HOME) TOP SET KEY (END) BOTTOM SET KEY (ESC) POP DEMOSYS.DOC Last revised 01/15/93 Page 37 Then, in the screens that need these key definitions, you can refer to the appropriate (SETn) definition by using the SET KEYS statement: - TEST01.001 First file with single-column input SET KEYS SET0 - TEST01.002 Double-column input SET KEYS SET1 - TEST01.003 Another single-column input SET KEYS SET0 The (SETn) section can also include regular SET statements like SET CURSOR, SET COLOR, etc. These definitions will be brought in if you use the "SET SETTINGS SETn" statement in your program. Action commands are ignored within a (SETn) definition. When you use the SET KEYS or SET SETTINGS statements, the (SETn) definitions are added to whatever you already have in your current screen's configuration. The configuration is not cleared first. If the (SETn) definition includes a KEY assignment that you try to redefine later for this same screen in your control card file, the (SETn) definition will win. You must define the (SETn) section before you invoke it. You can re-use the (SETn) declaration if you want. The SET KEYS and SET SETTINGS statements count as action commands so they cannot be used in (GLOBAL) sections. Macros, on the other hand, can appear anywhere. DEMOSYS.DOC Last revised 01/15/93 Page 38 Macros: Macros are groups of code that are brought in whenever needed. Macros can include SET statements, KEY definitions, action commands, (GLOBAL) statements, etc. In fact, a Macro can include any statement except another block of macro statements. In most cases, you will only find Macros useful for setting up KEY definitions that you want to include in (GLOBAL) statements. You may also find Macros useful in labels when several labels include the same block of action commands. Macros begin with a MACRO declaration and include every control line from the statement after the MACRO declaration to a corresponding MEND statement: MACRO name [ REUSE | SKIP ] ... MEND There has to be one and only one MEND statement for every MACRO declaration. The Macro name is truncated at eight characters and has to be unique against all other Macro names up to those eight characters. If "REUSE" is specified and the macro name is already in use, the new definition will replace it. If "SKIP" is specified and the macro name is already in use, the new definition will be ignored. The Macro has to be defined before it is invoked. In order to invoke a Macro, you must use the following command: DO name [ parms ] The "name" corresponds with the Macro name (again, being truncated at eight characters). The optional parameters allow you to pass in up to 9 words. These words will replace special variables &1 to &9 if any of these variables are found within the macro or within any code encountered before the next DO statement. This means that the &1 to &9 variables can appear just about anywhere but they will only have a value once a DO statement passes them a value. If desired, you can issue a DO statement against a system-defined fake Macro named (DUMMY). Depending on whether you pass parameters in or not, you can either change the definition of &1 to &9 or clear them entirely. Just like the MACRO statement itself, the DO statement can appear anywhere in your control card file. DEMOSYS.DOC Last revised 01/15/93 Page 39 Program Example 9: In this example, we'll define a Macro and use it and the &1 to &9 variables a little bit. Create the following control cards and save them as EXAM09.CTL: MACRO @TESTING /* A sample macro ECHO &1 is coming to &2 ECHO Get your &3 ready! ECHO PAUSE 2 MEND - @001 Invoking the macro DO @TESTING Santa_Claus town stockings DO @TESTING Bill_Clinton Washington_DC special_interests DO @TESTING George_Bush Texas tax_exemptions ECHO The value of &^_1 is &1 DO (DUMMY) ECHO The value of &^_1 is now &1 LOCATE 20 1 QUIT The Macro is invoked three times within one screen, each time passing in three different parameters. Then one of the parameters is tested outside of the Macro. Then DO (DUMMY) is invoked with no parameters, clearing &1 to &9 and one of the variables is tested again. One trick that you'll notice here is the use of ^_. This control combination is ignored by the system but only after the other parameters have been resolved. As a result, "&1" will actually show up when the ECHO command is printed instead of "George_Bush" (a definite improvement too). As always, compile this text file ("DEMOMAKE EXAM09.CTL EXAM09.EXE") and then run the program ("EXAM09"). See if it works the way you'd expect. DEMOSYS.DOC Last revised 01/15/93 Page 40 Included text: Periodically, you will develop a subset of a demo file that you will want to use in several demos. For example, you might have a group of screens that talk about modem problems and you decide to include this in both a technical help program as well as in a demonstration of your BBS. While you could manually copy the lines to include into your file, it's easier to tell your main control file to include at some point the other text. This is done using the + control statement: + filename When The DEMO System encounters one of these statements, it will stop processing the current file and start processing the new file. When done with that file, it will return to the originating file. Included files can have any type of control cards in them (including Macros). They can also have included files, nesting being limited roughly by the number of remaining file handles your DOS environment has allowed for.