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 >
Text File  |  1993-01-15  |  81KB  |  1,771 lines

  1.  DEMOSYS.DOC                   Last revised 01/15/93                     Page 1
  2.  
  3.                                 The DEMO System
  4.  
  5.                                  Wayne Software
  6.                                113 Sheffield St.
  7.                             Silver Spring, MD 20910
  8.  
  9.                     General user documentation and tutorial
  10. --------------------------------------------------------------------------------
  11.  
  12.                                Table of Contents
  13.  
  14. Table of contents ...............................................  1
  15. What is The DEMO System? ........................................  2
  16. Shareware notice ................................................  3
  17. Legal stuff .....................................................  3
  18. Registration form for The DEMO System ...........................  4
  19. The DEMO System documentation ...................................  5
  20. Documentation syntax ............................................  5
  21. The DEMO System programs:
  22.   DEMOMAKE.EXE ..................................................  6
  23.   The DEMO System viewer ........................................  6
  24.   DEMOSAVE.EXE (registered users only) ..........................  6
  25. Input files required to create the self-viewer...................  7
  26. Commenting code .................................................  7
  27. Tutorial:
  28.   Screen pages ..................................................  8
  29.     Program Example 1 ...........................................  9
  30.   Settings (SET) statements ..................................... 11
  31.     List of SET commands ........................................ 11
  32.   The screen display ............................................ 12
  33.     Program Example 2 ........................................... 13
  34.     ^ codes ..................................................... 14
  35.     Program Example 3 ........................................... 14
  36.     Environmental variables ..................................... 15
  37.       List of pre-defined environmental variables ............... 15
  38.     Program Example 4 ........................................... 16
  39.   Action commands ............................................... 17
  40.     List of action commmands .................................... 17
  41.     Primary vs alternate screens ................................ 18
  42.   Key definitions ............................................... 19
  43.     Program Example 5 ........................................... 21
  44.   Full-screen activities ........................................ 23
  45.     Program Example 6 ........................................... 24
  46.     How input fields are determined and how to do multi-column
  47.       menus ..................................................... 26
  48.     Program Example 7 ........................................... 27
  49.   Keys defined by default ....................................... 29
  50.   Self-running demos ............................................ 30
  51.   Creating menuing systems ...................................... 31
  52.     Program Example 8 ........................................... 33
  53.   Using (GLOBAL) ................................................ 35
  54.   More labor-saving techniques .................................. 36
  55.     (SETn) statements ........................................... 36
  56.     Macros ...................................................... 38
  57.       Program Example 9 ......................................... 39
  58.     Included text ............................................... 40
  59.  DEMOSYS.DOC                   Last revised 01/15/93                     Page 2
  60.  
  61. --------------------------------------------------------------------------------
  62.  
  63.                             What is The DEMO System?
  64.  
  65. The DEMO System can can be used to create demonstration programs for text-only
  66. products.  It allows you to specify branching to different display screens.  It
  67. allows you to define unique actions based on almost any keyboard entry.  This is
  68. an ideal vehicle for demonstrating bulletin boards and CD-ROM products without
  69. requiring the user to have any hardware.
  70.  
  71. The DEMO System can be used to create menu systems.  You can pop up a menu with
  72. several dozen options, allowing the user to pick an option or view more options.
  73. The user can be prompted for information.
  74.  
  75. The DEMO System can be used to create help and tutorial systems.  You can
  76. arrange help information in a tree-like structure and have the user branch
  77. around as necessary.
  78.  
  79. The DEMO System creates an EXE version of your demonstration.  This EXE version
  80. has imbedded CRC checks that prevent unauthorized tampering.  The EXE version
  81. can be distributed without royalty payments.  The EXE's are relatively small and
  82. can be placed on bulletin boards and floppy diskettes.
  83.  
  84.  
  85.  DEMOSYS.DOC                   Last revised 01/15/93                     Page 3
  86.  
  87. --------------------------------------------------------------------------------
  88.  
  89.                                 Shareware notice
  90.  
  91. The DEMO System is a shareware product.  This is a "try it before you buy it"
  92. concept.  If you find The DEMO System useful, you should pay the registration
  93. fee (US $50.00) to Wayne Software.
  94.  
  95.                 Wayne Software
  96.                 113 Sheffield St.
  97.                 Silver Spring, MD 20910
  98.  
  99. Upon registration, you will receive:
  100.  
  101. * Fax support for problems.
  102.  
  103. * A program called DEMOSAVE.EXE which takes EXE files created by the The DEMO
  104. System and recreates the control card statements.  DEMOSAVE.EXE is not for
  105. re-distribution and is available only to registered users.
  106.  
  107. * A disk copy of the current release of DEMOMAKE.EXE.  You will also receive a
  108. current copy of all of Wayne Software's other freebie software products.
  109.  
  110. Please print the following form, fill out a copy of it, and send it back to
  111. Wayne Software with payment.
  112.  
  113.  
  114. --------------------------------------------------------------------------------
  115.  
  116.                                   Legal stuff
  117.  
  118. No part of this publication may be reproduced, transmitted, transcribed, stored
  119. in a retrieval system, or translated into any other language or computer
  120. language in whole or in part, in any form or by any means, whether it be
  121. electronic, mechanical, magnetic, optical, manual or otherwise, without prior
  122. written consent of Wayne Software.
  123.  
  124. Wayne Software disclaims all warranties as to this software, whether express or
  125. implied, including without limitation any implied warranties of merchantability,
  126. fitness for a particular purpose, functionality, data integrity or protection.
  127.  
  128.  DEMOSYS.DOC                   Last revised 01/15/93                     Page 4
  129.  
  130. --------------------------------------------------------------------------------
  131.  
  132.                      Registration form for The DEMO System
  133.  
  134. Your name:      _____________________________________________________________
  135.  
  136. Your company (optional): ____________________________________________________
  137.  
  138. Mailing address: ____________________________________________________________
  139.  
  140.                  ____________________________________________________________
  141.  
  142. City, State, ZIP: ___________________________________________________________
  143.  
  144.                                        Country if not USA:  _________________
  145.  
  146. Voice phone number: _________________________________________________________
  147.  
  148. Fax phone number:   _________________________________________________________
  149.  
  150. Disk size (check one):   360K 5.25" ____        1.2MB 5.25" ____
  151.                          720K 3.5"  ____        1.44MB 3.5" ____
  152.  
  153. Please register me as a paid user of The DEMO System.  A check or money order
  154. for $50.00 (US) is enclosed.  (Sorry.  No credit card orders at this time.)
  155.  
  156. Registration entitles you to:
  157.  
  158. * Fax support for problems.
  159.  
  160. * A program called DEMOSAVE.EXE which takes EXE files created by the The DEMO
  161. System and recreates the control card statements.  DEMOSAVE.EXE is not for
  162. re-distribution and is available only to registered users.
  163.  
  164. * A disk copy of the current release of DEMOMAKE.EXE.  You will also receive a
  165. current copy of all of Wayne Software's other freebie software products.
  166.  
  167. Mail to:        Wayne Software
  168.                 113 Sheffield St.
  169.                 Silver Spring, MD 20910
  170.  
  171.  
  172. Additional comments?
  173.  
  174.  DEMOSYS.DOC                   Last revised 01/15/93                     Page 5
  175.  
  176. --------------------------------------------------------------------------------
  177.  
  178.                          The DEMO System documentation
  179.  
  180. The DEMO System documentation consists of two manuals:
  181.  
  182.   DEMOSYS.DOC:  This manual explains the basics of how to create and compile
  183.     the files used by The DEMO System.  It includes a tutorial with examples.
  184.  
  185.   DEMOSYS.REF:  This manual is a reference manual that explains each of
  186.     the commands and how they are used.  It also describes the syntax used
  187.     by the DEMOMAKE.EXE program as well as by the viewer.
  188.  
  189. While programming techies are inclined to skip tutorials, you should at least
  190. look through the sample control files (which are stored in the SAMPLES.ZIP file
  191. in the distribution file).  Unlike other programs, the DEMOMAKE.EXE program
  192. itself is not interactive.  You are expected to understand the program somewhat
  193. before you attempt to use it.
  194.  
  195.  
  196. --------------------------------------------------------------------------------
  197.  
  198.                               Documentation Syntax
  199.  
  200. Throughout this documentation, required items are capitalized.  Variables appear
  201. in lowercase letters.  So "MD directory" indicates that you must type exactly
  202. the letters "M" and "D" (in either lowercase or uppercase form) whereas
  203. "directory" is to be filled in with some other word.
  204.  
  205. Options are specified in square brackets.  They can be left out if desired.
  206. "RUN [ string ]" indicates that you can use the RUN command on its own (which
  207. will leave you at the DOS prompt) or you can include a command to be executed
  208. (at which point you'll be returned to the demonstrator).
  209.  
  210. When several options are available for a given command and, if any are used, you
  211. can only pick one, the options appear within one set of brackets and a vertical
  212. bar separates each.  So "CALL screen [ KEYn | parms ]" says you can either use
  213. "CALL screen", "CALL screen KEYn", or "CALL screen parms".
  214.  
  215.  
  216.  DEMOSYS.DOC                   Last revised 01/15/93                     Page 6
  217.  
  218. --------------------------------------------------------------------------------
  219.  
  220.                             The DEMO System programs
  221.  
  222. The DEMO System consists of three distinct programs:
  223.  
  224. - DEMOMAKE.EXE:  This program takes a control card file and (typically)
  225. stand-alone screen files, verifies and compiles the code, and generates a load
  226. file.  DEMOMAKE.EXE then appends The DEMO System viewer to this file to make a
  227. single demonstration file.  DEMOMAKE.EXE need not be distributed with your
  228. demonstration program; it is needed for creating demonstration programs, not for
  229. viewing them.
  230.  
  231. - The DEMO System viewer:  This program presents your demonstration presentation
  232. to the end user.  The viewer is a self-contained program which will be called
  233. anything you want it to be.  The DEMOMAKE.EXE program creates this viewer file
  234. for you.
  235.  
  236. - DEMOSAVE.EXE:  This program is distributed only to registered users and can
  237. *not* be distributed with your demonstration program.  DEMOSAVE.EXE allows you
  238. to uncompile the demonstration file, allowing you to make changes even if you're
  239. missing some of the original input screens.  It also provides you a complete
  240. list of all keys that are valid during any given screen, resolving all GLOBAL
  241. statements for you.
  242.  
  243.  
  244.  DEMOSYS.DOC                   Last revised 01/15/93                     Page 7
  245.  
  246. --------------------------------------------------------------------------------
  247.  
  248.                  Input files required to create the self-viewer
  249.  
  250. At a mininum, The DEMO System requires an input file which contains control card
  251. statements.  Typically, it also requires screen files.  At least initially, the
  252. screen files are stored as separate files external to the control card file.
  253.  
  254. All input files are ASCII text files.  They should not contain any tab, page
  255. eject, or other non-printable characters.
  256.  
  257.  
  258. --------------------------------------------------------------------------------
  259.  
  260.                                 Commenting code
  261.  
  262. (I put this in its own little section because in most application language
  263. manuals, it's almost impossible to find out how to enter comments.)
  264.  
  265. Comments can be imbedded within control cards in several ways:
  266.  
  267. - You can include blank lines between control cards.
  268.  
  269. - You can begin a line with either ":", ";", or "'".
  270.  
  271. - You can designate a comment within a command line by beginning it with "/*".
  272.  
  273. All comments are ignored by the DEMOMAKE program and do not end up in the
  274. compiled code that is actually processed by The DEMO System viewer.
  275.  
  276. The use of comments is heavy recommended.
  277.  
  278.  DEMOSYS.DOC                   Last revised 01/15/93                     Page 8
  279.  
  280. --------------------------------------------------------------------------------
  281.  
  282.                                     Tutorial
  283.  
  284.  
  285. Screen pages:
  286.  
  287. There are a great many types of commands available in the demonstration program.
  288. There are at least 35 unique commands, 12 settings, and several special
  289. operations.
  290.  
  291. Despite the variety, the standard "unit" of the demonstrator is a screen page.
  292. Each screen page can have unique key-press logic assigned to it (pressing "G"
  293. may take you to another screen on one screen page, or it may take you out of the
  294. demonstrator entirely).  Each screen page can also have other unique settings:
  295. the shape of the cursor can change, the constant logo (if any) can change, the
  296. colors can change.  All standard screen pages have text screens attached to
  297. them; text which is displayed (such as a menu) presenting the user with
  298. information so they can select the desired options or else text displayed for
  299. informational purposes (as in a help screen).
  300.  
  301. There are several special screen pages.  These pages do not have any text
  302. screens attached to them.  The special pages are:  labels (subroutines which are
  303. executed at a key press), global definitions (key and other settings which apply
  304. to all screens defined after the global definition), set definitions (key and
  305. other settings which can be defined once and then invoked later in different
  306. screens on an as-desired basis), and "once" definitions (operations which are
  307. done once when the program loads and then are not done again; these might
  308. including loading unique fonts so you can have you logo appear as graphics
  309. characters).
  310.  
  311. Screen pages are identified within your control file as statements that begin
  312. with a dash.  All of the screen page statements have same basic format:
  313.  
  314.         - filename [ description ]            /* Screen text is external
  315.         - *ref [ description ]                /* Screen text is imbedded
  316.         - @label [ description ]              /* Action-only pages
  317.         - (GLOBAL) [ description ]            /* Establish defaults for later
  318.         - (SETn) [ description ]              /* Provide recallable settings
  319.         - (ONCE) [ description ]              /* Done once only
  320.  
  321. The "description" field is totally optional.  It can be recalled by your
  322. program later if necessary using the environmental variable ^EFDESC^.  Unlike
  323. comments, descriptions stay with the data and are retrieved if DEMOSAVE is run
  324. on the file.
  325.  
  326.  DEMOSYS.DOC                   Last revised 01/15/93                     Page 9
  327.  
  328. Each regular screen page can consist of four classes of commands.  Each of these
  329. classes of commands are optional for any given screen.  Most screens will only
  330. have three of the four classes of commands and some types of screens cannot have
  331. one or more of the types.  Each class is processed in the following order:
  332.  
  333.   (1) settings (cursor shapes, colors, etc; these are processed immediately when
  334.       the screen is loaded)
  335.  
  336.   (2) the screen display (NOT allowed within labels, Global, Set, and Once-only
  337.       screen pages)
  338.  
  339.   (3) action commands (these commands are processed sequentially after the
  340.       screen is displayed; typically, action commands are only used within
  341.       label screen pages; their use within Global screen pages is strongly
  342.       discouraged and they are ignored within Set screen pages)
  343.  
  344.   (4) key definitions (what commands to do when a given key is pressed; these
  345.       are processed only if the user presses the desired key; typically, key
  346.       definitions do not appear within label pages)
  347.  
  348. Although the classes are in fact processed in the above order, they can
  349. typically appear within the control card file in any order.
  350.  
  351. A screen page is defined as ending when the first of any of the following
  352. conditions are met:
  353.  
  354. - The end of the main control file is reached
  355. - Another screen page control statement is reached.
  356. - A QUIT, GOTO, SCREEN, KEYPRESS, or POP action command is encountered.
  357.  
  358.  
  359. Program Example 1:
  360.  
  361. Let's start with a very simple control file.  You want the program to pop up,
  362. say "Hello world", and then return to DOS.  (For some reason, this is the
  363. standard "first program" example in most programming language books.)  This
  364. example doesn't require a text screen at all (we'll add one later); you just
  365. need the following control card file:
  366.  
  367.         - @HI! A label screen page without much to it
  368.         ECHO Hello world
  369.         QUIT
  370.  
  371. The first statement designates that this is a label screen page.  The "A label
  372. screen page without much to it" is the description for the page.  The
  373. description, again, was totally optional and you could have put anything you
  374. wanted to here.
  375.  
  376. DEMOSYS.DOC                   Last revised 01/15/93                     Page 10
  377.  
  378. The next two statements are action commands.  They execute sequentially, without
  379. regard to key presses.  Each statement is explained in the reference section
  380. below but the "ECHO" command displays a character string to the viewer's screen
  381. and "QUIT" gets you out of the program.  Every demonstration program should
  382. have at least one "QUIT" statement in at least one screen page.
  383.  
  384. Save these text lines as an ASCII file called EXAM01.CTL.  Then issue the
  385. following command:
  386.  
  387.         DEMOMAKE EXAM01.CTL EXAM01.EXE
  388.  
  389. When you run the EXAM01 file, you'll see some screen activity and get a final
  390. screen that looks something like this:
  391.  
  392.      DEMOMAKE  (c)Copyright 1993, Wayne Software          Last revised xx/xx/xx
  393.      23:24:56: Begin
  394.  
  395.      23:24:56: Begin Pass 1
  396.      Processing    3 line    3 screen    1 in EXAM01.CTL
  397.      Maximum number of keys per screen (including globals and actions): 6
  398.  
  399.      23:24:57: Begin Pass 2
  400.      Reading screen   1 @HI! A label screen page without much to it
  401.      Processed  Macros:   0   Variables:   1   Strings:   4   Screen lines:   0
  402.                 Keys (and actions):        6
  403.  
  404.      23:24:57: Creating EXAM01.EXE
  405.  
  406.      23:24:57: Done
  407.  
  408. Not a heck of a lot to it.  When you type the command EXAM01.EXE, you'll get
  409. something like the following:
  410.  
  411.      DEMO      (c)Copyright 1993, Wayne Software         Last revised xx/xx/xx
  412.      -Hello world
  413.  
  414. Well, not very exciting, was it?  You could have added a CLS command to get rid
  415. of the copyright stuff but it basically worked the way you expected it to.
  416.  
  417. Note that all programming examples are contained in the SAMPLES.ZIP file within
  418. the distribution file.
  419.  
  420. DEMOSYS.DOC                   Last revised 01/15/93                     Page 11
  421.  
  422. Settings (SET) statements:
  423.  
  424. Settings (SET) statements are defined once for each screen page.  If they are
  425. not defined by you, The DEMO System assigns certain default values for you.  The
  426. setting statements available to you are as follows:
  427.  
  428.         SET CASE OFF         /* The keypress "g" will be treated as "G"
  429.         SET CASE ON          /* "g" and "G" can each have their own actions
  430.         SET CLS ON           /* Clear the screen before this text page
  431.         SET CLS OFF          /* Do not clear the screen before this text page
  432.         SET COLOR settings   /* Define up to 8 color sets for color monitors
  433.         SET CURSOR string    /* Define a cursor to be used during full-screen
  434.         SET KEYS CLEAR       /* Clear all global key settings
  435.         SET KEYS SETn        /* Bring in key settings from setting "n"
  436.         SET LOGO string      /* Display a logo (text) somewhere on the screen
  437.         SET MONO settings    /* Define up to 8 color sets for monochrome users
  438.         SET SETTINGS SETn    /* Bring in SET settings from setting "n"
  439.         SET TOP screen       /* Define top level that program can POP to
  440.  
  441. Most of these options won't make sense at this point and, frankly, you'll never
  442. use some of them.  Commands which are needed in the examples will be explained
  443. briefly on an as-needed basis.  Each command is fully discussed in the reference
  444. section.
  445.  
  446. For reference, the default values (where applicable) for each of these are as
  447. follows:
  448.  
  449.         SET CASE OFF
  450.         SET CLS ON
  451.         SET COLOR 151 154 152 117 097 153 001 157
  452.         SET CURSOR _
  453.         SET MONO  150 070 007 157 150 070 007 157
  454.  
  455. DEMOSYS.DOC                   Last revised 01/15/93                     Page 12
  456.  
  457. The screen display:
  458.  
  459. For screen pages that allow a screen display, the screen itself is a block of
  460. text consisting of at most 25 lines, each usually no more than 80 characters in
  461. length.  Initially, you can create the screen pages with either a text editor or
  462. by using a text capture program (such as PC Magazine's PRN2FILE program).  For
  463. most presentations, you will end up using both techniques.
  464.  
  465. These text pages can be stored as either separate external files (each file
  466. containing just one screen's worth of information) or else they can be imbedded
  467. within the control card file.  The DEMOSAVE program (available only for
  468. registered users) recreates the control cards with all screens being imbedded.
  469.  
  470. The chief advantage of imbedded screen files is one of control; it's
  471. easier to maintain a single combined file than it is to have lots of little
  472. screen files.
  473.  
  474. The disadvantages are several; risks increase with only one file (lose the
  475. control file and you have to recreate everything from scratch or else use
  476. DEMOSAVE), larger files are typically harder to edit and maneuver around, and
  477. the DEMOMAKE.EXE program will actually have to process any imbedded text lines
  478. twice instead of once so compilation is slower.
  479.  
  480. If the screen files are external, the screen page control card follows this
  481. format:
  482.  
  483.         - filename [ description ]            /* Screen text is external
  484.  
  485. The "filename" can include drive and path information if desired.  Otherwise,
  486. the program will look for the file in your default directory unless you've
  487. provided a DATADIR command telling it to look for the files elsewhere.
  488.  
  489. For imbedded screen files, the control card looks like this:
  490.  
  491.         - *ref [ description ]                /* Screen text is imbedded
  492.  
  493. The "ref" is a unique and short (one word) clue for what the screen text does
  494. (you can always add a fuller "description").  The shorter the better as far as
  495. the program is concerned but each reference must be unique.
  496.  
  497. If the screen files are internal, the contents of the screen must be defined
  498. before the next screen control card statement is encountered.  The screen is
  499. defined in a block of text that begins with "/." by itself on one line, followed
  500. by the up-to-25 lines of text, followed by "./" on a line by itself.
  501.  
  502.  
  503. DEMOSYS.DOC                   Last revised 01/15/93                     Page 13
  504.  
  505. Program Example 2:
  506.  
  507. Let's do the "Hello World" example using an imbedded screen file instead of the
  508. ECHO command.  To do this, create the following control file as save it as
  509. EXAM02.CTL:
  510.  
  511.         - *DEMO An imbedded screen file
  512.         /.
  513.         Hello world
  514.         ./
  515.         QUIT
  516.  
  517. Remember the rules for what defines the end of a screen page.  Among other
  518. things, a screen page ends when it hits a QUIT (or POP, GOTO, SCREEN, or
  519. KEYPRESS) action command.  If you had placed the QUIT command before the
  520. imbedded text, the program would have misplaced the imbedded text and would have
  521. given you an error message.
  522.  
  523. Compile this text file ("DEMOMAKE EXAM02.CTL EXAM02.EXE") and then run it
  524. ("EXAM02").  The screen will clear, the words "Hello there!" will appear, and
  525. you'll be left at the DOS prompt.
  526.  
  527.  
  528. DEMOSYS.DOC                   Last revised 01/15/93                     Page 14
  529.  
  530. ^ codes:
  531.  
  532. The screens themselves can include codes which establish colors, input
  533. locations, and other things.  There are seven types of control codes that The
  534. DEMO System accepts in text strings (including logos and cursor indicators) but
  535. one of them (the "^Prow,col" indicator) should not be used within a screen.
  536. These codes are as follows:
  537.  
  538.         ^Cn             /* Set the color to color (or monochrome) set "n"
  539.         ^K              /* Establish this as a keyboard-input field
  540.         ^Evar^          /* Print an environmental variable here
  541.         ^Tn             /* Print "n" non-destructive spaces here
  542.         ^Sn             /* Print "n" destructive spaces here (used only
  543.                         /* to reduce the size of your input file; The DEMO
  544.                         /* System automatically uses space compression when it
  545.                         /* encounters five or more spaces together)
  546.         ^Pr,c           /* Locate the cursor at row "r" and column "c":
  547.                         /* this setting is not allowed within text screens
  548.                         /* themselves and should only be used in SET CURSOR,
  549.                         /* SET LOGO, ECHO, PROMPT, etc commands
  550.         ^_              /* Ignored.  Typically used only if you want to
  551.                         /* print out one of the other control key sequences
  552.  
  553. Any text that is not part of these control codes (including spaces) are treated
  554. as text and is printed as is.
  555.  
  556.  
  557. Program Example 3:
  558.  
  559. Okay, back to the "Hello world" example.  In this case, we're going to print a
  560. text screen which contains the words "Hello world", then print a "Goodbye world"
  561. string on top of that screen, and then quit.
  562.  
  563. Create the following control cards and save them as EXAM03.CTL:
  564.  
  565.         - *Overprinting Doing a screen, overprinting it, and then quitting
  566.         /.
  567.  
  568.         ^S20^C1Hello ^C0world
  569.         ./
  570.         ECHO ^P20,20^C2Goodbye ^C3world
  571.         QUIT
  572.  
  573. After compiling the program ("DEMOMAKE EXAM03.CTL EXAM03.EXE"), then running it
  574. ("EXAM03"), you'll see the screen clear, print a blank line, skip to column 20,
  575. print "Hello world" in two different colors, then skip 18 lines and print
  576. "Goodbye world" in two different colors underneath it.
  577.  
  578. While these examples work as expected, they don't sound like anything you'd like
  579. to demonstrate, do they?  We're getting there!
  580.  
  581.  
  582. DEMOSYS.DOC                   Last revised 01/15/93                     Page 15
  583.  
  584. Environmental variables:
  585.  
  586. Most text strings (including input pages) can contain both real and
  587. pseudo-environmental variables.  These can include any variable defined in your
  588. DOS environment (such as PROMPT or PATH).  The pseudo-variable can also include
  589. several variables within The DEMO System, passed variables, and user-defined
  590. variables.  They also include variables that are defined in PROMPT statements
  591. and some others.
  592.  
  593. All environmental variables appear as "^Evar^" (without the quotes).  The DOS
  594. prompt, for example, is represented as "^EPROMPT^".  If this character string
  595. appears as part of an output block (either a screen, or a logo, prompt, or ECHO
  596. result), the variable will be expanded into the proper string.
  597.  
  598. (Some times, this will present problems.  Avoid putting an environmental
  599. variable in a row that will not fit on the screen.  Results are uncertain in
  600. these cases.)
  601.  
  602. The variables predefined by The DEMO System include those listed below.  Some of
  603. them may not have an immediately useful value but future changes to The DEMO
  604. System will make them relevant.
  605.  
  606.         ^EDATE^         the current system date (in mm/dd/yy format)
  607.         ^ETIME^         the current system time (in hh:mm:ss format)
  608.         ^EETIME^        the elapsed time that the user has used this program
  609.                         (in hh:mm:ss format)
  610.  
  611.         ^EFNAME^        the name of the screen input file
  612.         ^EFDESC^        the description (if any) of the screen input file
  613.         ^EFPAGE^        the sequential number of the screen input file
  614.  
  615.         ^EDIR^          the current default directory for the default drive
  616.                         (no slash appears at the end of the name)
  617.         ^EINITDIR^      the initial default directory when the program was
  618.                         loaded (no slash appears at the end of the name)
  619.  
  620.         ^EDISPLAY^      the current display type (COLOR or MONO)
  621.         ^EDISPLAYN^     the current display type (1=COLOR, 2=MONO)
  622.         ^EFIELD^        the current field number
  623.         ^ECOL^          the current screen column number
  624.         ^EROW^          the current screen row number
  625.  
  626. In addition, when using CALL and GOTO statements, you can pass one of more
  627. variables.  These variables are assigned sequentially to the
  628. pseudo-environmental variables ^E1^ to ^E9^.
  629.  
  630. Note that you can change regular DOS environmental variables (like PROMPT) but
  631. they are redefined only until your program completes.  Once you go back to DOS,
  632. they're reset to whatever they started off to be.
  633.  
  634. You can usually concatenate environmental variables with other variables and
  635. character strings.  For example, the following usually works:
  636.  
  637.         KEY (PGDN) GOTO *006 KEY^EFIELD^
  638. DEMOSYS.DOC                   Last revised 01/15/93                     Page 16
  639.  
  640. Program Example 4:
  641.  
  642. In this example, we'll generate a output screen that shows you the current
  643. definition of all of the environmental variables.  Note that some of the
  644. variables won't really have applicable values unless they're used in specific
  645. cases.
  646.  
  647. Create the following control cards and save them as EXAM04.CTL:
  648.  
  649.         - @MAIN This is the main screen
  650.         CALL @FILE Apples are good for you!
  651.         QUIT
  652.         - @FILE This is the screen that displays everything
  653.         ECHO  DATE      = ^EDATE^
  654.         ECHO  TIME      = ^ETIME^
  655.         ECHO  ETIME     = ^EETIME^
  656.         ECHO
  657.         ECHO  FNAME     = ^EFNAME^
  658.         ECHO  FDESC     = ^EFDESC^
  659.         ECHO  FPAGE     = ^EFPAGE^
  660.         ECHO
  661.         ECHO  DIR       = ^EDIR^
  662.         ECHO  INITDIR   = ^EINITDIR^
  663.         ECHO
  664.         ECHO  FIELD     = ^EFIELD^
  665.         ECHO  COL       = ^ECOL^
  666.         ECHO  ROW       = ^EROW^
  667.         ECHO
  668.         ECHO  Passed parms: (1)=^E1^ (2)=^E2^ (3)=^E3^
  669.         ECHO  Passed parms: (4)=^E4^ (5)=^E5^ (6)=^E6^
  670.         ECHO  Passed parms: (7)=^E7^ (8)=^E8^ (9)=^E9^
  671.         POP
  672.  
  673. Other than the environmental variables, there is a new action command included
  674. in this example.  The CALL statement brings in another screen page.  The word
  675. after the "CALL" must correspond to a page defined in a screen page statement.
  676. In this case, the screen page is a label page with no text screen at all.  All
  677. information is displayed using ECHO commands.  At the bottom of the page is the
  678. command "POP" which returns control to the statement after the call.
  679.  
  680. CALL and GOTO are the primary way used to move from one display screen to
  681. another.
  682.  
  683. CALL (and the related GOTO) command allow you to pass in up to 9 words
  684. (separated by one or more spaces) which become environmental variables ^E1^ to
  685. ^E9^.  You could pass in file names, control ("^") text codes, or anything else
  686. you want.  In this example, "Apples are good for you!" is passed in.  "Apples"
  687. is assigned to ^E1^, "are" is assigned to ^E2^, etc.  Variables ^E6^ to ^E9^ are
  688. left as blank.
  689.  
  690. Compile this code ("DEMOMAKE EXAM04.CTL EXAM04.EXE") and then test it out
  691. ("EXAM04").  It will display some information on the screen and then quit.
  692.  
  693. DEMOSYS.DOC                   Last revised 01/15/93                     Page 17
  694.  
  695. Action commands:
  696.  
  697. We've already used four action commands:  CALL, ECHO, POP, and QUIT.  There are
  698. 35 or more action commands available within The DEMO System.  These are listed
  699. below.  Some of them will be used in later examples and all are explained in the
  700. reference section at the end.
  701.  
  702. Note that most action commands actually appear within label pages, not screen
  703. pages.  Most of these action commands can be used in KEY statements (discussed
  704. next) but some (like RUN) will typically require a REDRAW command after
  705. executing; since you cannot assign two functions to a single keystroke, you will
  706. want to move these to label pages anyway.
  707.  
  708. Action commands are ignored within SET pages and are not recommended within
  709. Global pages.  Also note that most of the parameters can be replaced by
  710. environmental variables where desired.
  711.  
  712.         ASSIGN ^Evar^ [ string ]        /* Assign a value to an environmental
  713.                                         /* variable
  714.         BEEP                            /* Beep
  715.         BUFFER [ keys ]                 /* Put input characters into a buffer
  716.                                         /* so self-running demoes can be done
  717.         CALL screen [ KEYn | parms ]    /* Call a label or screen, with the
  718.                                         /* intention of returning to the
  719.                                         /* current location
  720.         CD directory                    /* Change to a given subdirectory
  721.         CDD drive:directory             /* Change to a given drive and subdir
  722.         CLS                             /* Clear the screen
  723.         COPY file1 file2                /* Copy file1 as file2
  724.         DELETE filename                 /* Delete a specified file
  725.         DISPLAY COLOR                   /* Use SET COLOR color settings
  726.         DISPLAY MONO                    /* Use SET MONO color settings
  727.         DISPLAY TOGGLE                  /* Toggles between COLOR and MONO
  728.         DRIVE letter                    /* Set the default drive
  729.         ECHO [ string[@] ]              /* Display a given string
  730.         ECHOA [ string[@] ]             /* Display a given string to the
  731.                                         /* alternate screen
  732.         FIELD change                    /* Move to a particular input field
  733.         GOTO screen [ KEYn | CLEAR | parms ]
  734.                                         /* Branch to a label or screen,
  735.                                         /* intending to not return to the
  736.                                         /* current screen
  737.         KEYPRESS                        /* Wait for a keypress (automatically
  738.                                         /* done in any screen text screen)
  739.         LOCATE row col                  /* Move to a given row and column on
  740.                                         /* the screen, can also be done with
  741.                                         /* ^Pr,c in display string itself
  742.         MD directory                    /* Make a subdirectory
  743.         NONE                            /* Don't to anything; only used in
  744.                                         /* key assignments
  745. DEMOSYS.DOC                   Last revised 01/15/93                     Page 18
  746.  
  747.         PAUSE [ seconds ]               /* Wait for seconds to pass or until
  748.                                         /* key is pressed
  749.         PAUSEA [ seconds ]              /* Wait on the alternate screen
  750.         PAUSE BREAK ON                  /* Allow people to escape out of
  751.                                         /* buffered sequences
  752.         PAUSE BREAK OFF                 /* Don't allow people to escape
  753.         PAUSE DEMO seconds              /* Wait specified number of seconds
  754.                                         /* before processing next key in the
  755.                                         /* buffer
  756.         PLAY string                     /* Play a given musical string
  757.         PLAY ON                         /* Activate all PLAY commands
  758.         PLAY OFF                        /* Turn off all PLAY commands
  759.         POP [ TOP | 1 to 20 ] [ KEYn ]  /* Return to some CALL statement
  760.         PROMPT ^Evar^ pattern string    /* Prompt user for some input
  761.         QUIT [ return_code ]            /* Return to DOS
  762.         RD directory                    /* Remove a subdirectory
  763.         REDRAW                          /* Redraw the current screen
  764.         RUN [ string ]                  /* Run a DOS command
  765.         RUNA [ string ]                 /* Run a DOS command to the
  766.                                         /* alternative screen
  767.         SAVE filename                   /* Save the current screen
  768.         SCREEN change                   /* Switch to another screen
  769.         WRITE filename string           /* Write a line to a text file
  770.  
  771. Action commands are executed sequentially after the screen text (if any) is
  772. displayed and before any user keypresses are processed (unless KEYPRESS
  773. appears).  While several of the normal computer programming branching
  774. constructs, like GOTO and CALL statements, are implemented in The DEMO System,
  775. you will typically find they are implemented unusually in The DEMO System and
  776. you will need to develop work-arounds for some of them.
  777.  
  778.  
  779. Primary vs alternative screens:
  780.  
  781. There are actually two screens that The DEMO System uses.  The first screen, the
  782. "primary screen", is used automatically for all text screens and by most of the
  783. commands.  The second screen, called the "alternate screen", is typically used
  784. when you want to run a DOS command and not have the output from this command
  785. affect the text screen the user is viewing.  Sometimes, you will want the output
  786. of the command to disappear completely.
  787.  
  788. There are are number of commands that provide the capability of writing to
  789. either of these two screens:  ECHO and ECHOA, PAUSE and PAUSEA, PROMPT and
  790. PROMPTA, and RUN and RUNA.  In most cases, stick to the command without the
  791. suffix.
  792.  
  793.  
  794. DEMOSYS.DOC                   Last revised 01/15/93                     Page 19
  795.  
  796. Key definitions:
  797.  
  798. Okay.  Time for the meat and potatos command within The DEMO System.  Key
  799. definitions tell the program what it should do if the user presses a given
  800. character.
  801.  
  802. Each key definition statement follows this basic format:
  803.  
  804.         KEY key[,key]... action_command [ options ]
  805.  
  806. where, at least for some of the action commands, the options are, in fact, not
  807. optional.
  808.  
  809. The "key" portion of the statement can be any regular character, like "R"
  810. (without the quotes).  If you want to assign an action to them, there are four
  811. characters that have to be coded specially:
  812.  
  813.         =       code as (EQUAL)
  814.         space   code as (SPACE)
  815.         (       code as (LPAREN)
  816.         ,       code as (COMMA)
  817.  
  818. You can also define just about any other character on the keybard to do
  819. something.  All of these keys are coded as a word in parentheses.  These include
  820. all of the following keys which should be self-evident:
  821.  
  822.         (DEL)   (ENTER) (INS)   (PGUP)  (UP)
  823.         (DOWN)  (ESC)   (LEFT)  (RIGHT) (F1) to (F12)
  824.         (END)   (HOME)  (PGDN)  (TAB)
  825.  
  826. as well as some keys that may not be readily apparent or be standard:
  827.  
  828.         (BS)            backspace key
  829.         (A-key)         Any letter key or F1 to F12 with Alt key pressed
  830.         (A-n)           Any key sequence generated by pressing the Alt
  831.                         key down, and, while keeping it down, pressing
  832.                         one to three digits on the numeric keypad
  833.         (C-key)         Any letter key, ENTER, BS, or F1 to F12 with Ctrl key
  834.                         pressed
  835.         (S-key)         TAB, DEL, INS, END, DOWN, PGDN, F1 to F12, etc with
  836.                         shift key pressed
  837.  
  838. Note that all one-letter control keys are in fact defined as something else too.
  839. (C-M) internally is the same key as (ENTER), (C-I) is the same as (TAB), etc.
  840. You should watch out for this when you define your key sequences; only the first
  841. key assignment will win.
  842.  
  843. You should also watch for this when you use the (A-n) convention.  Most keys in
  844. the (A-32) to (A-126) range can be entered directly.  Most of the keys before
  845. (A-32) are in fact keys like (ENTER) and (BS).  If you have one key assigned
  846. with something like (A-62) and another key defined as ">" (decimal value 62),
  847. the first key defined will always win.
  848.  
  849. DEMOSYS.DOC                   Last revised 01/15/93                     Page 20
  850.  
  851. You can assign multiple keys to the same action if desired, either on separate
  852. KEY statements or else by separating each key with a comma *only* (don't put any
  853. spaces around the comma).
  854.  
  855. Three mouse-related "keys":
  856.  
  857.         (MOUSER)        right mouse button pressed
  858.         (MOUSEL)        left mouse button pressed
  859.         (MOUSEB)        both left and right mouse buttons pressed
  860.  
  861. Full-screen field related keys:
  862.  
  863.         @1 to @90       field-selections 1 to 90
  864.  
  865. And two very special "keys":
  866.  
  867.         (ELSE)          any non-defined key was pressed
  868.         (ANY)           any key was pressed
  869.         (LASTKEY)       the last user key pressed; only allowed in BUFFER cmd
  870.  
  871. The "action_command" and "[ options ]" part of the KEY statement is the same as
  872. were mentioned above.
  873.  
  874. Typically, you will have key presses either call another screen or go to another
  875. screen.  The difference between a CALL and a GOTO is whether you want to be able
  876. to return easily to where you were when you issued the command.  You might use a
  877. CALL statement from a main menu, which offers the user several choices and then
  878. ultimately returns the user to the menu.  You might use a GOTO statement when
  879. you have several pages of information to present to a user and you want PgDn to
  880. simply goto the next screen of information.
  881.  
  882.  
  883. DEMOSYS.DOC                   Last revised 01/15/93                     Page 21
  884.  
  885. Program Example 5:
  886.  
  887. It's time for a more useful example.  In this case, you're going to have a menu
  888. with two branching options as well as a "quit" option.  The program will contain
  889. three screens: a main menu and the two subsequent screens (one of which is a
  890. label screen).  We won't use any full-screen options at this point.
  891.  
  892. Create your control card file EXAM05.CTL:
  893.  
  894.         - *001 Main menu
  895.         KEY A,(MOUSEL) CALL *002
  896.         KEY B,(MOUSER) CALL @003
  897.         KEY Q,(MOUSEB) QUIT
  898.         /.
  899.         Select an option:
  900.  
  901.            A. Display the current date and time          (left mouse button)
  902.            B. Do a directory of the default subdirectory (right mouse button)
  903.  
  904.            Q. Quit                                       (both buttons)
  905.         ./
  906.         - *002 Display the current date and time
  907.         KEY (ANY) POP
  908.         /.
  909.         Current date:    ^EDATE^
  910.         Current time:    ^ETIME^
  911.         Elapsed time:    ^EETIME^
  912.  
  913.         Press any key to return to the main menu
  914.         ./
  915.         - @003 Do a directory
  916.         RUN DIR /W
  917.         ECHO Press a key to return to the main menu
  918.         PAUSE
  919.         POP
  920.  
  921. DEMOSYS.DOC                   Last revised 01/15/93                     Page 22
  922.  
  923. This example has three KEY statements appearing in the first screen alone:
  924.  
  925.         KEY A,(MOUSEL) CALL *002
  926.         KEY B,(MOUSER) CALL @003
  927.         KEY Q,(MOUSEB) QUIT
  928.  
  929. When an "A" character or the left mouse button is pressed, the first KEY
  930. statement calls screen "*002", which has some imbedded text.  When a "B"
  931. character or the right mouse button is pressed, the second KEY statement calls
  932. the label "@003", which has some RUN and ECHO commands in it.  "SET CASE OFF" is
  933. the default setting so "a" and "A" are treated the same as are "b" and "B".
  934.  
  935. The third statement quits the program when a "Q" (or "q") or both mouse buttons
  936. are pressed.
  937.  
  938. Screen *002 contains another KEY statement:  "KEY (ANY) POP".  This says that if
  939. the user presses any key (including either mouse key), the program will return
  940. to the previous CALL statement.  In this case, it will return to *001, from
  941. which the CALL statement was made.
  942.  
  943. Several new action commands are used here.  The "RUN DIR /W" command shells out
  944. to the DOS command processor, and runs a directory command with the "/W" (wide)
  945. option.  "PAUSE" waits for the user to enter any keystroke and then goes on.
  946.  
  947. The ^Evar^ items (like ^ETIME^) in *002 are environmental variables which were
  948. discussed above.
  949.  
  950. Compile this code ("DEMOMAKE EXAM05.CTL EXAM05.EXE") and then test it out
  951. ("EXAM05").  The screen will clear, you'll get a small menu, you can pick any of
  952. the options by using the first character.  When you're done, press Q and you'll
  953. be returned to DOS.
  954.  
  955. This is a typical example for a demo set up for a bulletin board.  In BBS's, you
  956. typically select an item by pressing a mnemonic key.  There is usually no
  957. ability to do any selections using cursor keys.
  958.  
  959. Non-BBS applications, on the other hand, allow users to select options based on
  960. moving the cursor and pressing Enter.  For this, you need to know some
  961. full-screen functions.
  962.  
  963.  
  964. DEMOSYS.DOC                   Last revised 01/15/93                     Page 23
  965.  
  966. Full-screen activities:
  967.  
  968. Full-screen systems typically allow the user to move around the menu using the
  969. cursor keys.  For example, a list of 10 items might be presented vertically on
  970. the screen and you're able to use the up and down cursor keys to position the
  971. cursor to the item you want.  Then you press Enter.
  972.  
  973. The DEMO System allows this as well.  There are a number of things that have to
  974. be decided:
  975.  
  976. * What user-selectable fields are there?  What format will they have on the
  977. screen?  Are they arranged in columns or vertically?  Or are they some
  978. combination of both?
  979.  
  980. * What keys can be used to maneuver around the screen and what do they do?  A
  981. vertical list might support just the up and down arrow keys.  But typically, you
  982. will also want to support the Home and End keys to move to the first and last
  983. item on the list.  If you have a menu with vertical lists in several columns,
  984. you may want to add support for the right and left arrow keys.
  985.  
  986. * What should the cursor look like?  Should it be something like a greater-than
  987. symbol (">").  Or should it be a different-colored text block?  Or should it be
  988. parentheses around the current item, perhaps also in a different-colored text
  989. block?
  990.  
  991. * Where do you want the cursor to start in each field?  One space before the
  992. item?  Two spaces?  Three?  Maybe the cursor is "==>"; four would be appropriate
  993. for that.  Maybe the cursor appears *after* the item?
  994.  
  995. In The DEMO System, all input screens are in fact text screens.  If you want to
  996. designate fields within the screen, you use the "^K" character combination where
  997. you want the field location to begin.  You can designate up to 90 input areas
  998. per screen.
  999.  
  1000. For single-column presentations, you can skip lines all you want.  For
  1001. multi-column presentations, there are some other things to consider.  We'll
  1002. cover the simpler single-column presentation first.
  1003.  
  1004.  
  1005. DEMOSYS.DOC                   Last revised 01/15/93                     Page 24
  1006.  
  1007. Program Example 6:
  1008.  
  1009. In this example, we're going to do a short menu based on the screens in example
  1010. 5.  This menu will allow the user to use the arrow keys to get around.  The
  1011. input selections are arranged in a single column (you can guess what example 7
  1012. will cover!).
  1013.  
  1014. Create your control card file EXAM06.CTL:
  1015.  
  1016.         - *001 Main menu
  1017.         SET CURSOR ^C2=>
  1018.         KEY (UP) FIELD -1
  1019.         KEY (DOWN) FIELD 1
  1020.         KEY A,@1 CALL *002
  1021.         KEY B,@2 CALL @003
  1022.         KEY Q,@3 QUIT
  1023.         /.
  1024.         Select an option:
  1025.  
  1026.               ^K   A. Display the current date and time
  1027.               ^K   B. Do a directory of the default subdirectory
  1028.  
  1029.               ^K   Q. Quit
  1030.         ./
  1031.         - *002 Display the current date and time
  1032.         KEY (ANY) POP
  1033.         /.
  1034.         Current date:    ^EDATE^
  1035.         Current time:    ^ETIME^
  1036.         Elapsed time:    ^EETIME^
  1037.  
  1038.         Press any key to return to the main menu
  1039.         ./
  1040.         - @003 Do a directory
  1041.         RUN DIR /W
  1042.         ECHO Press a key to return to the main menu
  1043.         PAUSE
  1044.         POP
  1045.  
  1046. The *002 and @003 screens are identical to what they were originally.  What's
  1047. been added are the full-screen commands in the first screen.
  1048.  
  1049. Checking the changes line by line, the first new statement is:
  1050.  
  1051.         SET CURSOR ^C2=>
  1052.  
  1053. This establishes a cursor as "=>" which will be printed using color set 2
  1054. (which defaults to white on green).  The next lines establish what happens when
  1055. the up and down arrow keys are used:
  1056.  
  1057.         KEY (UP) FIELD -1
  1058.         KEY (DOWN) FIELD 1
  1059.  
  1060. DEMOSYS.DOC                   Last revised 01/15/93                     Page 25
  1061.  
  1062. If (UP) is pressed, the cursor will move from the current field to the previous
  1063. field.  If it's at the top item, it will be moved to the bottom item.  If (DOWN)
  1064. is pressed, the cursor will move from the current field to the next field.  If
  1065. it's at the bottom item, it will be moved to the top item.
  1066.  
  1067. These two keys don't actually select any of the items on the list.  They simply
  1068. determined where the cursor would be placed.  If Enter is pressed, the key
  1069. statement designated with that input field's number will take affect:
  1070.  
  1071.         KEY A,@1 CALL *002
  1072.         KEY B,@2 CALL @003
  1073.         KEY Q,@3 QUIT
  1074.  
  1075. If the cursor is at the first field when Enter is pressed, page *002 will be
  1076. executed.  If it's at the second field, then label page @003 will be executed.
  1077. If it's at the third field, the user will drop to DOS.
  1078.  
  1079. The actual designation of what fields are defined in done in the screen portion:
  1080.  
  1081.         /.
  1082.         Select an option:
  1083.  
  1084.               ^K   A. Display the current date and time
  1085.               ^K   B. Do a directory of the default subdirectory
  1086.  
  1087.               ^K   Q. Quit
  1088.         ./
  1089.  
  1090. The "^K" combination is used three times so there are three user-selectable
  1091. fields.  Note that there are three spaces between the "^K" and the item letter.
  1092. This means that there will be one space between the cursor (which is two
  1093. characters long) and the item letter.
  1094.  
  1095. Note that the cursor will skip all lines that don't contain a ^K designator.
  1096.  
  1097. Compile this code ("DEMOMAKE EXAM06.CTL EXAM06.EXE") and then test it out
  1098. ("EXAM06").  The screen will clear, you'll get a small menu, and you can pick
  1099. any of the options by using either the first character or by using the cursor
  1100. keys and then pressing Enter.  When you're done, press Q or move the cursor to
  1101. the Q option and press Enter.  You'll then be returned to DOS.
  1102.  
  1103.  
  1104. DEMOSYS.DOC                   Last revised 01/15/93                     Page 26
  1105.  
  1106. How input fields are determined and how to do multi-column menus:
  1107.  
  1108. The DEMO System detects input fields in the order they are found in the screen
  1109. file.  The fields are numbered from the first column to the last column, first
  1110. line to last line.
  1111.  
  1112. The "KEY (DOWN) FIELD 1" statement tells The DEMO System to move the cursor from
  1113. the current field location to the next field location.  If that field location
  1114. is on the next line, the cursor will physically move down.  If, on the other
  1115. hand, that field is on the current line, the cursor will instead move physically
  1116. right instead of down.
  1117.  
  1118. The DEMO System does not try to make the (DOWN) key move to the next line.  As
  1119. far as The DEMO System is concerned, the key sequence for (DOWN) is defined as
  1120. an action command; that action command, not the key itself, are processed during
  1121. a demonstration.
  1122.  
  1123. If you have a multicolumn input screen, you will have to select your key
  1124. locations more carefully.  Typically, you will want to insure that all columns
  1125. have the same number of input fields.  You will want to do this even if there
  1126. are cells that are missing in a given column.  (The reason for this will make
  1127. sense in the example that follows.)
  1128.  
  1129. Keep in mind that any keys that aren't defined for The DEMO System are in fact
  1130. ignored.  If someone positions the cursor at a field for which you don't have
  1131. any KEY statements and presses Enter, nothing happens.
  1132.  
  1133. Let's design a screen with multi-column user inputs.
  1134.  
  1135.  
  1136. DEMOSYS.DOC                   Last revised 01/15/93                     Page 27
  1137.  
  1138. Program Example 7:
  1139.  
  1140. In this example, we're going to do a multi-column menu.  The menu selections
  1141. don't actually do much (we need to keep the example short).  This menu will
  1142. allow the user to use the arrow keys to get around.
  1143.  
  1144. Create your control card file EXAM07.CTL:
  1145.  
  1146.         - *SCR Basic input screen
  1147.         SET CURSOR ^C2(^T8)
  1148.         KEY (RIGHT) FIELD 1
  1149.         KEY (LEFT) FIELD -1
  1150.         KEY (UP) FIELD -3
  1151.         KEY (DOWN) FIELD 3
  1152.         KEY (HOME) FIELD TOP
  1153.         KEY (END) FIELD BOTTOM
  1154.         KEY @1 CALL @DISPLAY Field 1
  1155.         KEY @2 CALL @DISPLAY Field 2
  1156.         KEY @3 CALL @DISPLAY Field 3
  1157.         KEY @4 CALL @DISPLAY Field 4
  1158.         KEY @5 CALL @DISPLAY Field 5
  1159.         KEY @6 CALL @DISPLAY Field 6
  1160.         KEY @7 CALL @DISPLAY Field 7
  1161.         KEY @8 CALL @DISPLAY Field 8
  1162.         KEY @10 CALL @DISPLAY Field 10
  1163.         KEY @11 CALL @DISPLAY Field 11
  1164.         KEY @13 CALL @DISPLAY Field 13
  1165.         KEY @14 CALL @DISPLAY Field 14
  1166.         KEY @15 QUIT
  1167.         /.
  1168.            Use the cursor keys to select a cell below:
  1169.  
  1170.            ^K Field 1      ^K Field 2      ^K Field 3
  1171.            ^K Field 4      ^K Field 5      ^K Field 6
  1172.            ^K Field 7      ^K Field 8      ^K
  1173.            ^K Field 10     ^K Field 11     ^K
  1174.            ^K Field 13     ^K Field 14     ^K Quit
  1175.         ./
  1176.         - @DISPLAY
  1177.         ECHO ^P10,10^C2You selected ^E1^ ^E2^
  1178.         PAUSE 2                 /* Waits for two seconds or a user keystroke
  1179.         POP
  1180.  
  1181. For instructional purposes only, the text screen labels the fields sequentially
  1182. in the order that the program sees them (left to right, top line down).  There's
  1183. no reason you'd have the user see something like "Field 4" when they selected
  1184. something.
  1185.  
  1186. The (RIGHT) and (LEFT) KEY statements do about what you'd expect them to do.
  1187. They move the cursor one field to the left or right ("KEY (RIGHT) FIELD 1" moves
  1188. it one field to the right).  When the cursor is on the last field of a row,
  1189. pressing (RIGHT) will move it to the first field of the next row.  Pressing
  1190. (LEFT) will do the reverse.
  1191.  
  1192. DEMOSYS.DOC                   Last revised 01/15/93                     Page 28
  1193.  
  1194. The (UP) and (DOWN) key statements had to trick the program.  If you want the
  1195. cursor to move down to the cell immediately below the current one, the program
  1196. has to be told to move the cursor over three fields.  If, for example, the
  1197. cursor is on field 1, "SET (DOWN) FIELD 3" tells the program to move to field 1
  1198. --> 2 --> 3 --> 4 and stop there.
  1199.  
  1200. If you want to, test out this example eliminating those "unused" ^K designators.
  1201.  
  1202. When the (ENTER) key is pressed, if there is a key field defined on the screen,
  1203. the program checks to see where the cursor is currently positioned.  It then
  1204. executes any KEY statement found for that particular field position.  These KEY
  1205. statements provide the field position as "KEY @n action_command", where "n" is
  1206. the field number.
  1207.  
  1208. (Any "KEY (ENTER) action_command" statements are ignored if there are fields
  1209. defined on the screen.  You have to use cursor movements if you've defined
  1210. fields.)
  1211.  
  1212. There are two fields, fields 9 and 12, which don't have an text next to them.
  1213. If you look through the key assignments, you'll notice there are no
  1214. corresponding "KEY @9 action_command" or "KEY @12 action_command" statements.
  1215. These are dummy fields.  The cursor will be allowed to rest on these fields but
  1216. if the user presses (ENTER), nothing happens.
  1217.  
  1218. Notice the SET CURSOR assignment too.  This one:
  1219.  
  1220.         SET CURSOR ^C2(^T8)
  1221.  
  1222. sets the cursor to a different color, prints a left parenthesis, skips 8
  1223. characters (not printing over what's already there on the screen), and then
  1224. prints the right parenthesis, still in the different color.  This is fairly
  1225. common in full-screen systems.
  1226.  
  1227. Compile this code ("DEMOMAKE EXAM07.CTL EXAM07.EXE") and then test it out
  1228. ("EXAM07").  The screen will clear, you'll get a small menu, and you can pick
  1229. any of the options by using the cursor keys and then pressing Enter.  When
  1230. you're done, press Q or move the cursor to the Q option and press Enter.  You'll
  1231. then be returned to DOS.
  1232.  
  1233.  
  1234. DEMOSYS.DOC                   Last revised 01/15/93                     Page 29
  1235.  
  1236. Keys defined by default:
  1237.  
  1238. The DEMO System pre-defines four key combinations for you.  They are defined for
  1239. debugging and "whoops!" purposes.  These assignments are:
  1240.  
  1241.         SET (C-C) QUIT
  1242.         SET (C-F1) ECHO ^P25,65^EFNAME^@
  1243.         SET (C-J) RUN
  1244.         SET (C-R) REDRAW
  1245.  
  1246. The first assignment provides a QUIT definition, allowing you to get out of the
  1247. program.  This is often necessary because it frequently turns out that even when
  1248. you remember to code one of more QUIT statements in your program, you code a
  1249. screen that leaves you in any infinite loop.  (The most common way to do this is
  1250. to have a page which calls itself.)
  1251.  
  1252. The second assignment tells you the current screen name.  This is useful when
  1253. you're viewing a demo and you notice that you need to make a change to a
  1254. particular screen.  Maybe you forgot to code a key assignment or the characters
  1255. don't align properly.
  1256.  
  1257. The third assignment allows you to jump to DOS.  You need to say "EXIT" at the
  1258. command line in order to be returned to The DEMO System.  This is useful for
  1259. checking directories, making sure required files are present, etc.
  1260.  
  1261. The fourth assignment redraws the current screen for you.  This is frequently
  1262. useful when you've done something like run a DOS command which has messed up
  1263. your display screen and you need to get the menu back on.  (You can also do this
  1264. with a "SCREEN 0" command although that command behaves somewhat differently.
  1265. See the reference manual.)
  1266.  
  1267. You can reassign these keys if desired by doing specific reassignments (e.g.
  1268. "SET KEY (C-C) GOTO @HOME" or "SET KEY (C-F1) (NONE)").  They provide some
  1269. useful functionality though and defining other keys to do the same thing is
  1270. recommended if you need these key sequences for something else.
  1271.  
  1272.  
  1273. DEMOSYS.DOC                   Last revised 01/15/93                     Page 30
  1274.  
  1275. Self-running demos:
  1276.  
  1277. You may find yourself wanting to create some self-running demos, where the
  1278. user's keys are in fact pressed for them.  The user will see the results of
  1279. each key press (e.g. the cursor will move).  This may
  1280. be desirable for an entire presentation or just for parts of a presentation.
  1281.  
  1282. Several action commands relate to this capability:
  1283.  
  1284.         BUFFER [ keys ]
  1285.         KEYPRESS
  1286.         PAUSE BREAK ON
  1287.         PAUSE BREAK OFF
  1288.         PAUSE DEMO seconds
  1289.  
  1290. The BUFFER command pushes keystrokes into a keystroke buffer.  Each keystroke
  1291. is retrieved sequentially on a first-in, first-out basis whenever a KEYPRESS
  1292. command is encountered or whenever the program awaits a keypress in a normal
  1293. text screen.  You can clear the buffer by skipping the "keys" parameter.
  1294.  
  1295. The KEYPRESS command is typically used in a label screen to get a keypress from
  1296. the buffer.  Since label screens never wait for a keypress otherwise (except
  1297. when executing PAUSE or PROMPT commands), this is the only way to have them
  1298. register any user-defined inputs.
  1299.  
  1300. PAUSE BREAK ON says that a user can escape out of buffered keystrokes by
  1301. pressing the Escape key.  Doing so clears the keystroke buffer.  This is useful
  1302. if you want them to be able to do something on their own instead of getting
  1303. stuck with your keystrokes only.  PAUSE BREAK ON is the default in The DEMO
  1304. System.
  1305.  
  1306. PAUSE BREAK OFF is the opposite of PAUSE BREAK ON.  PAUSE BREAK ON is the
  1307. default for The DEMO System.  Note that it's possible to crash The DEMO System
  1308. (as well as your reputation) through poor placement of a BUFFER command.
  1309. Placing a BUFFER command in a screen that is frequently executed may result in
  1310. the BUFFER being filled up and provide no convenient way for the user to get
  1311. out.  If you have PAUSE BREAK OFF in effect, you may provide yourself will no
  1312. way out of an overflowing buffer.  Having said this, PAUSE BREAK OFF is clearly
  1313. necessary in some cases.
  1314.  
  1315. PAUSE DEMO seconds tells The DEMO System to wait a specified number of seconds
  1316. before processing each keystroke.  The user can press a key before the number
  1317. of seconds is up, in which case the next keystroke will be activated (or, if
  1318. PAUSE BREAK ON is in effect and they press Escape, they'll clear the buffer).
  1319. The default value for this is PAUSE DEMO 1.  Other than PAUSE DEMO 0 (which
  1320. operates too quickly to be seen on some systems), PAUSE DEMO 1 is as fast as you
  1321. can go.
  1322.  
  1323. Note that the contents of the buffer is not applied to PROMPT or PAUSE/PAUSEA
  1324. action commands.  The system will not take the buffered input to answer a prompt
  1325. or get out of a wait condition.
  1326.  
  1327. DEMOSYS.DOC                   Last revised 01/15/93                     Page 31
  1328.  
  1329. Creating menuing systems:
  1330.  
  1331. The DEMO System provides enough functionality to create your own menuing system,
  1332. providing menu access to basic DOS commands as well as a program launcher for
  1333. other application products.  You can set up a series of screens which let the
  1334. user select applications to run or execute various DOS functions for them.
  1335.  
  1336. Several action commands provide DOS functionality and closely correspond to the
  1337. standard DOS commands.  These are listed below without explanation.  See the
  1338. reference manual if any of them don't make sense to you.
  1339.  
  1340.         CD directory
  1341.         CDD drive:directory
  1342.         COPY file1 file2
  1343.         DELETE filename
  1344.         DRIVE letter
  1345.         MD directory
  1346.         RD directory
  1347.         RUN [ string ]
  1348.  
  1349. Several action commands are a bit more obscure.  These are listed below and
  1350. described afterward:
  1351.  
  1352.         PROMPT ^Evar^ pattern string
  1353.         QUIT [ return_code ]
  1354.         RUNA [ string ]
  1355.         WRITE filename string
  1356.  
  1357. The PROMPT command prompts the user for a response and sets an environmental
  1358. variable to their response.  It consists of several parts (which are described
  1359. completely in the reference manual):
  1360.  
  1361. * "^Evar^" is the environmental variable that stores the results of the user's
  1362. input.
  1363.  
  1364. * "pattern" defines the type of input that is expected.  The "pattern" can be
  1365. replaced by any of the following words:
  1366.         FILESPEC        A DOS file specification
  1367.         VFILESPEC       An existing DOS filename
  1368.         MM/DD/YY        A valid date
  1369.         PATH            A DOS file path
  1370.         VPATH           An existing DOS file path
  1371. or by any combination of the following characters:
  1372.         A               alpha input (A-Z) (either upper or lower case)
  1373.         B               Boolean input (T/F/Y/N; translated to Y/N on output)
  1374.         N               numeric input (digits 0 to 9 only)
  1375.         U               uppercase alpha (A-Z) only (translated to uppercase
  1376.                         if provided in lowercase)
  1377.         X               any character (decimal 32 to 125) (no translation)
  1378.         !               uppercase any character (decimal 32 to 125) (translated
  1379.                         to uppercase if provided in lowercase)
  1380.         else            any other characters in the pattern are left in the
  1381.                         result verbatim; spaces are not allowed
  1382.  
  1383. DEMOSYS.DOC                   Last revised 01/15/93                     Page 32
  1384.  
  1385. * "prompt" is what the user sees before filling in their answer.  The prompt and
  1386. can include the normal control codes (^Cx, ^Prow,col, etc) that are allowed for
  1387. most strings in The DEMO System.
  1388.  
  1389. The QUIT command has already been used in a few examples to get out of the
  1390. program.  It also provides the ability to pass a return code to DOS.  Quitting
  1391. and looking for a return code is one way that a menu batch command can run
  1392. another application without running out of memory.  An easier method is to
  1393. create a batch file in the menuing system and test for this batch file on exit.
  1394. The easier method is demonstrated below.
  1395.  
  1396. The RUNA command switches to the alternate screen before running a DOS command.
  1397. You will see the command run but it probably won't permanently affect your menu
  1398. display.  Many applications will take charge of your screens anyway and they'll
  1399. affect the menu.  Note that using RUN or RUNA means The DEMO System remains in
  1400. memory while your command is run.  The DEMO System requires close to 100K of
  1401. RAM.  If your program needs more than about 500K, you will have to exit the
  1402. system (using QUIT), run a batch file, and then return to The DEMO System.  This
  1403. is demonstrated below.
  1404.  
  1405. The WRITE command writes a line to a text file.  This is typically used for
  1406. creating a batch file from scratch.  It can also be used to create accounting
  1407. records saying that a particular command was run at a particular date and time.
  1408.  
  1409.  
  1410. DEMOSYS.DOC                   Last revised 01/15/93                     Page 33
  1411.  
  1412. Program Example 8:
  1413.  
  1414. This is going to be a fairly complicated example.  For most real menuing
  1415. systems, you need to set up a batch file that calls The DEMO System and then
  1416. optionally calls another batch file which has commands to execute.  This is done
  1417. for any command that is too big to fit into memory.
  1418.  
  1419. In this example, most of the options in the menu are directly available from The
  1420. MENU System but one, running WordPerfect, is not.  We presume for the sake of
  1421. this example that you have a batch file called WP.BAT that invokes WordPerfect,
  1422. changing the subdirectory and drive if necessary, and running it will all of the
  1423. proper options.  You could have many batch files if you wanted to.  The DEMO
  1424. System also allows you to create files (such as batch files) on the fly using
  1425. the WRITE action command.
  1426.  
  1427. You also have a batch file that you're running The DEMO System from.  We'll call
  1428. it EXAMMENU.BAT and it looks like this:
  1429.  
  1430.         ECHO OFF
  1431.         :Restart
  1432.         EXAM08
  1433.         IF NOT EXIST EXAM08X.BAT GOTO :Done
  1434.         CALL EXAM08X.BAT
  1435.         GOTO :Restart
  1436.         :Done
  1437.  
  1438. This batch file loads The DEMO System's program (EXAM08.EXE in this case).  Once
  1439. the program runs, the batch file checks to see if it has created a file called
  1440. EXAM08X.BAT.  If yes, that batch file is run and then The DEMO System is entered
  1441. again.  If not, then the user is returned to DOS.
  1442.  
  1443. EXAM08.EXE is the file you're creating with The DEMO System this time.  Its
  1444. source control cards look like this:
  1445.  
  1446.         /* Creating a sample user menu
  1447.         - (ONCE)
  1448.         DELETE EXAM08X.BAT     /* Killing off the temporary batch file
  1449.         - *000 Main menu
  1450.         KEY (UP) FIELD -1
  1451.         KEY (DOWN) FIELD 1
  1452.         KEY @1,A CALL @SHELLRUN WP.BAT
  1453.         KEY @2,B CALL @RUN CHKDSK
  1454.         KEY @3,C CALL @RUN DIR /W
  1455.         KEY @4,D CALL @RUN FORMAT A:
  1456.         KEY @5,E CALL @SHELL
  1457.         KEY @6,Q,(ESC) GOTO @QUIT     /* EXAM08X.BAT is gone so batch program st
  1458.         SET CURSOR ^C1==>
  1459.         /.
  1460.         Sample menuing system:
  1461.  
  1462.             Pick an option:
  1463.  
  1464.             ^K   A Run WordPerfect
  1465.             ^K   B Run CHKDSK
  1466.             ^K   C Do a directory
  1467.             ^K   D Run FORMAT A:
  1468.             ^K   E Drop into DOS
  1469. DEMOSYS.DOC                   Last revised 01/15/93                     Page 34
  1470.  
  1471.  
  1472.             ^K   Q Quit
  1473.         ./
  1474.         - @RUN Running a command while staying in The MENU System
  1475.         CLS       /* Unnecessary, but it looks better
  1476.         RUN ^E1^ ^E2^ ^E3^ ^E4^
  1477.         ECHO Press a key to continue
  1478.         PAUSE
  1479.         POP
  1480.         - @SHELLRUN Running a batch command.
  1481.         /* Copying the file as EXAM08X.BAT which is tested for in the
  1482.         /* main batch file.
  1483.         COPY ^E1^ EXAM08X.BAT
  1484.         QUIT
  1485.         - @SHELL Leaving the user in DOS itself
  1486.         ECHO ^P20,1Enter EXIT and then (ENTER) to go back into The MENU System
  1487.         RUN
  1488.         POP
  1489.         - @QUIT Quitting
  1490.         ECHO ^P20,1Thanks for your interest!
  1491.         QUIT
  1492.  
  1493. The entire menuing system consists of just five screens in this example, three
  1494. of which are labels and one of which is a (ONCE) declaration.  This leaves just
  1495. one visual screen for the user to see.  You could easily create a multiple-page
  1496. menuing system which allowed the user to branch through a long series of
  1497. commands and such.
  1498.  
  1499. The very first screen is a (ONCE) statement that deletes the file EXAM08X.BAT.
  1500. A (ONCE) statement contains statements that you only want run when The DEMO
  1501. System first starts up.  EXAM08X.BAT is the file that is tested for in the
  1502. EXAMMENU.BAT file and whose non-existance means that there's nothing more for
  1503. the program to do ("IF NOT EXIST EXAM08X.BAT GOTO :Done").  The only way that
  1504. file is recreated is in label @SHELLRUN; any other way out of the program will
  1505. result in the file not being there so the user will be left in DOS.
  1506.  
  1507. The first KEY assignment gives control to this @SHELLRUN label.  It passes the
  1508. name of the batch file that should be copied over EXAM08X.BAT.  (You could
  1509. create the batch file on the fly with WRITE commands but it's easier to take an
  1510. existing one if you can.)  The passed parameter becomes environmental variable
  1511. ^E1^ (subsequent ones would have become ^E2^ to ^E9^).
  1512.  
  1513. The @SHELLRUN label expands ^E1^ into "WP.BAT" and then copies this file over
  1514. EXAM08X.BAT.  It then quits to DOS, at which point the EXAMMENU.BAT file kicks
  1515. in, runs the program, and then puts you back into The MENU System.
  1516.  
  1517. There are several RUN commands in the program but all of the programs they're
  1518. running can be done within about 520K of memory so they do not cause problems.
  1519.  
  1520. Try the command out (the EXAMMENU.BAT file is also in the SAMPLES.ZIP file)
  1521. and see if it works the way you expect it to.
  1522.  
  1523. DEMOSYS.DOC                   Last revised 01/15/93                     Page 35
  1524.  
  1525. Using (GLOBAL):
  1526.  
  1527. It's time to backtrack a bit.  Six screen page statements were introduced back
  1528. at the beginning of this tutorial:
  1529.  
  1530.         - filename [ description ]            /* Screen text is external
  1531.         - *ref [ description ]                /* Screen text is imbedded
  1532.         - @label [ description ]              /* Action-only pages
  1533.         - (GLOBAL) [ description ]            /* Establish defaults for later
  1534.         - (SETn) [ description ]              /* Provide recallable settings
  1535.         - (ONCE) [ description ]              /* Done once only
  1536.  
  1537. So far, we've covered the first three of these without saying much about the
  1538. remaining ones.
  1539.  
  1540. The (GLOBAL) statement is used when you have a lot of similar screens and you
  1541. want to avoid coding the same basic KEY statements or SET statements for each of
  1542. them.
  1543.  
  1544. For example, say you have a series of screens, all of which should have the same
  1545. cursor shape and all of which should uniformly treat (RIGHT), (LEFT), (UP), and
  1546. (DOWN).  You could of course code the same KEY and SET statements in for each of
  1547. these screens.  Alternatively, you could establish a default for KEY and SET
  1548. statements and all screens defined after that default is set will share those
  1549. defaults.
  1550.  
  1551. In our case, you could say:
  1552.  
  1553.         - (GLOBAL) Establishing certain defaults
  1554.         KEY (RIGHT) FIELD 1
  1555.         KEY (LEFT) FIELD -1
  1556.         KEY (UP) FIELD -3
  1557.         KEY (DOWN) FIELD 3
  1558.         KEY (ESC) POP
  1559.         SET CURSOR ^C2(^T8)
  1560.         - TEST01.SCR First screen
  1561.         - TEST02.SCR Second screen
  1562.         - TEST03.SCR Third screen
  1563.  
  1564. Presuming that the files TEST01.SCR, TEST02.SCR, and TEST03.SCR all share the
  1565. same types of field assignments, this would work fine.
  1566.  
  1567. (GLOBAL) is presumed for any statements that appear in the control file before
  1568. the first real screen is encountered.  You only *need* to use the (GLOBAL) if
  1569. you want to redefine the defaults part-way through a control file.
  1570.  
  1571. Whenever (GLOBAL) is encountered, all previously-defined (GLOBAL) KEY
  1572. assignments are cleared but SET statements are not.
  1573.  
  1574. You cannot put regular action command (like RUN) in a (GLOBAL) section although
  1575. they can be assigned to a keystroke in that section.  Otherwise, you'd end up
  1576. with an action command being performed at the start of every screen.
  1577.  
  1578. DEMOSYS.DOC                   Last revised 01/15/93                     Page 36
  1579.  
  1580. More labor-saving techniques:
  1581.  
  1582. The (GLOBAL) statement (discussed above) is one way to save yourself from
  1583. adding a lot of repeating lines to your control file.  Other labor-saving tools
  1584. exist and this section discusses them.  These include (SETn) statements, Macros,
  1585. and included text.
  1586.  
  1587.  
  1588. (SETn) statements:
  1589.  
  1590. There can only be one set of (GLOBAL) statements defined at a time.  Frequently,
  1591. you will want to have alternative defaults that you bring in.
  1592.  
  1593. For example, let's say you have a presentation which has some screens with
  1594. single input columns, some with double input columns, and some with only
  1595. horizontal selections (e.g. "Pick a drive: A B C D E F G").  You could spend
  1596. your time trying to make sure that all screens with similar characteristics
  1597. follow each other in sequence but that might destroy the "natural order" of your
  1598. control file.
  1599.  
  1600. The first easy way to get around this is to use (SETn) statements.  These are of
  1601. the format:
  1602.  
  1603.         - (SETn) [ description ]              /* Provide recallable settings
  1604.  
  1605. You can define up to ten (SETn) definitions, where "n" is a digit from "0" to
  1606. "9".  In our example, we could define three (SETn) statements:
  1607.  
  1608.         - (SET0) Single-column input
  1609.         SET KEY (DOWN) FIELD 1
  1610.         SET KEY (UP) FIELD -1
  1611.         SET KEY (HOME) TOP     /* Takes you to first field on screen
  1612.         SET KEY (END) BOTTOM   /* Takes you to last field on screen
  1613.         SET KEY (ESC) POP
  1614.         - (SET1) Dual-column input
  1615.         SET KEY (RIGHT) FIELD 1
  1616.         SET KEY (LEFT) FIELD -1
  1617.         SET KEY (UP) FIELD -2
  1618.         SET KEY (DOWN) FIELD 2
  1619.         SET KEY (HOME) TOP
  1620.         SET KEY (END) BOTTOM
  1621.         SET KEY (ESC) POP
  1622.         - (SET2) Horizontal input
  1623.         SET KEY (LEFT) FIELD -1
  1624.         SET KEY (RIGHT) FIELD 1
  1625.         SET KEY (HOME) TOP
  1626.         SET KEY (END) BOTTOM
  1627.         SET KEY (ESC) POP
  1628.  
  1629. DEMOSYS.DOC                   Last revised 01/15/93                     Page 37
  1630.  
  1631. Then, in the screens that need these key definitions, you can refer to the
  1632. appropriate (SETn) definition by using the SET KEYS statement:
  1633.  
  1634.         - TEST01.001 First file with single-column input
  1635.         SET KEYS SET0
  1636.         - TEST01.002 Double-column input
  1637.         SET KEYS SET1
  1638.         - TEST01.003 Another single-column input
  1639.         SET KEYS SET0
  1640.  
  1641. The (SETn) section can also include regular SET statements like SET CURSOR, SET
  1642. COLOR, etc.  These definitions will be brought in if you use the "SET SETTINGS
  1643. SETn" statement in your program.
  1644.  
  1645. Action commands are ignored within a (SETn) definition.
  1646.  
  1647. When you use the SET KEYS or SET SETTINGS statements, the (SETn) definitions
  1648. are added to whatever you already have in your current screen's configuration.
  1649. The configuration is not cleared first.  If the (SETn) definition includes a KEY
  1650. assignment that you try to redefine later for this same screen in your control
  1651. card file, the (SETn) definition will win.
  1652.  
  1653. You must define the (SETn) section before you invoke it.  You can re-use the
  1654. (SETn) declaration if you want.
  1655.  
  1656. The SET KEYS and SET SETTINGS statements count as action commands so they cannot
  1657. be used in (GLOBAL) sections.  Macros, on the other hand, can appear anywhere.
  1658.  
  1659.  
  1660. DEMOSYS.DOC                   Last revised 01/15/93                     Page 38
  1661.  
  1662. Macros:
  1663.  
  1664. Macros are groups of code that are brought in whenever needed.  Macros can
  1665. include SET statements, KEY definitions, action commands, (GLOBAL) statements,
  1666. etc.  In fact, a Macro can include any statement except another block of macro
  1667. statements.
  1668.  
  1669. In most cases, you will only find Macros useful for setting up KEY definitions
  1670. that you want to include in (GLOBAL) statements.  You may also find Macros
  1671. useful in labels when several labels include the same block of action commands.
  1672.  
  1673. Macros begin with a MACRO declaration and include every control line from the
  1674. statement after the MACRO declaration to a corresponding MEND statement:
  1675.  
  1676.         MACRO name [ REUSE | SKIP ]
  1677.         ...
  1678.         MEND
  1679.  
  1680. There has to be one and only one MEND statement for every MACRO declaration.
  1681. The Macro name is truncated at eight characters and has to be unique against all
  1682. other Macro names up to those eight characters.  If "REUSE" is specified and the
  1683. macro name is already in use, the new definition will replace it.  If "SKIP" is
  1684. specified and the macro name is already in use, the new definition will be
  1685. ignored.
  1686.  
  1687. The Macro has to be defined before it is invoked.
  1688.  
  1689. In order to invoke a Macro, you must use the following command:
  1690.  
  1691.         DO name [ parms ]
  1692.  
  1693. The "name" corresponds with the Macro name (again, being truncated at eight
  1694. characters).  The optional parameters allow you to pass in up to 9 words.  These
  1695. words will replace special variables &1 to &9 if any of these variables are
  1696. found within the macro or within any code encountered before the next DO
  1697. statement.  This means that the &1 to &9 variables can appear just about
  1698. anywhere but they will only have a value once a DO statement passes them a
  1699. value.
  1700.  
  1701. If desired, you can issue a DO statement against a system-defined fake Macro
  1702. named (DUMMY).  Depending on whether you pass parameters in or not, you can
  1703. either change the definition of &1 to &9 or clear them entirely.
  1704.  
  1705. Just like the MACRO statement itself, the DO statement can appear anywhere in
  1706. your control card file.
  1707.  
  1708.  
  1709. DEMOSYS.DOC                   Last revised 01/15/93                     Page 39
  1710.  
  1711. Program Example 9:
  1712.  
  1713. In this example, we'll define a Macro and use it and the &1 to &9 variables a
  1714. little bit.
  1715.  
  1716. Create the following control cards and save them as EXAM09.CTL:
  1717.  
  1718.         MACRO @TESTING  /* A sample macro
  1719.         ECHO &1 is coming to &2
  1720.         ECHO Get your &3 ready!
  1721.         ECHO
  1722.         PAUSE 2
  1723.         MEND
  1724.         - @001 Invoking the macro
  1725.         DO @TESTING Santa_Claus town stockings
  1726.         DO @TESTING Bill_Clinton Washington_DC special_interests
  1727.         DO @TESTING George_Bush Texas tax_exemptions
  1728.         ECHO The value of &^_1 is &1
  1729.         DO (DUMMY)
  1730.         ECHO The value of &^_1 is now &1
  1731.         LOCATE 20 1
  1732.         QUIT
  1733.  
  1734. The Macro is invoked three times within one screen, each time passing in three
  1735. different parameters.  Then one of the parameters is tested outside of the
  1736. Macro.  Then DO (DUMMY) is invoked with no parameters, clearing &1 to &9 and one
  1737. of the variables is tested again.
  1738.  
  1739. One trick that you'll notice here is the use of ^_.  This control combination is
  1740. ignored by the system but only after the other parameters have been resolved.
  1741. As a result, "&1" will actually show up when the ECHO command is printed instead
  1742. of "George_Bush" (a definite improvement too).
  1743.  
  1744. As always, compile this text file ("DEMOMAKE EXAM09.CTL EXAM09.EXE") and then
  1745. run the program ("EXAM09").  See if it works the way you'd expect.
  1746.  
  1747.  
  1748. DEMOSYS.DOC                   Last revised 01/15/93                     Page 40
  1749.  
  1750. Included text:
  1751.  
  1752. Periodically, you will develop a subset of a demo file that you will want to use
  1753. in several demos.  For example, you might have a group of screens that talk
  1754. about modem problems and you decide to include this in both a technical help
  1755. program as well as in a demonstration of your BBS.
  1756.  
  1757. While you could manually copy the lines to include into your file, it's easier
  1758. to tell your main control file to include at some point the other text.  This is
  1759. done using the + control statement:
  1760.  
  1761.         + filename
  1762.  
  1763. When The DEMO System encounters one of these statements, it will stop processing
  1764. the current file and start processing the new file.  When done with that file,
  1765. it will return to the originating file.
  1766.  
  1767. Included files can have any type of control cards in them (including Macros).
  1768. They can also have included files, nesting being limited roughly by the number
  1769. of remaining file handles your DOS environment has allowed for.
  1770.  
  1771.