home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / graphics / demos304.zip / DEMOSYS.REF < prev    next >
Text File  |  1993-03-13  |  114KB  |  2,718 lines
  1.  DEMOSYS.REF                   Last revised 03/13/93                     Page 1
  2.  
  3.                                 The DEMO System
  4.  
  5.                                  Wayne Software
  6.                                113 Sheffield St.
  7.                             Silver Spring, MD 20910
  8.  
  9.                           Fax support: (301) 588-8986
  10.  
  11.                                 Reference manual
  12.  
  13. --------------------------------------------------------------------------------
  14.  
  15.                                Table of contents
  16.  
  17. Table of contents ...............................................  1
  18. Command-line options:
  19.   DEMOMAKE.EXE ..................................................  5
  20.   The DEMO System viewer ........................................  6
  21. Control card references .........................................  7
  22.   Screen pages ..................................................  8
  23.     - filename [ description ] ..................................  8
  24.     - *ref [ description ] ......................................  9
  25.     - (GLOBAL) [ description ] ..................................  9
  26.     - (GLOBALNC) [ description ] ................................ 10
  27.     - (ONCE) [ description ] .................................... 10
  28.     - (SETn) [ description ] .................................... 10
  29.     - @label [ description ] .................................... 11
  30.     /.,  ./ ..................................................... 11
  31.  
  32.   Statement reference ........................................... 12
  33.     + filename .................................................. 12
  34.     Comments .................................................... 12
  35.     DATADIR [ subdirectory ] .................................... 12
  36.     DO name [ parms ], DO (DUMMY) [ parms ] ..................... 13
  37.     MACRO name [ REUSE | SKIP ], MEND ........................... 13
  38.  
  39.   SET statements ................................................ 14
  40.     SET BASE n .................................................. 14
  41.     SET CASE ON, SET CASE OFF ................................... 14
  42.     SET CLS ON, SET CLS OFF ..................................... 14
  43.     SET COLOR settings .......................................... 15
  44.     SET CURSOR string ........................................... 15
  45.     SET KEYS CLEAR .............................................. 16
  46.     SET KEYS (SETn) ............................................. 16
  47.     SET LOGO string ............................................. 16
  48.     SET MONO settings ........................................... 16
  49.     SET MOUSE ON, SET MOUSE OFF ................................. 17
  50.     SET SETTINGS CLEAR .......................................... 17
  51.     SET SETTINGS (SETn) ......................................... 17
  52.     SET TOP screen .............................................. 17
  53.  DEMOSYS.REF                   Last revised 03/13/93                     Page 2
  54.  
  55.   Action commands:
  56.     ASSIGN ^Uvar^ [ = string ] .................................. 18
  57.     BEEP ........................................................ 18
  58.     BUFFER [ chars ] ............................................ 18
  59.     CALL screen [ KEYn | parms ] ................................ 19
  60.     CD directory ................................................ 19
  61.     CDD drive:directory ......................................... 19
  62.     CLS ......................................................... 20
  63.     CLSA ........................................................ 20
  64.     COPY file1 file2 ............................................ 20
  65.     DATA ........................................................ 20
  66.     DELETE filename ............................................. 20
  67.     DISPLAY COLOR, DISPLAY MONO, DISPLAY TOGGLE ................. 21
  68.     DRIVE letter ................................................ 21
  69.     DROP location ............................................... 21
  70.     ECHO [ string[@] ] .......................................... 22
  71.     ECHOA [ string[@] ] ......................................... 22
  72.     FIELD [ TOP | FIRST | -999 to 999 | BOTTOM | LAST |
  73.       @1 to @99 ] ............................................... 22
  74.     GOTO screen [ KEYn | CLEAR | parms ] ........................ 23
  75.     HOP location ................................................ 24
  76.     IF cond1 rel cond2 THEN HOP location ........................ 25
  77.     KEYPRESS .................................................... 25
  78.     LOADLOGO ^Uvar^ char_count .................................. 26
  79.     LOADLOGO CLEAR .............................................. 27
  80.     LOCATE row col .............................................. 27
  81.     MD directory ................................................ 27
  82.     MSGBOX type message ......................................... 28
  83.     MSGBOXA type message ........................................ 28
  84.     NONE ........................................................ 29
  85.     PAUSE [ seconds ] ........................................... 30
  86.     PAUSEA [ seconds ] .......................................... 30
  87.     PAUSE BREAK ON, PAUSE BREAK OFF ............................. 30
  88.     PAUSE DEMO seconds .......................................... 30
  89.     PLAY string ................................................. 31
  90.     PLAY ON, PLAY OFF ........................................... 31
  91.     POP [ TOP | 1 to 20 ] [ KEYn ] .............................. 32
  92.     PROMPT ^Uvar^ "pattern" [ other parms ] ..................... 33
  93.     PROMPTA ^Uvar^ "pattern" [ other parms ] .................... 37
  94.     QUIT [ return_code ] ........................................ 38
  95.     RD directory ................................................ 39
  96.     REDRAW ...................................................... 40
  97.     RUN [ string ] .............................................. 41
  98.     RUNA [ string ] ............................................. 42
  99.     SAVE filename ............................................... 42
  100.     SCREEN { TOP | FIRST | -999 to 999 | BOTTOM | LAST }
  101.       [ KEYn | CLEAR | parms ]................................... 43
  102.     SELECT ...................................................... 44
  103.     WRITE filename string ....................................... 44
  104.     @ ^Uvar^ "pattern" [ other parms ] .......................... 45
  105.  
  106.  DEMOSYS.REF                   Last revised 03/13/93                     Page 3
  107.  
  108.   KEY statement ................................................. 47
  109.   Miscellaneous string concepts ................................. 48
  110.     &Pn:    Variables passed in when invoking DEMOMAKE itself.... 49
  111.     &n:     Variables passed in when doing DO statements......... 51
  112.     ^Uvar^: User-defined variables............................... 51
  113.     ^EVar^: DOS-defined environmental variables.................. 51
  114.     %Func%: System-defined functions............................. 52
  115.       %Add%(n,n) ................................................ 53
  116.       %Col% ..................................................... 53
  117.       %Date% .................................................... 53
  118.       %DateOrig% ................................................ 53
  119.       %DateR2S%(n) .............................................. 53
  120.       %DateS2R%(s) .............................................. 53
  121.       %DateValid%(s) ............................................ 53
  122.       %Dir% ..................................................... 53
  123.       %Display% ................................................. 53
  124.       %DisplayEGA% .............................................. 53
  125.       %DisplayNum% .............................................. 53
  126.       %DisplayVGA% .............................................. 53
  127.       %Div%(n,n) ................................................ 54
  128.       %Drive%(c) ................................................ 54
  129.       %DriveCur% ................................................ 54
  130.       %DriveDir%(c) ............................................. 54
  131.       %DriveDirOrig% ............................................ 54
  132.       %DriveLabel%(c) ........................................... 54
  133.       %DriveOrig% ............................................... 54
  134.       %DriveSpace%(c) ........................................... 54
  135.       %FieldMax% ................................................ 54
  136.       %FieldNum% ................................................ 54
  137.       %FileDate%(s) ............................................. 55
  138.       %FileExist%(s) ............................................ 55
  139.       %FileJoin%(c) ............................................. 55
  140.       %FileMakeTest%(s) ......................................... 55
  141.       %FileOrig% ................................................ 55
  142.       %FileOrigDir% ............................................. 55
  143.       %FileSize%(s) ............................................. 55
  144.       %FileTime%(s) ............................................. 55
  145.       %FileValid%(s) ............................................ 55
  146.       %FreeEMS% ................................................. 56
  147.       %Instr%(s,s) .............................................. 56
  148.       %Instr2%(n,s,s) ........................................... 56
  149.       %Left%(s,n) ............................................... 56
  150.       %Len%(s) .................................................. 56
  151.       %Lower%(s) ................................................ 56
  152.  DEMOSYS.REF                   Last revised 03/13/93                     Page 4
  153.  
  154.       %Mid%(s,n,n) .............................................. 56
  155.       %Mouse% ................................................... 56
  156.       %Mult%(n,n) ............................................... 56
  157.       %PageDesc% ................................................ 57
  158.       %PageLines% ............................................... 57
  159.       %PageMax% ................................................. 57
  160.       %PageName% ................................................ 57
  161.       %PageNum% ................................................. 57
  162.       %PathCanMake%(s) .......................................... 57
  163.       %PathExist%(s) ............................................ 57
  164.       %PrinterReady%(n) ......................................... 57
  165.       %Proper%(s) ............................................... 57
  166.       %ReplaceStr%(s,s,s) ....................................... 57
  167.       %Right%(s,n) .............................................. 57
  168.       %Row% ..................................................... 57
  169.       %Sub%(n,n) ................................................ 58
  170.       %Time% .................................................... 58
  171.       %TimeElapsed% ............................................. 58
  172.       %TimeOrig% ................................................ 58
  173.       %TimeR2S%(n) .............................................. 58
  174.       %TimeS2R%(s) .............................................. 58
  175.       %Trim%(s) ................................................. 58
  176.       %Upper%(s) ................................................ 58
  177.       %Weekday%(s) .............................................. 58
  178.       %1% to %9% ................................................ 58
  179.     ^ctrl:  Control codes ....................................... 59
  180.     Primary vs alternate screens ................................ 60
  181.   System maximums ............................................... 60
  182.  
  183.  DEMOSYS.REF                   Last revised 03/13/93                     Page 5
  184.  
  185. --------------------------------------------------------------------------------
  186.  
  187.                               Command-line options
  188.  
  189. DEMOMAKE.EXE syntax:
  190.  
  191.         DEMOMAKE ctlname [ exename ] [ /OVERWRITE | /-OVERWRITE | /OVERASK ]
  192.           [ /SCAN ] [ /Xstring ] [ /Lstr ] [ /Q ] [ /? ] [ other parms ]
  193.  
  194. where:
  195.  
  196. "ctlname" is the name of the main control file that you want to process.  The
  197. main control file can include links to other control files if desired Drive and
  198. path information can be provided if desired.
  199.  
  200. "exename" is the name of the self-viewing file you want to create.  The name
  201. defaults to the ctlname with an .EXE extension.  If a name is provided without
  202. an extension, the extension defaults to "EXE".  Drive and path information can
  203. be provided if desired.
  204.  
  205. "/OVERWRITE" says to overwrite the output file if it already exists.
  206.  
  207. "/-OVERWRITE" says to abort if the output file already exists.
  208.  
  209. "/OVERASK" says to prompt if the output file exists already.  This is normally
  210. the default but you can use the CONFIGWS program to change it.
  211.  
  212. "/SCAN" is used to have the program review your control files without actually
  213. checking on any of the screen files (either imbedded or external).  This does
  214. not produce an EXE file but it's a useful way of quickly reviewing the validity
  215. of your file.
  216.  
  217. "/Xstring" is used to protect your control file from being regenerated by the
  218. DEMOSAVE program (available to registered users only).  The same string has to
  219. be provided when DEMOSAVE is run.
  220.  
  221. "/Lstr" is a flag that registered users may use which turns off the "Wayne
  222. Software" copyright message.
  223.  
  224. "/Q" says to not play any of the PLAY commands within the file.  Normally, they
  225. are all played during compilation in order to make sure they are valid.  In
  226. case you forget, you can also press the letter "Q" during compilation to turn
  227. it off.
  228.  
  229. "/?" or "/HELP" or "HELP" gives you syntactical information about how to use the
  230. command.
  231.  
  232. "other parms" are additional values that you want to pass in.  These will be
  233. substituted into the strings &P1 to &P9 (if any) found in your control cards or
  234. screen files.  Resolution of these parameters is done at compile time, not
  235. viewing time.  As such, you can pass in names of macros or anything else.  The
  236. case of your parameter is retained.  Multi-word parameters can be enclosed in
  237. quotes.
  238.  
  239.  DEMOSYS.REF                   Last revised 03/13/93                     Page 6
  240.  
  241. The DEMO System viewer syntax:
  242.  
  243.         exename [ /M ] [ /Q ] [ /? ]
  244.  
  245. where:
  246.  
  247. "exename" is the name of the self-viewing file created by DEMOMAKE.EXE.
  248.  
  249. "/M" says to use the monochrome (or alternate) color set.  The DEMO System
  250. defaults to the color (primary) set.
  251.  
  252. "/Q" says to skip all BEEP and PLAY statements.
  253.  
  254. "/?" or "/HELP" or "HELP" gives you syntactical information about how to use the
  255. command.
  256.  
  257.  
  258.  DEMOSYS.REF                   Last revised 03/13/93                     Page 7
  259.  
  260. --------------------------------------------------------------------------------
  261.  
  262.                              Control Card References
  263.  
  264. Descriptions below are separated into five sections:
  265.  
  266.   Screen pages:  This includes all GLOBAL and SET page types.  It also
  267.     includes /. ... ./ used for imbedded text screens.
  268.  
  269.   Statement Reference:  Macros and some other commands that don't fit
  270.     under the other groups below.
  271.  
  272.   SET statements:  Commands which are defined once for every screen page.
  273.  
  274.   Action commands:  Commands which can appear on their own in some types
  275.     of screen pages or else in KEY commands.
  276.  
  277.   KEY statements:  Commands which are activated by the user pressing a
  278.     given key on the keyboard.
  279.  
  280.   Miscellaneous string concepts:  Things like control codes, variables, and
  281.     functions.
  282.  
  283.  
  284. Note that within The DEMO System viewer, actions happen in a predictable order.
  285. This order is as follows:
  286.    (1)  All SET statements are executed.  The SET LOGO statement is not acted
  287.         upon until later.  If SET CLS ON is active, the screen is cleared.
  288.    (2)  The text screen (if any) is displayed.
  289.    (3)  The SET LOGO statement (if any) is activated; writing over any text that
  290.         is already on the screen.
  291.    (4)  If a data-entry form is provided (@ commands are used), the data-entry
  292.         form is completed.
  293.    (5)  Any action commands are activated.  If your action commands include any
  294.         command that clears the screen (like CLS), you'll wipe your text
  295.         screen out.
  296.    (6)  Any KEY commands are activated.  This step is not executed if a data-
  297.         entry form was provided.
  298.  
  299.  DEMOSYS.REF                   Last revised 03/13/93                     Page 8
  300.  
  301. --------------------------------------------------------------------------------
  302.  
  303.                                   Screen Pages
  304.  
  305. This section documents all of the various types of "pages" within The DEMO
  306. System.  All executable commands have to be assigned to a page.
  307.  
  308. Pages begin with a dash followed by a space.  Pages end *only* whenever any of
  309. the following conditions are met:
  310.  
  311.   * The end of the main control file is reached
  312.   * Another screen page control statement is reached.
  313.   * A QUIT, GOTO, SCREEN, KEYPRESS, or POP action command is encountered.
  314.  
  315. *******************
  316.  
  317. - filename [ description ]
  318.  
  319. Defines a page whose display screen is stored in an external file.  The filename
  320. can include drive and path information if desired.  Otherwise, the file will be
  321. looked for in your default subdirectory unless a DATADIR statement appears.
  322.  
  323. Note that even if drive/path information is coded, the related CALL or GOTO
  324. statement should not include this drive/path information.
  325.  
  326. All filenames (minus drive/path information) must be unique.
  327.  
  328. Note that the function %PageName% returns the filename and %PageDesc% returns
  329. the page description for this page.
  330.  
  331. The first screen displayed has to be a display screen, not a label screen.
  332.  
  333. These pages can include: SET statements
  334.                          Action commands
  335.                          KEY statements
  336.  
  337.  DEMOSYS.REF                   Last revised 03/13/93                     Page 9
  338.  
  339. *******************
  340.  
  341. - *ref [ description ]
  342.  
  343. Defines a page whose display screen is imbedded within /. ... ./ lines.
  344. Example:
  345.  
  346.         - *001 Testing
  347.         KEY (ESC) POP
  348.         /.
  349.                 Sample screen
  350.                    ^C2 Hi! ^C0
  351.         ./
  352.  
  353. The DEMOMAKE program actually requires that all display screens to be stored as
  354. external files.  As a result, when it encounters imbedded screens, it
  355. transparently writes them out to your default drive and subdirectory under the
  356. names ~DEMOINT.nnn (where "nnn" is a three-digit number assigned sequentially).
  357. These files are then read back in during the second pass and then deleted.  Due
  358. to this, imbedded files have to be processed twice and will be slower to compile
  359. than non-imbedded files.
  360.  
  361. Having said this, it's much easier to write documentation if the screens are
  362. imbedded so most examples in this document will show imbedded screens.
  363.  
  364. All references must be unique.
  365.  
  366. Note that the function %PageName% returns the file reference ("*ref") and
  367. %PageDesc% returns the page description for this page.
  368.  
  369. These pages can include: SET statements
  370.                          Action commands
  371.                          KEY statements
  372.  
  373. *******************
  374.  
  375. - (GLOBAL) [ description ]
  376.  
  377. Allows you to establish default KEY and SET settings.  Any KEY or SET statements
  378. that appear before you first screen page are presumed to be within (GLOBAL).
  379. The (GLOBAL) statement automatically resets all previously-defined (GLOBAL) KEY
  380. settings but does not affect any (GLOBAL) SET settings.
  381.  
  382. The (GLOBAL) statement affects all regular page references which follow it.
  383.  
  384. You cannot include any action commands within a (GLOBAL) definition.
  385.  
  386. These pages can include: SET statements
  387.                          KEY statements
  388.  
  389. DEMOSYS.REF                   Last revised 03/13/93                     Page 10
  390.  
  391. *******************
  392.  
  393. - (GLOBALNC) [ description ]
  394.  
  395. Identical to the (GLOBAL) reference except it does not clear any
  396. previously-defined (GLOBAL) KEY settings.
  397.  
  398. These pages can include: SET statements
  399.                          KEY statements
  400.  
  401. *******************
  402.  
  403. - (ONCE) [ description ]
  404.  
  405. Establishes a set of commands that is only executed once, at the start of the
  406. program.  Typically, the use of this is confined to LOADLOGO and associated DATA
  407. statements.  For menuing systems, you may find it desirable to put a DELETE
  408. statement in this section.
  409.  
  410. Note that the (ONCE) page counts as a page and can be used (usually
  411. accidentally) as a destination for SCREEN, CALL, and GOTO commands.
  412.  
  413. These pages can include: Action commands
  414.  
  415. *******************
  416.  
  417. - (SETn) [ description ]
  418.  
  419. Allows you to establish up to 10 sets of KEY and SET defaults.  "n" has to be a
  420. digit from "0" to "9".
  421.  
  422. The (SETn) KEY settings are invoked by using the "SET KEY (SETn)" command.
  423.  
  424. The (SETn) SET settings are invoked by using the "SET SETTINGS (SETn)" command.
  425.  
  426. You have to define the (SETn) before you use it.  You can re-specify the (SETn)
  427. settings if you want.  You can define (SETn) sections in any order; you don't
  428. have to define (SET0) before you define (SET1).
  429.  
  430. Action commands appearing within a (SETn) definition are ignored (unlike in
  431. (GLOBAL) definitions where they generate errors).
  432.  
  433. These pages can include: SET statements
  434.                          KEY statements
  435.  
  436. DEMOSYS.REF                   Last revised 03/13/93                     Page 11
  437.  
  438. *******************
  439.  
  440. - @label [ description ]
  441.  
  442. Establishes a page with no associated screen file.  Is typically used for
  443. prompt or action-only screens, setting up buffers, etc.
  444.  
  445. Labels are truncated at 12 characters including the "@" character.
  446.  
  447. Note that the function %PageName% returns the label ("@label") and %PageDesc%
  448. returns the page description for this page.
  449.  
  450. The first screen displayed has to be a display screen, not a label screen.
  451.  
  452. These pages can include: SET statements
  453.                          Action commands
  454.  
  455. *******************
  456.  
  457. /.
  458. ...
  459. ./
  460.  
  461. Defines the screen text for any page with imbedded screen text.  The "./"
  462. statement must appear by itself on the control line; comments are not allowed.
  463.  
  464. DEMOSYS.REF                   Last revised 03/13/93                     Page 12
  465.  
  466. --------------------------------------------------------------------------------
  467.  
  468.                               Statement Reference
  469.  
  470. Statements can basically appear anywhere within the control file.
  471.  
  472. *******************
  473.  
  474. + filename
  475.  
  476. Says to pick up more control statements from another file.  Can include drive
  477. and path information if desired.
  478.  
  479. *******************
  480.  
  481. Comments
  482.  
  483. The DEMO System ignores any blank lines as well as any lines that begin with the
  484. following characters:
  485.  
  486.         : (colon)
  487.         ; (semi-colon)
  488.         ' (single quote)
  489.         /* (slash-asterisk)
  490.  
  491. Comments can also be included on lines after regular commands; precede the
  492. comment with "/*" as in:
  493.  
  494.         KEY (ESC) GOTO SCRN.001   /* Takes the user to the main menu
  495.  
  496. The use of comments is always recommended.
  497.  
  498. *******************
  499.  
  500. DATADIR [ subdirectory ]
  501.  
  502. Specifies the subdirectory location of all file references that follow.  This
  503. statement can appear anywhere including within page screen definitions (but not
  504. within the text of the screen).  The DATADIR setting remains in effect until
  505. another DATADIR setting is encountered.
  506.  
  507. If subdirectory is not provided, files will be looked for in your default
  508. subdirectory.
  509.  
  510. You can always hard-code the paths in all of your file references but it's
  511. easier to use the DATADIR command.
  512.  
  513. DEMOSYS.REF                   Last revised 03/13/93                     Page 13
  514.  
  515. *******************
  516.  
  517. DO name [ parms ]
  518. DO (DUMMY) [ parms ]
  519.  
  520. Executes a previously-defined Macro statement.
  521.  
  522. Up to 9 words can be passed in and these will be substituted in for any
  523. references to &1 to &9 during compilation.  (If 10 or more words are provided,
  524. the extra words are all stuck in &0.) These variables remain set until another
  525. DO statement is encountered.
  526.  
  527. DO (DUMMY) is used to clear or reset Macro variables.  No action other than the
  528. variable clearing goes on with this Macro statement.  You can, therefore, have
  529. &1 to &9 (and &0) defined even without having any associated MACRO statement.
  530.  
  531. *******************
  532.  
  533. MACRO name [ REUSE | SKIP ]
  534. ...
  535. MEND
  536.  
  537. Defines a Macro.  This code can include any statement other than another Macro
  538. definition.  The Macro block must end with a MEND statement, which must appear
  539. by itself on a control line.  (The MEND statement can include comments though.)
  540.  
  541. Macro names must be unique unless "REUSE" or "SKIP" is specified.  If the
  542. definition already exists and "REUSE" is specified, the new definition will
  543. replace the old.  If the definition already exists and "SKIP" is specified, the
  544. new definition will be ignored (although it does show up in the count of
  545. macros).
  546.  
  547. The Macro is actually invoked with a DO command.
  548.  
  549. DEMOSYS.REF                   Last revised 03/13/93                     Page 14
  550.  
  551. --------------------------------------------------------------------------------
  552.  
  553.                                  SET Statements
  554.  
  555. Each SET statement is defined once per display screen.  (One exception:  SET
  556. KEYS SETn and SET SETTINGS (SETn) can occur multiple times.)  If the same SET
  557. statement appears more than once in a given page, the latter definition always
  558. wins.  Keep this in mind; you can't have the program be case-sensitive for some
  559. keys and case-insensitive for others on the same screen.
  560.  
  561. *******************
  562.  
  563. SET BASE n
  564.  
  565. Sets the default color (^Cn) to be used for a given screen.  "n" has to be
  566. a color set number (0 to 7).
  567.  
  568. The default setting is SET BASE 0.
  569.  
  570. *******************
  571.  
  572. SET CASE ON
  573. SET CASE OFF
  574.  
  575. Determines whether the case of the user's input matters when processing a KEY
  576. statement.  If SET CASE ON is in effect, "g" will be treated differently than
  577. "G".
  578.  
  579. The default setting is SET CASE OFF.
  580.  
  581. *******************
  582.  
  583. SET CLS ON
  584. SET CLS OFF
  585.  
  586. Determines whether the screen is automatically cleared when a new text screen
  587. (confined to "- filename" and "- *ref" statements) is loaded.
  588.  
  589. The default setting is SET CLS ON.
  590.  
  591. DEMOSYS.REF                   Last revised 03/13/93                     Page 15
  592.  
  593. *******************
  594.  
  595. SET COLOR settings
  596.  
  597. Allows you to define up to 8 color "sets" (numbered ^C0 to ^C7) which you can
  598. use in most displayed text.  Each color set consists of 1 to 8 three-digit
  599. numbers.  The first three-digit number defines ^C0, the eighth defines ^C7.
  600.  
  601. Each three digit number consists of two digits for a foreground color and one
  602. digit for the background color.  The foreground color must be zero-filled if
  603. it's only one digit in length (use "07" instead of "7").
  604.  
  605. Foreground colors:
  606.  
  607.         Low intensity           High intensity
  608.  
  609.         0 = black                8 = dark grey
  610.         1 = blue                 9 = light blue
  611.         2 = green               10 = light green
  612.         3 = cyan                11 = light cyan
  613.         4 = red                 12 = light red
  614.         5 = magenta             13 = light magenta
  615.         6 = brown               14 = light yellow
  616.         7 = white               15 = bright white
  617.  
  618. Adding 16 to any color will make the text blink.
  619.  
  620. Background colors can consist of 0 to 7 above.
  621.  
  622. Bright white on blue, for example, would be "151".
  623.  
  624. The default setting is SET COLOR 151 154 152 117 097 153 001 157
  625.  
  626. All screen text lines are defined to use color set 0 unless a different "SET
  627. BASE n" is specified.  You can imbed color control codes anywhere in your text
  628. to get around this.  The SET COLOR settings automatically come up by default
  629. unless /M is passed into the viewer.  You can switch to the monochrome settings
  630. within your program by issuing the command "DISPLAY MONO" or "DISPLAY TOGGLE".
  631.  
  632. Other than the text screen lines, most text uses the color of the last string
  633. printed as the default color.
  634.  
  635. *******************
  636.  
  637. SET CURSOR string
  638.  
  639. This establishes the shape and color of the screen's cursor.  This is typically
  640. applicable only for full-screen operations.
  641.  
  642. The cursor definition string can include ^ controls.  For example:
  643.  
  644.         SET CURSOR ^C2(^T10^
  645.  
  646. The default setting is SET CURSOR _
  647.  
  648. DEMOSYS.REF                   Last revised 03/13/93                     Page 16
  649.  
  650. *******************
  651.  
  652. SET KEYS CLEAR
  653.  
  654. Clears any key definitions inherited from the (GLOBAL) level.
  655.  
  656. *******************
  657.  
  658. SET KEYS (SETn)
  659.  
  660. Grabs all KEY settings in (SETn) and uses them for this screen.  (SETn) has to
  661. be previously defined.
  662.  
  663. The settings are added in place, leaving KEY statements before and after as they
  664. were.  If the (SETn) KEY setting is already defined before the SET KEYS (SETn)
  665. statement is encountered, the first definition wins.  Similarly, KEY statements
  666. which appear after a SET KEYS (SETn) statement lose precedence over the
  667. definitions in SET KEYS (SETn).
  668.  
  669. See also the SET SETTINGS (SETn) command which grabs all SET settings in (SETn).
  670.  
  671. *******************
  672.  
  673. SET LOGO string
  674.  
  675. Establishes a logo or byline that appears somewhere on the screen.  This is
  676. typically used to identify the fact that the person is running a demo, not the
  677. real product.  The logo prints over any text that is already on the screen.
  678.  
  679. The logo string can include ^ controls.  This allows you to have the logo
  680. appearing on multiple logo lines on your screen although only one SET LOGO is
  681. accepted.  For example:
  682.  
  683.         SET LOGO ^C1^P1,35This is a logo^P25,30appearing on top and bottom
  684.  
  685. *******************
  686.  
  687. SET MONO settings
  688.  
  689. Defines the monochrome (or alternate) screen colors.  See the description of
  690. colors in the SET COLOR command description.
  691.  
  692. In actuality, COLOR and MONO just refers to a primary and secondary set of
  693. screen colors.  You could define MONO to be color as well.
  694.  
  695. The default setting is SET MONO  150 070 007 157 150 070 007 157
  696.  
  697. DEMOSYS.REF                   Last revised 03/13/93                     Page 17
  698.  
  699. *******************
  700.  
  701. SET MOUSE ON
  702. SET MOUSE OFF
  703.  
  704. Allows the mouse cursor to show up.  Usually used in conjunction with a SELECT
  705. action command:
  706.  
  707.         SET MOUSE ON
  708.         KEY (MOUSER) SELECT
  709.  
  710. Defaults to SET MOUSE OFF.  Is automatically deactivated if there are no
  711. keyboard input fields defined on the screen or if the screen is a data-entry
  712. form (using @ commands).
  713.  
  714. *******************
  715.  
  716. SET SETTINGS CLEAR
  717.  
  718. Resets most SET commands to their system initial values.  These are:
  719.  
  720.         SET BASE 0
  721.         SET CASE OFF
  722.         SET CLS ON
  723.         SET COLOR 151 154 152 117 097 153 001 157
  724.         SET CURSOR _
  725.         SET LOGO
  726.         SET MONO  150 070 007 157 150 070 007 157
  727.         SET MOUSE OFF
  728.  
  729. *******************
  730.  
  731. SET SETTINGS (SETn)
  732.  
  733. Grabs all SET settings in (SETn) and uses them for this screen.  (SETn) has to
  734. be previously defined.
  735.  
  736. The settings are added in place, leaving SET statements before and after as they
  737. were.  If the (SETn) SET setting is already defined before the SET SETTINGS
  738. (SETn) statement is encountered, the first definition wins.  Similarly, SET
  739. statements which appear after a SET SETTINGS (SETn) statement lose precedence
  740. over the definitions in SET SETTINGS (SETn).
  741.  
  742. See also the SET KEYS (SETn) command which grabs all KEY settings in (SETn).
  743.  
  744. *******************
  745.  
  746. SET TOP screen
  747.  
  748. Determines which screen the system will bring up if a "POP TOP" statement is
  749. executed.  Is also the screen that's brought up if a POP statement tries to POP
  750. further back than the CALL stack provides.
  751.  
  752. Defaults to the first real text screen in your control file.
  753.  
  754. DEMOSYS.REF                   Last revised 03/13/93                     Page 18
  755.  
  756. --------------------------------------------------------------------------------
  757.  
  758.                                 Action commands
  759.  
  760. ASSIGN ^Uvar^ [ = string ]
  761.  
  762. Assigns a value to a user-defined variable.  The use of the equal sign is
  763. optional.
  764.  
  765. The assignment string can include user-defined variables, environmental
  766. variables, or functions.
  767.  
  768. If the assignment string is left off, the value of ^Uvar^ will be null.
  769.  
  770. *******************
  771.  
  772. BEEP
  773.  
  774. Beeps.  You can be more creative using PLAY commands though.  BEEP is useful if
  775. you want to alert people to invalid keystrokes:
  776.  
  777.         KEY (ELSE) BEEP
  778.  
  779. *******************
  780.  
  781. BUFFER [ chars ]
  782.  
  783. Buffers one or more characters.  These characters are then read in when The DEMO
  784. System encounters any keypress situation.
  785.  
  786. Leaving off the parameter results in the buffer being immediately cleared.
  787.  
  788. One of the characters can be (LASTKEY) which is the value of the last key
  789. pressed.  Passing this then clears the value of (LASTKEY).  This is typically
  790. used for screens that you want any keypress to advance to the next screen but
  791. you still want to use the keypress for some later movement.
  792.  
  793. Buffering is affected by these commands:
  794.         PAUSE BREAK ON
  795.         PAUSE BREAK OFF
  796.         PAUSE DELAY seconds
  797.  
  798. DEMOSYS.REF                   Last revised 03/13/93                     Page 19
  799.  
  800. *******************
  801.  
  802. CALL screen [ KEYn | parms ]
  803.  
  804. Passes control to another screen (or label) with the intention of having a POP
  805. command later on returning control to the current screen.
  806.  
  807. The KEYn parameter says to position the cursor at input key "n" when the next
  808. screen in loaded.
  809.  
  810. The optional parameters allow you to pass up to 9 values into the next screen.
  811. These values are stored separately as functions %1% to %9% unless you pass the
  812. parameters in with quotes.  For example:
  813.  
  814.         CALL @TEST1 Internet lives!    /* %1%=Internet, %2%=lives, others blank
  815.         CALL @TEST2 "Internet lives!"  /* %1%=Internet lives!, others blanks
  816.  
  817. These function remain set until the next CALL, GOTO, or SCREEN statement is
  818. encountered which also passes parameters.
  819.  
  820. The parms can include control items, user-defined variables, environmental
  821. variables, and functions.
  822.  
  823. See also the GOTO and SCREEN commands.
  824.  
  825. *******************
  826.  
  827. CD directory
  828.  
  829. Changes the default subdirectory.  If that directory does not exist, an error
  830. message will be displayed but the program will continue on.
  831.  
  832. If the subdirectory includes drive information, the default subdirectory on
  833. *that* drive, not the default drive, will be changed.
  834.  
  835. The directory can be a user-defined variable or a function.
  836.  
  837. See also the CDD, DRIVE, MD, and RD commands.
  838.  
  839. See also the %PathExist% function.
  840.  
  841. *******************
  842.  
  843. CDD drive:directory
  844.  
  845. Changes the default drive and subdirectory.  (Essentially the same thing as
  846. issue a DRIVE command, followed by a CD command.) If that directory does not
  847. exist, an error message will be displayed but the program will continue on.
  848.  
  849. The drive:directory can be a user-defined variable or a function.
  850.  
  851. See also the CD, DRIVE, MD, and RD commands.
  852.  
  853. See also the %DriveDirOrig% and %Dir% functions.
  854.  
  855. DEMOSYS.REF                   Last revised 03/13/93                     Page 20
  856.  
  857. *******************
  858.  
  859. CLS
  860.  
  861. Clears the primary screen.
  862.  
  863. *******************
  864.  
  865. CLSA
  866.  
  867. Clears the alternate screen.
  868.  
  869. *******************
  870.  
  871. COPY file1 file2
  872.  
  873. Copies one file (file1) under another file (file2).  The destination file is
  874. replaced if it exists already.  Either filename can include drive and path
  875. information.
  876.  
  877. Either file name can be a user-defined variable or a function.
  878.  
  879. See also the %FileExist% function.
  880.  
  881. *******************
  882.  
  883. DATA ...
  884.  
  885. Statement which, so far, is only used with the LOADLOGO command.
  886.  
  887. *******************
  888.  
  889. DELETE filename
  890.  
  891. Deletes a file.  The filename can include drive and path information.  The
  892. command is ignored if the file doesn't exist.
  893.  
  894. The file name can be a user-defined variable or a function.
  895.  
  896. See also the %FileExist% function.
  897.  
  898. DEMOSYS.REF                   Last revised 03/13/93                     Page 21
  899.  
  900. *******************
  901.  
  902. DISPLAY COLOR
  903. DISPLAY MONO
  904. DISPLAY TOGGLE
  905.  
  906. Sets the default color setting to either the SET COLOR set or the SET MONO (or
  907. alternate) set.  DISPLAY TOGGLE toggles between the two (COLOR becomes MONO and
  908. vice versa).  This is frequently used in a key definition:
  909.  
  910.         KEY (A-M) DISPLAY MONO
  911.         KEY (A-C) DISPLAY COLOR
  912.  
  913. Note that the color changes do not take effect until the screen is redraw.  You
  914. may want to handle display toggling in a label since that will redraw the
  915. screen automatically when done.
  916.  
  917. See also the %Display% and %DisplayNum% functions.
  918.  
  919. *******************
  920.  
  921. DRIVE letter
  922.  
  923. Sets the default drive as "letter".  The drive designation *cannot* be an
  924. environmental variable.
  925.  
  926. See also the CD, CDD, MD, and RD commands.
  927.  
  928. See also the %Dir% functions.
  929.  
  930. *******************
  931.  
  932. DROP location
  933.  
  934. Establishes a label to which you can later HOP to.  The location is a single
  935. word (it cannot contain spaces), is not case-sensitive ("DROP Wayne" is the same
  936. as "DROP WAYNE") and is truncated to 8 characters.
  937.  
  938. See also the HOP and IF commands.
  939.  
  940. DEMOSYS.REF                   Last revised 03/13/93                     Page 22
  941.  
  942. *******************
  943.  
  944. ECHO [ string[@] ]
  945.  
  946. Prints a string to the primary screen.  The string can include environmental
  947. variables, user-defined variables, functions, and control codes.
  948.  
  949. If a "@" immediately follows the string, The DEMO System will not do a carriage
  950. return/line feed after the string.
  951.  
  952. Note that it's possible to cause a system failure by specifying a string that
  953. will not fit within the designated line.  Exercise some judgment when putting
  954. long strings on the right side of the screen.
  955.  
  956. *******************
  957.  
  958. ECHOA [ string[@] ]
  959.  
  960. Prints a string to the alternate screen.  See the ECHO action command for
  961. further details.
  962.  
  963. *******************
  964.  
  965. FIELD [ TOP | FIRST | -999 to 999 | BOTTOM | LAST | @1 to @99 ]
  966.  
  967. Moves the cursor to a different input field on the current screen.  Using -999
  968. to 999, you can specify the field position relative to the current field (-2
  969. takes the cursor back two fields).
  970.  
  971. Absolute fields can be specified using TOP (or FIRST) and BOTTOM (or LAST) or by
  972. specifying @1 to @99.
  973.  
  974. This command is typically used when designing full-screen systems.  For example:
  975.  
  976.         KEY (RIGHT) FIELD 1
  977.         KEY (LEFT) FIELD -1
  978.         KEY (HOME) FIELD TOP
  979.         KEY (END) FIELD BOTTOM
  980.  
  981. The command is ignored if you have less than two input fields on a given screen.
  982.  
  983. See also the %FieldNum% and %FieldMax% functions.
  984.  
  985. DEMOSYS.REF                   Last revised 03/13/93                     Page 23
  986.  
  987. *******************
  988.  
  989. GOTO screen [ KEYn | CLEAR | parms ]
  990.  
  991. Passes control to another screen (or label) with the intention of *not*
  992. returning control to the current screen.
  993.  
  994. The KEYn parameter says to position the cursor at input key "n" when the next
  995. screen in loaded.
  996.  
  997. The CLEAR parameter says to clear the CALL return stack when the jump is made.
  998.  
  999. The optional parameters allow you to pass up to 9 values into the next screen.
  1000. These values are stored separately as functions %1% to %9% unless you pass the
  1001. parameters in with quotes.  For example:
  1002.  
  1003.         GOTO @TEST1 Internet lives!    /* %1%=Internet, %2%=lives, others blank
  1004.         GOTO @TEST2 "Internet lives!"  /* %1%=Internet lives!, others blanks
  1005.  
  1006. These keys remain set until the next CALL, GOTO, or SCREEN statement is
  1007. encountered which also passes parameters.
  1008.  
  1009. Note that a GOTO statement on its own (outside a KEY statement) will result in
  1010. the current screen being closed and must be followed by a new page declaration
  1011. or else the end of the file.
  1012.  
  1013. The parms can include control items, functions, user-defined variables, and
  1014. environmental variables.
  1015.  
  1016. See also the CALL and SCREEN commands.
  1017.  
  1018. DEMOSYS.REF                   Last revised 03/13/93                     Page 24
  1019.  
  1020. *******************
  1021.  
  1022. HOP location
  1023.  
  1024. The HOP command transfers you to the location of a DROP command elsewhere in the
  1025. page.  In this format, the HOP is unconditional; it will happen no matter what.
  1026. It also also non-returnable; the location from which you hopped from is not
  1027. stored so the program will not return you to it.  You can of course set up some
  1028. additional DROP and HOP commands to take care of that.
  1029.  
  1030. Care should be take to avoid leaving yourself in an endless loop condition.
  1031. There is no way to get out of these without rebooting your machine.
  1032.  
  1033. An example of using HOP in combination with the IF command follows:
  1034.  
  1035.         - @Demo_Loop Demonstration of HOP/DROP/IF etc
  1036.         ; This could have been done using a form too.  It wouldn't have
  1037.         ; worked as smoothly using regular text pages because the page
  1038.         ; commands would be executed *before* the user picked their selection.
  1039.         DROP Start
  1040.         ECHO We have three tunes that we can play for you:
  1041.         ECHO    1. Beethoven's Fifth Symphony (abbreviated version!)
  1042.         ECHO    2. Meaningless drivel 1
  1043.         ECHO    3. Meaningless drivel 2
  1044.         ECHO    Q. Quit this stuff
  1045.         ECHO Select one:
  1046.         PROMPT ^UPlay^ "!" DEF=1 TEST=%Instr%(123Q,^UPlay^) > 0
  1047.         IF ^UPlay^ = 1 THEN HOP Song1
  1048.         IF ^UPlay^ = 2 THEN HOP Song2
  1049.         IF ^UPlay^ = 3 THEN HOP Song3
  1050.         ECHO Yeah, I'm kind of tired of them too.
  1051.         HOP Done
  1052.         DROP Song1
  1053.         ECHO You picked the only good one!
  1054.         PLAY mb t180 o2 p2 p8 l8 ggg l2 e- p24 p8 l8 fff l2 d
  1055.         HOP Start
  1056.         DROP Song2
  1057.         PLAY mb l8 n42 n45 n41 n40 n51 n59 n68 n70 n73 n30
  1058.         ECHO Chear up.  Drivel 2 was worse.
  1059.         HOP Start
  1060.         DROP Song3
  1061.         PLAY mb l16 n50 n51 n50 n51 n50 n52 n54 n55 n52 n51 n50 n48 l2 d
  1062.         HOP Start
  1063.         DROP Done
  1064.         QUIT
  1065.  
  1066. See also the DROP and IF commands.
  1067.  
  1068. DEMOSYS.REF                   Last revised 03/13/93                     Page 25
  1069.  
  1070. *******************
  1071.  
  1072. IF cond1 rel cond2 THEN HOP location
  1073.  
  1074. The IF command provides a way for doing conditional looping in a program.  The
  1075. command can be used to hop to another statement in the existing page.  The
  1076. command's scope is limited to a single page.
  1077.  
  1078. The "cond1 rel cond2" portion of the command is the same as the TEST= parameter
  1079. in the PROMPT command.  See that for an explanation of these parameters.
  1080.  
  1081. The "HOP location" portion of the command tells it to HOP to the designated DROP
  1082. location if the condition is true.  That DROP location can be before any
  1083. command, including a CALL or GOTO statement so you can go to another screen.
  1084.  
  1085. The IF command has many uses.  The following example shows it being used to loop
  1086. through a section of code 10 times:
  1087.  
  1088.         - @Test
  1089.         ECHO This statement should loop 10 times
  1090.         ASSIGN ^UVal^ = 1
  1091.         DROP ReLoop
  1092.         ECHO Current value ^UVal^
  1093.         ASSIGN ^UVal^ = %ADD%(^UVal^,1)
  1094.         IF ^UVal^ <= 10 THEN HOP ReLoop
  1095.         QUIT
  1096.  
  1097. Care should be take to avoid leaving yourself in an endless loop condition.
  1098. There is no way to get out of these without rebooting your machine.
  1099.  
  1100. See also the DROP, HOP, and PROMPT commands.
  1101.  
  1102. *******************
  1103.  
  1104. KEYPRESS
  1105.  
  1106. Pauses and waits for a user input.  KEYPRESS is automatically executed for a
  1107. screen with an associated text page.
  1108.  
  1109. Note that a KEYPRESS statement on its own (outside a KEY statement) will result
  1110. in the current screen being closed and must be followed by a new page
  1111. declaration or else the end of the file.
  1112.  
  1113. Example:
  1114.         - @TESTING
  1115.         KEY (UP) ECHO Pressed UP
  1116.         KEY (DOWN) ECHO Pressed DOWN
  1117.         KEY (ESC) QUIT
  1118.         ECHO Press either UP or DOWN or ESC
  1119.         KEYPRESS
  1120.  
  1121. (Remember that action commands are always executed before KEY statements so the
  1122. ECHO will show up, then the KEYPRESS will be acted upon, and the result will
  1123. be used by the KEY statements.)
  1124.  
  1125. DEMOSYS.REF                   Last revised 03/13/93                     Page 26
  1126.  
  1127. *******************
  1128.  
  1129. LOADLOGO ^Uvar^ char_count
  1130. DATA ...
  1131. DATA ...
  1132.  
  1133. A technique for loading graphics characters over the VGA character set so you
  1134. can make things like logos or special boxes while within the text environment.
  1135. The technique itself has been explained in several technical articles and
  1136. involves the use of interrupts and such.  It will not be explained here other
  1137. than the explain the format used within this program.
  1138.  
  1139. The ^Uvar^ parameter is the user-defined variable that will be assigned the
  1140. characters that constitute the redefined characters.  If you want to define
  1141. several logos, each of which can consist of one or more characters together, you
  1142. would need to use several LOADLOGO statements.  Once the logo has been loaded,
  1143. you can use the ^Uvar^ in ECHO, SET LOGO, etc statements.
  1144.  
  1145. The char_count indicates how many characters put together constitute this logo.
  1146. There has to be one DATA line for every character.
  1147.  
  1148. The DATA statements consist of 17 values.  The first value is the ASCII value
  1149. that the character will replace (e.g. 211 for CHR$(211)).  The next values are
  1150. the decimal representation for each line of pixels.  VGA fonts are 16 pixels
  1151. high so there are 16 values after the decimal representation.
  1152.  
  1153. The DATA statements must immediately follow the LOADLOAD statement.  Blank
  1154. lines and comments are not allowed.
  1155.  
  1156. The following example defines a bat silhouette as ASCII characters 221, 222, and
  1157. 224.
  1158.  
  1159.         LOADLOGO ^UBatSymbol^ 3
  1160.         DATA 221,0,24,28,60,62,63,127,127,127,255,255,255,239,206,132,128
  1161.         DATA 222,66,126,126,126,126,255,255,255,255,255,255,255,255,126,60,24
  1162.         DATA 224,0,24,56,60,124,252,254,254,254,255,255,255,247,115,33,1
  1163.  
  1164. LOADLOGO is ignored if the user does not have a VGA card.  In that case, the
  1165. environmental variable will be set to null.
  1166.  
  1167. You typically will not want to define the logo multiple times in one program.
  1168. Doing so causes the screen to flicker.  It's usually best to use the (ONCE)
  1169. screen definition to load the logo when The DEMO System viewer is loaded and
  1170. then not do it again.
  1171.  
  1172. Some applications (like PC Tools and the Norton Utilities) may redefine the
  1173. character set on their own.  In this case, the environmental variable will still
  1174. be set but it will display weird characters instead of what you want.  Notice
  1175. which programs do this and isolate the RUN commands that are affected.  If you
  1176. have a command like SET LOGO which uses the logo, you will want to either
  1177. re-load the logo again (using the LOADLOGO command) or redefine the
  1178. environmental variable to be null.
  1179.  
  1180. See also the %DisplayVGA% function.
  1181.  
  1182. DEMOSYS.REF                   Last revised 03/13/93                     Page 27
  1183.  
  1184. *******************
  1185.  
  1186. LOADLOGO CLEAR
  1187.  
  1188. This command clears any VGA character redefinitions that you've made.  This
  1189. insures that the user's DOS session won't have weird little graphics characters
  1190. showing up at odd times.
  1191.  
  1192. If the characters actually remain on the screen after LOADLOGO CLEAR is issued,
  1193. you will probably want to issue a CLS command to clear the screen.
  1194.  
  1195. LOADLOGO CLEAR does not affect the contents of the environmental variable you
  1196. defined in the LOADLOGO command.  If you print that string after using LOADLOGO
  1197. CLEAR, that string will show up as the original DOS characters, not the
  1198. redefined ones.  You may want to assign it to null if you want to continue on.
  1199.  
  1200. The LOADLOGO CLEAR statement is ignored if the user does not have a VGA card or
  1201. if they didn't set any symbols in the first place.
  1202.  
  1203. *******************
  1204.  
  1205. LOCATE row col
  1206.  
  1207. Positions the cursor at a given row and column on the screen.  Positioning on
  1208. the screen starts with the upper left corner being 1, 1 and the lower right
  1209. corner being 25, 80.
  1210.  
  1211. Optionally, you can use a comma between the positions.
  1212.  
  1213. You can use the ^Prow,col control codes to position most text instead of using
  1214. the LOCATE command.
  1215.  
  1216. *******************
  1217.  
  1218. MD directory
  1219.  
  1220. Makes a new subdirectory.  If that subdirectory cannot be created, an error
  1221. message will be displayed but the program will continue on.
  1222.  
  1223. The directory can be a environmental variable, user-defined variable, or
  1224. function and it can include drive information if desired.
  1225.  
  1226. See also the CD, CDD, DRIVE, and RD commands.
  1227.  
  1228. See also the %PathCanMake% function.
  1229.  
  1230. DEMOSYS.REF                   Last revised 03/13/93                     Page 28
  1231.  
  1232. *******************
  1233.  
  1234. MSGBOX type message
  1235.  
  1236. Displays a message box on the screen, pausing until the user presses a key.
  1237. The message can be purely informational or it can present warnings or force the
  1238. user to stop.  The "type" code determines the display and the options available
  1239. to the user:
  1240.  
  1241.         0 = informational message only, using color set 1, with only option
  1242.             being to contiue
  1243.         1 = warning message, using color set 2, with only option being to
  1244.             continue
  1245.         2 = warning message, using color set 2, with option of continuing or
  1246.             quitting
  1247.         3 = fatal message, using color set 2, with only option being to quit
  1248.  
  1249. The "message" can be any one line of text.  Any message longer than 75
  1250. characters will be truncated to the first 75 characters.  Do not put quotes
  1251. around the text.
  1252.  
  1253. If the user gets a type 2 message and asks to quit, The DEMO System will set the
  1254. DOS return code to be 254.  If the user gets a type 3 message, The DEMO System
  1255. will set the DOS return code to be 255.
  1256.  
  1257. *******************
  1258.  
  1259. MSGBOXA type message
  1260.  
  1261. Identical to the MSGBOX command except output goes to the alternate screen
  1262. instead of the primary screen.
  1263.  
  1264. DEMOSYS.REF                   Last revised 03/13/93                     Page 29
  1265.  
  1266. *******************
  1267.  
  1268. NONE
  1269.  
  1270. This is a special null-operation command which is typically only used in
  1271. KEY statements.  The purpose is to nullify a key assignment made by a (SETn) or
  1272. GLOBAL statement.
  1273.  
  1274. For (SETn) statements, the NONE assignment has to be made *before* the SET VARS
  1275. SETn statement.
  1276.  
  1277. Example:
  1278.  
  1279.         - (GLOBAL)
  1280.         KEY (UP) FIELD -5
  1281.         KEY (DOWN) FIELD 5
  1282.         ... (a half-dozen key assignments you like) ...
  1283.         - (SET1)
  1284.         KEY (LEFT) FIELD -1
  1285.         KEY (RIGHT) FIELD 1
  1286.         ... (a dozen key assignments you like) ...
  1287.         - *001 Testing
  1288.         KEY (UP) NONE      /* Note that these keys will do nothing now
  1289.         KEY (DOWN) NONE
  1290.         SET KEYS (SET1)
  1291.  
  1292. DEMOSYS.REF                   Last revised 03/13/93                     Page 30
  1293.  
  1294. *******************
  1295.  
  1296. PAUSE [ seconds ]
  1297.  
  1298. Waits for either the specified number of seconds or until the user presses any
  1299. key.  Seconds can be expressed in tenths and must be between 0.1 and 600.
  1300.  
  1301. The activity is done on the primary screen.
  1302.  
  1303. *******************
  1304.  
  1305. PAUSEA [ seconds ]
  1306.  
  1307. Same as "PAUSE [ seconds ]" but activity is done on the alternate screen.
  1308.  
  1309. *******************
  1310.  
  1311. PAUSE BREAK ON
  1312. PAUSE BREAK OFF
  1313.  
  1314. Determines whether someone can escape (using the Esc key) out of a self-running
  1315. demo.
  1316.  
  1317. Defaults to PAUSE BREAK ON (the user can escape out).
  1318.  
  1319. *******************
  1320.  
  1321. PAUSE DEMO seconds
  1322.  
  1323. Determines how many seconds the system should delay between buffered keystrokes
  1324. in a self-running demo.  The user can skip through the pause by pressing any
  1325. keyboard key (not mouse key).
  1326.  
  1327. Seconds can be expressed in tenths and must be between 0.1 and 600.
  1328.  
  1329. Defaults to PAUSE DEMO 1.
  1330.  
  1331. DEMOSYS.REF                   Last revised 03/13/93                     Page 31
  1332.  
  1333. *******************
  1334.  
  1335. PLAY string
  1336.  
  1337. The PLAY command plays a string of sounds using QuickBASIC's PLAY command.
  1338. There are lots of characters that can appear in the PLAY string.  The following
  1339. chart summarizes them but you should use a QuickBASIC manual for fuller
  1340. explanations if necessary.  (This information doesn't appear in the VisualBASIC
  1341. manual at all!)
  1342.  
  1343.         A to G          Plays note in range A to G: "#" after note implies
  1344.                         a sharp while "-" afterward implies a flat
  1345.         L n             Sets the default length of each note (from 1 [whole
  1346.                         note] to 64 [very short note]).  You can also specify
  1347.                         the length after each note itself, e.g. "A16".
  1348.         MN              Music normal.  Each note plays for 7/8's its time.
  1349.         ML              Music legato.  Each note plays for full period.
  1350.         MS              Music staccato.  Each note plays 3/4 of its time.
  1351.         P n             Specifies a pause of length 1 to 64.
  1352.         T n             Specifies tempo (number of L 4 quarter notes played
  1353.                         in one minute).  Range can be 32 to 255, default 120.
  1354.         MF              Music foreground.  The program waits until the notes
  1355.                         finish before going on.
  1356.         MB              Music background.  The notes start playing and the
  1357.                         user can continue to press keys while the music plays.
  1358.                         MB is the default in The DEMO System.
  1359.         .               A period after the note causes the note to play
  1360.                         3/2's of it's time.
  1361.         # or +          These characters after the note cause it to be sharped.
  1362.         -               A minus after the note causes it to be flatted.
  1363.         N n             Plays note "n".  "n" must be between 0 (a rest) and 84
  1364.                         (the highest note in the seventh octave).
  1365.  
  1366. The first few notes of Beethoven's Fifth Symphony is the following:
  1367.  
  1368.         PLAY mb t180 o2 p2 p8 l8 ggg l2 e- p24 p8 l8 fff l2 d
  1369.  
  1370. PLAY strings are played during compilation in order to check them for errors.
  1371. You can turn off this verification by using DEMOMAKE's /Q option or else by
  1372. pressing Q during compilation.  Note that failure to verify the PLAY strings at
  1373. some point may result in non-recoverable execution errors.
  1374.  
  1375. If your user wants to avoid the PLAY commands, they can call your self-viewing
  1376. file with the /Q option and that will turn off all PLAY and BEEP commands.
  1377.  
  1378. *******************
  1379.  
  1380. PLAY ON
  1381. PLAY OFF
  1382.  
  1383. The PLAY OFF command turns off any BEEP and PLAY commands within your
  1384. demonstration.  The PLAY ON command turns them back on.
  1385.  
  1386. PLAY ON is the default.
  1387.  
  1388. DEMOSYS.REF                   Last revised 03/13/93                     Page 32
  1389.  
  1390. *******************
  1391.  
  1392. POP [ TOP | 1 to 20 ] [ KEYn ]
  1393.  
  1394. Returns to the statement after a prior CALL statement.  Relative to GOTO
  1395. statements, POP commands make screen levels easier to keep track of and allows
  1396. you to designate some screens or sets of screens as being common to several
  1397. demonstrations.
  1398.  
  1399. You can instruct POP to return you to any of the last 20 screens that you made
  1400. CALL's from.  You can also instruct it to return to the screen defined as your
  1401. "top" screen (see SET TOP), whether that screen had used a CALL or not.  If no
  1402. level is specified, POP 1 is the default.
  1403.  
  1404. You can specify which keyboard input item the cursor should rest on by using the
  1405. KEYn parameter.  Otherwise, the program will automatically select the first item
  1406. on the screen.  For example:
  1407.  
  1408.         - *001 Central menu
  1409.         KEY (LEFT) FIELD -1
  1410.         KEY (RIGHT) FIELD 1
  1411.         KEY @1 CALL @002
  1412.         KEY @2 CALL @003
  1413.         KEY @3 CALL @004
  1414.         KEY (ESC) QUIT
  1415.         /.
  1416.           Select one:  ^K First field    ^K Second field   ^K Third field
  1417.           or (ESC) to quit
  1418.         ./
  1419.         - @002 First field
  1420.         ECHO ^P10,1^C1Made it to ^C4first^C1 field's choice
  1421.         ECHO Press a key
  1422.         PAUSE
  1423.         POP                  /* Returns to first field by default
  1424.         - @003 Second field
  1425.         ECHO ^P10,1^C2Made it to ^C4second^C2 field's choice
  1426.         ECHO Press a key
  1427.         PAUSE
  1428.         POP KEY2             /* Will return user to the "Second field" field
  1429.         - @004 Third field
  1430.         ECHO ^P10,1^C3Made it to ^C4third^C3 field's choice
  1431.         ECHO Press a key
  1432.         PAUSE
  1433.         POP KEY3             /* Will return user to the "Third field" field
  1434.  
  1435. Unlike with GOTO and CALL, you cannot pass a variable or function (like
  1436. KEY%Field%) into a POP command.
  1437.  
  1438. Doing a POP from the TOP level is the same thing as QUIT.
  1439.  
  1440. Note that a POP statement on its own (outside a KEY statement) will result in
  1441. the current screen being closed and must be followed by a new page declaration
  1442. or else the end of the file.
  1443.  
  1444. DEMOSYS.REF                   Last revised 03/13/93                     Page 33
  1445.  
  1446. *******************
  1447.  
  1448. PROMPT ^Uvar^ "pattern" [ LEN=n ] [ RANGE=n-n ] [ DEF=s ]
  1449.   [ TEST=cond [rel cond] ] [ QUIT=key ] [ VQUIT=key ] [ HELP=key ]
  1450.   [ COLOR=n ] [ REQ ] [ NOESCAPE ] [ QUIET | -QUIET ]
  1451.  
  1452. The PROMPT command allows you to ask the user for a response.  This response is
  1453. put into a user-defined variable which can then be displayed, written to a file,
  1454. etc.  The prompt itself appears on the primary screen (see the PROMPTA command).
  1455.  
  1456. The PROMPT command and the related form entry @ command consists of two required
  1457. parts and several optional parameters.  Each is documented separately below:
  1458.  
  1459. "^Uvar^" is a required parameter.  It provides the name of user-defined variable
  1460. that you want the user's response to be assigned to.  The choice of variable
  1461. names matters somewhat since any user error messages identify the field by the
  1462. variable name.
  1463.  
  1464. "pattern" is a required parameter.  It tells the system the number of and what
  1465. sort of characters the user can enter.  The pattern must be enclosed in quotes
  1466. and can consist of any combination of the following characters:
  1467.  
  1468.         A               alpha input (A-Z) (either upper or lower case)
  1469.         B               Boolean input (T/F/Y/N; translated to Y/N on output)
  1470.         N               numeric input (digits 0 to 9 only)
  1471.         U               uppercase alpha (A-Z) only (translated to uppercase
  1472.                         if provided in lowercase)
  1473.         X               any character (decimal 32 to 125) (no translation)
  1474.         !               uppercase any character (decimal 32 to 125) (translated
  1475.                         to uppercase if provided in lowercase)
  1476.         0 to 9          used to indicate a repetition factor for the pattern
  1477.                         that immediately follows the last contiguous digit;
  1478.                         10X is the same as XXXXXXXXXX
  1479.         else            any other characters in the pattern are left in the
  1480.                         result verbatim; quotation marks are not allowed
  1481.  
  1482. "LEN=n" is an optional parameter.  It tells the system that the user's response
  1483. must consist of at least a certain number of characters.  (The maximum number of
  1484. characters is always the length of the pattern.) If no LEN is specified, it
  1485. defaults to LEN=0.  The length is determined as the user input, including all
  1486. patterns, minus any trailing spaces.  The following example would have a length
  1487. of 10 even if the user didn't fill in anything because the "-" character is the
  1488. 10th character of the pattern:
  1489.  
  1490.         PROMPT ^UPhone^ "(999) 999-9999" LEN=14
  1491.  
  1492. The following PROMPT would require that the user's response be at least 3
  1493. characters.  If they keyed in none, one, or two characters, an error message
  1494. would appear (on the secondary screen) and they'd be reprompted for their input:
  1495.  
  1496.         PROMPT ^UName^ "9!" LEN=3
  1497.  
  1498. DEMOSYS.REF                   Last revised 03/13/93                     Page 34
  1499.  
  1500. "RANGE=n-n" is an optional parameter.  It is primarily used to numeric input,
  1501. requiring that the user's input be within a given minimum to maximum range.  If
  1502. the PROMPT pattern does not include an "N" (numeric) field, then the system
  1503. compares the range as strings; otherwise the results are converted to numeric
  1504. values and compared that way.  If no RANGE is specified, no range test is
  1505. applied.  Invalid range messages appear on the secondary screen and the user is
  1506. re-prompted.  The following PROMPT would require that the user enter a number
  1507. between 1 and 100:
  1508.  
  1509.         PROMPT ^UValue^ "NNN" RANGE=1-100
  1510.  
  1511. "DEF=s" is an optional parameter.  It specifies the default value for the user's
  1512. response; the value that will appear in the answer grid.  The assignment string
  1513. can include a function if you want (e.g.  "DEF=%Today%").  If no DEF is
  1514. specified, a null value will be the default.  For example, the following PROMPT
  1515. lets the user specify the drive that they want to copy a file to, defaulting to
  1516. drive C:
  1517.  
  1518.         PROMPT ^UDrive^ "U" DEF=C
  1519.  
  1520. "TEST=cond1 rel cond2" is an optional parameter.  It allows you to establish a
  1521. condition that the user's response must meet before you allow them to continue.
  1522. The TEST parameter is a powerful and simple way to have the system impose a
  1523. check on the values; you can always have your own control files impose other
  1524. checks using IF commands but that's somewhat tougher to do.  The TEST parameter
  1525. consists of one to three parts.  A typical usage might be as such:
  1526.  
  1527.         PROMPT ^UDrive^ "U" DEF=C TEST=%Drive%(^UDrive^) = 1
  1528.  
  1529. This example allows the user to enter a drive letter and then tests to see if
  1530. it's a valid drive or not.  The %Drive% function (documented in the Functions
  1531. discussion below) returns a "0" if the passed-in drive letter is invalid or "1"
  1532. if it's valid.  In the above example, if the drive does not exist (a "0" value
  1533. is returned), the system will beep and the user will be asked for the response
  1534. again.  Each TEST parameter must be separated by a space and the parameters
  1535. themselves cannot include spaces.  The "rel" (relation) parameter can consist of
  1536. any of the following one- and two-character symbols (whose meaning should be
  1537. obvious):
  1538.  
  1539.         =  <  >  <=  >=  <>
  1540.  
  1541. In addition, you can use these two-letter codes which mean the same thing:
  1542.  
  1543.         EQ LT GT LE GE NE
  1544.  
  1545. The second condition ("cond2") can be "(NULL)", which tests to see if the first
  1546. condition ("cond1") is missing or not.  For example, to force the user to put in
  1547. a valid (although not necessarily existing) file name, the PROMPT would be:
  1548.  
  1549.         PROMPT ^UFileName^ "25!" TEST=%FileValid%(^UFileName^) <> (NULL)
  1550.  
  1551. DEMOSYS.REF                   Last revised 03/13/93                     Page 35
  1552.  
  1553. If the user keys in a non-valid file name, the "cond1" parameter will be set to
  1554. null.  In this format, the TEST rejects any input that evaluates to a null
  1555. string so the system beeps and the user is asked for the input again.  Check
  1556. each function description to see what conditions will result in a null response;
  1557. most functions that return numeric values return a 0 or -1 if something's
  1558. invalid, most functions that return strings return a null.
  1559.  
  1560. The comparison is done based on either the numeric value of the parameters or
  1561. their ASCII value.  If either parameter can be clearly identified as being
  1562. non-numeric, the test will be done on an ASCII basis.  So "TEST=2 < 10" will be
  1563. true whereas "TEST=2A < 10A" will be false.
  1564.  
  1565. Any error message about a TEST= failure appears on the secondary screen even if
  1566. PROMPTA is being used.
  1567.  
  1568. Note that there can't be a space within any of the TEST parameters, there can't
  1569. be a space after TEST=, and there has to be a space between the three
  1570. parameters.
  1571.  
  1572. "QUIT=key" is an optional parameter.  It is typically only used in data-entry
  1573. form screens.  It indicates the single keypress that will get the user out of
  1574. this particular form.  The keypress is not case sensitive.  The default is
  1575. QUIT=(NONE) for every field in the form.  There has to be at least one QUIT= or
  1576. VQUIT= (see) specification in any form.  If the QUIT= key is entered, the value
  1577. of the variable will be the upper case value of the QUIT= key.  See the example
  1578. in the VQUIT=key discussion.
  1579.  
  1580. "VQUIT=key" (verify quit) is an optional parameter.  It is typically only used
  1581. in data-entry forms screens.  It indicates the single keypress that will get the
  1582. user out of this particular form, and, unlike with the QUIT=key parameter, will
  1583. actually verify each of the fields to make sure that all REQ, TEST=, LEN=, and
  1584. RANGE= conditions are met.  The keypress is not case sensitive.  The default is
  1585. VQUIT=(NONE) for every field in the form.  There has to be at least one QUIT=
  1586. (see) or VQUIT= specification in any form.  If the VQUIT= key is entered, the
  1587. value of the variable will be the upper case value of the VQUIT= key.
  1588.  
  1589. The following example shows a typical prompt using QUIT= and VQUIT=.  It is
  1590. coded for the @ command instead of PROMPT/PROMPTA:
  1591.  
  1592.         - *Submit? Ask them for a report number and then verify?
  1593.         @ ^UReport^ "NNN" RANGE=1-175
  1594.         @ ^UWidth^  "NNN" RANGE=40-132
  1595.         ' Someone could press Tab or Shift-Tab and skip either prompt.
  1596.         ' This is desirable if they don't want a report at all but not
  1597.         ' if they do.  So force verification if they say "Y".
  1598.         @ ^USubmit^ "!" QUIT=(ESC) VQUIT=Y
  1599.         /.
  1600.                         Select a report number:   ^K
  1601.                         Select the desired width: ^K
  1602.  
  1603.                         Correct (Y,N,Esc): ^K
  1604.         ./
  1605.  
  1606. DEMOSYS.REF                   Last revised 03/13/93                     Page 36
  1607.  
  1608. "HELP=key" is an optional parameter.  If the user presses the designated key,
  1609. the bottom line of the screen will show some information about what the user
  1610. response has to be.  It shows the following:
  1611.  
  1612.         * The pattern
  1613.         * The minimum length
  1614.         * The value range
  1615.         * The default value
  1616.         * Whether the field is marked REQ or not
  1617.         * Whether a TEST condition is imposed (but not what the condition is)
  1618.         * The QUIT= value for this field
  1619.         * The VQUIT= value for this field
  1620.  
  1621. You can define the "key" to be any standard The DEMO System key.  It defaults to
  1622. KEY=(A-F1).
  1623.  
  1624. "COLOR=n" is an optional parameter.  It specifies the color setting to use for
  1625. the user's input.  The "n" parameter corresponds to the normal "^Cn" control
  1626. statements and must be in the range of 0 to 7.  If no COLOR is provided, the
  1627. prompt defaults to COLOR=1.  To make a prompt is color set 2, you'd say this:
  1628.  
  1629.         PROMPT ^UDrive^ "U" DEF=C COLOR=2
  1630.  
  1631. "REQ" is an optional parameter.  It specifies that an answer must be provided
  1632. for this prompt if the cursor is in this field.  The answer can be provided by a
  1633. DEF=s specification or by a user input.  Typically, the user can just press
  1634. Enter at a prompt and, unless a DEF=s or LEN=n value is specified, the result
  1635. can be null.  The REQ parameter reprompts the user if the value is null.  Even
  1636. with the REQ attribute, it is possible for a user to skip a field entirely by
  1637. using Shift-Tab or Tab and going to a designated QUIT=key or VQUIT=key field.
  1638. However, if the VQUIT=key key is entered, the system will still force them to
  1639. fill in every "REQ"-designated field.
  1640.  
  1641. "NOESCAPE" specifies that (C-J) and (C-C), which are normally defined as being,
  1642. respectively, shell to DOS and quit to DOS, are not to be valid.  This prevents
  1643. the user from escaping out of this form except through successful filling in of
  1644. the field (in the case of the PROMPT and PROMPTA commands) or successful
  1645. execution of the QUIT= key (in the case of the @ command).
  1646.  
  1647. "QUIET" turns off the "Insr"/"Over" indicator at the bottom of the screen.  This
  1648. is the default for the PROMPT/PROMPTA command.
  1649.  
  1650. "-QUIET" turns on the "Insr"/"Over" indicator at the bottom of the screen.  This
  1651. is the default for the @ command.
  1652.  
  1653. You should use the ECHO command to generate any message that you want the user
  1654. to see before the prompt.  For example:
  1655.  
  1656.         ECHO ^C2Please enter your name? @
  1657.         PROMPT ^UName^ "U25X" LEN=5 COLOR=3 REQ
  1658.  
  1659. DEMOSYS.REF                   Last revised 03/13/93                     Page 37
  1660.  
  1661. During data entry, several special data-entry keys can be used.  In the
  1662. discussion below, "single pattern" refers to patterns which are made up of the
  1663. same pattern character like "X" or "XXXX" or "25X".  "XXX-XXX-XXX" is not a
  1664. single pattern character.  Typically, insert and delete only work in single
  1665. pattern fields and cursor movement keys skip over non-pattern characters (like
  1666. "-" in the example above).  The list of special data-entry keys:
  1667.  
  1668.         (ENTER), (TAB)  Ends data entry for this field.  If you're in a
  1669.                         data-entry form, moves the cursor to the start of
  1670.                         the next field.
  1671.         (S-TAB)         Ends data entry for this field.  If you're in a
  1672.                         data-entry form, moves the cursor to the start of
  1673.                         the previous field
  1674.         (INS)           Toggles insert mode.  Is only applicable for fields
  1675.                         that are made up of the same pattern character; you
  1676.                         can't insert into a pattern "XXX-XXX-XXX".  Unless
  1677.                         QUIET is in affect, the status line changes from "Over"
  1678.                         to "Insr" as you toggle this.
  1679.         (BS)            Deletes the character in the current position and then
  1680.                         moves back a character.
  1681.         (DEL)           Deletes the character in the current position without
  1682.                         moving the cursor.
  1683.         (LEFT)          Moves the cursor back one character.
  1684.         (RIGHT)         Moves the cursor forward one character.
  1685.         (C-C)           Quits to DOS unless NOESCAPE specified.
  1686.         (C-F1)          Displays the page file name on the bottom line.
  1687.         (C-J)           Jumps to DOS unless NOESCAPE specified.  Note that the
  1688.                         screen is not redrawn when you return from DOS so
  1689.                         navigating around a form may get complex.
  1690.         otherwise       Entered into the field.
  1691.  
  1692. For PROMPT and PROMPTA, the cursor does not do a carriage return/line feed after
  1693. a prompt.  If you want one, you have to add an ECHO command on your own.
  1694.  
  1695. Unless the QUIET option is in affect, the "Over" and "Insr" indicators appear in
  1696. line 25, beginning column position 75.  If you use PROMPT, PROMPTA, or the @
  1697. command, text located in that position will get overwritten.
  1698.  
  1699. See also the PROMPTA and @ commands.
  1700.  
  1701. *******************
  1702.  
  1703. PROMPTA ^Uvar^ "pattern" [ LEN=n ] [ RANGE=n-n ] [ DEF=s ] [ COLOR=n ]
  1704.   [ REQ ] [ HELP=key ] [ QUIT=key ] [ TEST = cond1 [ rel cond2 ] ] [ NOESCAPE ]
  1705.  
  1706. Identical to the PROMPT command except the prompt appears on the alternate
  1707. screen.  Note that invalid data user error messages also show up on the
  1708. alternate screen.
  1709.  
  1710. See also the PROMPT and @ commands.
  1711.  
  1712. DEMOSYS.REF                   Last revised 03/13/93                     Page 38
  1713.  
  1714. *******************
  1715.  
  1716. QUIT [ return_code ]
  1717.  
  1718. The command causes the program to stop and return to DOS.  Every control card
  1719. file should consist of at least one QUIT statement and, by default, (C-C) is
  1720. always defined to do this.
  1721.  
  1722. The use of the return code (which can be a variable or function) allows you
  1723. to use The DEMO System in sophisticated ways within a batch file.  For example,
  1724. let's say you have a menu system set up where some options will jump to DOS and
  1725. run a batch command and return to The DEMO System, while other options will not
  1726. return.  You could set up some options in The DEMO System to set the return code
  1727. as 1 (run an application defined in the batch file DOIT.BAT and then come back),
  1728. 2 (run DOIT.BAT but don't come back), and 3 (normal end; person wanted out of
  1729. the system).  If The DEMO System blows up (e.g.  you request a prompt that can't
  1730. possibly fit in the space allocated), The DEMO System itself will return an
  1731. errorlevel of 0.  Unfortunately, this is how it works in QuickBASIC and
  1732. VisualBASIC and I can't change that.  So the complete batch file might look like
  1733. this:
  1734.  
  1735.         :Restart
  1736.         MYDEMO           (or whatever you call your demonstration program)
  1737.         IF ERRORLEVEL 3 GOTO :Goodbye
  1738.         IF ERRORLEVEL 2 GOTO :NoReturn
  1739.         IF ERRORLEVEL 1 GOTO :Return
  1740.         ECHO Fatal error in The DEMO System
  1741.         ECHO Check your control cards!
  1742.         GOTO :Done
  1743.         :Return
  1744.         CALL DOIT.BAT
  1745.         GOTO :Restart
  1746.         :NoReturn
  1747.         DOIT.BAT         (since CALL not used, will execute the batch file
  1748.                           and then stop; no need for a GOTO afterward)
  1749.         :Goodbye
  1750.         ECHO All done!
  1751.         :Done
  1752.  
  1753. Having said all this, creating files and then testing for them with an IF EXIST
  1754. statement in your DOS batch file is probably easier.
  1755.  
  1756. DEMOSYS.REF                   Last revised 03/13/93                     Page 39
  1757.  
  1758. If you loaded any VGA text definitions (using the LOADLOGO command), you may
  1759. want to issue a LOADLOGO CLEAR command before quitting.
  1760.  
  1761. Upon exit, QUIT leaves the cursor wherever it was last placed.  You may want to
  1762. issue a LOCATE command (or an ECHO command with ^Prow,col specification) before
  1763. exiting.  This is typically done by adding a statement like this before QUIT:
  1764.  
  1765.         ECHO ^P23,1^C1Thank you for your interest in our product!
  1766.  
  1767. Note that a QUIT statement on its own (outside a KEY statement) will result in
  1768. the current screen being closed and must be followed by a new page declaration
  1769. or else the end of the file.
  1770.  
  1771. See also the MSGBOX and MSGBOXA action commands.
  1772.  
  1773. *******************
  1774.  
  1775. RD directory
  1776.  
  1777. Removes a subdirectory.  If that directory does not exist or it cannot be
  1778. removed, an error message will be displayed but the program will continue on.
  1779.  
  1780. The directory can be an environmental variable, user-defined variable, or
  1781. function.  It can contain drive information if desired.
  1782.  
  1783. See also the CD, CDD, DRIVE, and MD commands.
  1784.  
  1785. See also the %PathExist% function.
  1786.  
  1787. DEMOSYS.REF                   Last revised 03/13/93                     Page 40
  1788.  
  1789. *******************
  1790.  
  1791. REDRAW
  1792.  
  1793. Redraws the current text screen without branching.  Redrawing is frequently
  1794. necessary if you want to recover from the output of a RUN command.  The
  1795. branching consideration means that, unlike with SCREEN 0 (another way to
  1796. accomplish the screen redrawing desire), control will continue with the
  1797. statement after REDRAW, instead of re-starting at the first statement of the
  1798. screen.
  1799.  
  1800. Note that REDRAW affects only screens with attached text screens.  It doesn't do
  1801. much good for label pages.
  1802.  
  1803. An example:
  1804.  
  1805.         - *002 Sample
  1806.         KEY A GOTO *003
  1807.         KEY (ESC) QUIT
  1808.         /.
  1809.           Press A or (ESC)
  1810.         ./
  1811.         - *003
  1812.         ECHO Testing and press ENTER
  1813.         PAUSE
  1814.         REDRAW      /* This redraws the screen text (the two lines
  1815.                     /* in the /.  ...  ./ section below)
  1816.         RUN DIR *.EXE /W
  1817.         ECHO Press ENTER
  1818.         PAUSE
  1819.         REDRAW
  1820.         RUNA DIR *.BAS /W   /* Doing output to the alternate page
  1821.         ECHOA Press ENTER
  1822.         PAUSEA
  1823.         ECHO Press ENTER again
  1824.         PAUSE
  1825.         /.
  1826.  
  1827.                 This is some additional text that keeps coming
  1828.                 up when REDRAW is used but the other stuff doesn't
  1829.         ./
  1830.  
  1831.         POP             /* Remember, this has to be *after* the /. ... ./
  1832. DEMOSYS.REF                   Last revised 03/13/93                     Page 41
  1833.  
  1834. *******************
  1835.  
  1836. RUN [ string ]
  1837.  
  1838. Shells to DOS and executes a command (given by "string") in the primary screen.
  1839.  
  1840. If the command is not specified, you will be shelled to DOS and left at the DOS
  1841. prompt.  Say "EXIT" and press ENTER to return to The DEMO System.
  1842.  
  1843. The string can be a regular DOS command, any command that's available in your
  1844. path, a command with drive and path information if necessary, or the name of a
  1845. batch file.  The latter is used if you want to execute multiple commands at
  1846. once.
  1847.  
  1848. RUN leaves a copy of The DEMO System in memory and requires loading COMMAND.COM.
  1849. Together, these take up roughly 130K of RAM space.  If the remaining space is
  1850. not sufficient to run your application, consider using The DEMO System as part
  1851. of a batch file, quitting entirely to DOS, running your application, and then
  1852. reloading The DEMO System.  Techniques for doing this are discussed in
  1853. DEMOSYS.DOC under the "Creating menuing systems" section.
  1854.  
  1855. Typically, after running the command, your display screen will be messed up.
  1856. You may want to use any command that will redraw the current screen (REDRAW or
  1857. CLS) or else branch you to another screen (SCREEN, GOTO, CALL, POP) immediately
  1858. after doing a RUN command.
  1859.  
  1860. The command string can include environmental variables, user-defined variables,
  1861. or functions if desired.
  1862.  
  1863. You can also add a ">NUL:" at the end of the command string in order to try to
  1864. eliminate the screen output from the RUN command.  This doesn't always work.
  1865. See also the RUNA command.
  1866.  
  1867. DEMOSYS.REF                   Last revised 03/13/93                     Page 42
  1868.  
  1869. *******************
  1870.  
  1871. RUNA [ string ]
  1872.  
  1873. Similar to the RUN command except the commands are executed in the alternate
  1874. screen (instead of the primary screen) and the alternate screen is also made the
  1875. default screen for viewing the results.  This provides a way of running a batch
  1876. or DOS command without interfering with existing menus.
  1877.  
  1878. Some applications will change the default screen and wipe out your primary
  1879. screen anyway.  This is typically not the case with any internal DOS commands
  1880. but it may be a factor with others.  In these cases, you might as well use RUN
  1881. instead.
  1882.  
  1883. The command string can include environmental variables, user-defined variables,
  1884. or functions if desired.
  1885.  
  1886.  
  1887. *******************
  1888.  
  1889. SAVE filename
  1890.  
  1891. Saves the current screen to a file.  This is desirable in some cases (maybe the
  1892. current screen has an application form and you want the user to be able to print
  1893. or save it).
  1894.  
  1895. "Filename" can by any file (including drive and path information if desired) or
  1896. be any of the following DOS devices:
  1897.  
  1898.         KYBD:
  1899.         SCRN:
  1900.         COM1: to COM4:
  1901.         LPT1: to LPT2:
  1902.         CONS:
  1903.  
  1904. The filename can include environmental variables, user-defined variables, or
  1905. functions if desired.
  1906.  
  1907.  
  1908. DEMOSYS.REF                   Last revised 03/13/93                     Page 43
  1909.  
  1910. *******************
  1911.  
  1912. SCREEN { TOP | FIRST | -999 to 999 | BOTTOM | LAST } [ KEYn | CLEAR | parms ]
  1913.  
  1914. Branches the program to another screen or page using an implied GOTO command.
  1915. In most cases, SCREEN and GOTO can be used synonymously (and, in fact, SCREEN
  1916. commands are internally recoded as GOTO commands).  SCREEN avoids the need to
  1917. hardcode a series of screen names when you want to execute them in a sequence.
  1918. For example:
  1919.  
  1920.         - EXPLAIN.001 First screen
  1921.         KEY (PGDN) SCREEN 1
  1922.         KEY (ESC) QUIT
  1923.         - (GLOBAL)
  1924.         KEY (PGDN) SCREEN 1
  1925.         KEY (PGUP) SCREEN -1
  1926.         KEY (ESC) QUIT
  1927.         - EXPLAIN.002 Second screen
  1928.         - EXPLAIN.003 Third screen
  1929.         - EXPLAIN.004 Fourth screen
  1930.         - (GLOBAL)
  1931.         - EXPLAIN.005 Last screen
  1932.         KEY (PGUP) SCREEN -1
  1933.         KEY (PGDN) NONE
  1934.         KEY (ESC) QUIT
  1935.  
  1936. You can specify screen locations in relative terms using positive numbers to
  1937. move to the next screens in sequence and negative numbers to move to the prior
  1938. screen.  Note that the program does not distinguish text screens from label
  1939. screens when it's doing this movement; if you want to avoid a label, make sure
  1940. the label is not in the sequence you want to pass through.
  1941.  
  1942. You can also specify SCREEN TOP (or SCREEN FIRST) and SCREEN BOTTOM (or SCREEN
  1943. LAST) to take the user to the absolute first screen (*not* the one defined by
  1944. SET TOP; use "POP TOP" to do this) or the absolute last screen.
  1945.  
  1946. The KEYn parameter says to position the cursor at input key "n" when the next
  1947. screen in loaded.
  1948.  
  1949. The CLEAR parameter says to clear the CALL return stack when the jump is made.
  1950.  
  1951. The optional parameters allow you to pass up to 9 values into the next screen.
  1952. These values are stored in %1% to %9%.  These keys remain set until the next
  1953. CALL, GOTO, or SCREEN statement is encountered which also passes parameters.
  1954.  
  1955. Note that a SCREEN statement on its own (outside a KEY statement) will result in
  1956. the current screen being closed and must be followed by a new page declaration
  1957. or else the end of the file.
  1958.  
  1959. The parms can include control codes, environmental variables, user-defined
  1960. variables, or functions.
  1961.  
  1962. See also the CALL and GOTO commands.
  1963.  
  1964. DEMOSYS.REF                   Last revised 03/13/93                     Page 44
  1965.  
  1966. *******************
  1967.  
  1968. SELECT
  1969.  
  1970. Is used only with (MOUSER), (MOUSEL), or (MOUSEB) KEY assignments and the SET
  1971. MOUSE ON command.  Tells the system which mouse button(s) activate a given
  1972. choice.
  1973.  
  1974. When SELECT is encountered, the system looks for the last ^K assignment on
  1975. the same line as the mouse cursor to the left of the mouse cursor.  The mouse
  1976. press is ignored if a valid input field is not found.
  1977.  
  1978. *******************
  1979.  
  1980. WRITE filename string
  1981.  
  1982. Writes a line of text to a file.  This is very useful for creating batch files
  1983. from your program.  It's also a good way of writing usage information or
  1984. anything else you want.  The file is appended to (your text is written to the
  1985. end of it).  If you want the file emptied before you write to it, use a DELETE
  1986. command.
  1987.  
  1988. "Filename" can by any file (including drive and path information if desired) or
  1989. be any of the following DOS devices:
  1990.  
  1991.         KYBD:
  1992.         SCRN:
  1993.         COM1: to COM4:
  1994.         LPT1: to LPT2:
  1995.         CONS:
  1996.  
  1997. The "string" can be just about anything and can include quotes or spaces.  If
  1998. you've just prompted the user for five variables (three alpha and two numeric)
  1999. and you want them written out in an ASCII-delimited format, you'd say the
  2000. following:
  2001.  
  2002.         WRITE TEST.PRN "^UAlpha1^","^UAlpha2^","^UAlpha3^",^UNum1^,^UNum2^
  2003.  
  2004. The filename and the string can include environmental variables, user-defined
  2005. variables, or functions if desired.
  2006.  
  2007. DEMOSYS.REF                   Last revised 03/13/93                     Page 45
  2008.  
  2009. *******************
  2010.  
  2011. @ ^Uvar^ "pattern" [ LEN=n ] [ RANGE=n-n ] [ DEF=s ]
  2012.   [ TEST=cond [rel cond] ] [ QUIT=key ] [ VQUIT=key ] [ HELP=key ]
  2013.   [ COLOR=n ] [ REQ ] [ NOESCAPE ] [ QUIET | -QUIET ]
  2014.  
  2015. Is used for data entry forms.  If there are any of these statements in a command
  2016. page, then there must be as many of these are there are keyboard input fields on
  2017. the screen page.  For example,
  2018.  
  2019.         - *004A Data-entry form
  2020.         ; Note that the first character of each field is automatically converted
  2021.         ; to uppercase for them.  As it is, the %Proper% function fixes up most
  2022.         ; fields before writing out the record.
  2023.         @ ^UName^ "!25X" LEN=5
  2024.         @ ^UCompany^ "!25X"
  2025.         @ ^UStreet1^ "!25X" LEN=5
  2026.         @ ^UStreet2^ "!25X"
  2027.         @ ^UCity^ "!19X"
  2028.         @ ^UState^ "!!" LEN=2
  2029.         @ ^UZip^ "NNNNN-NNNN" /* Because of pattern, ZIP will be minimum of 6 ch
  2030.                               /* Could have imposed a TEST clause if you wanted.
  2031.         @ ^UPhone^ "(NNN) NNN-NNNN" LEN=14
  2032.         @ ^USubmit^ "!" VQUIT=S QUIT=Q DEF=E TEST=%Instr%(SQE,^USubmit^) > 0
  2033.         IF %Upper%(^USubmit^) = Q THEN HOP Skip
  2034.         ASSIGN ^UName^ = %Proper%(^UName^)
  2035.         ASSIGN ^UCompany^ = %Proper%(^UCompany^)
  2036.         ASSIGN ^UStreet1^ = %Proper%(^UStreet1^)
  2037.         ASSIGN ^UStreet2^ = %Proper%(^UStreet2^)
  2038.         ASSIGN ^UCity^ = %Proper%(^UCity^)
  2039.         ; Trailing blanks are always removed from responses in data-
  2040.         ; entry forms so you can do something like "^UCity^, ^UState^ ^UZip^"
  2041.         ; and it will show up correctly as "Silver Spring, MD 20910".
  2042.         WRITE TEST.PRN "^UName^","^UCompany^","^UStreet1^","^UStreet2^",
  2043.            (continuation) "^UCity^, ^UState^ ^UZip^","^UPhone^"
  2044.         ECHO
  2045.         ECHO Entries saved.
  2046.         DROP Skip
  2047.         /.
  2048.                                        Address entry form
  2049.  
  2050.                         User name:    ^K
  2051.                         Company:      ^K
  2052.                         Street:       ^K
  2053.                                       ^K
  2054.                         City, State ZIP: ^K                    , ^K   ^K
  2055.  
  2056.                         Phone:        ^K
  2057.  
  2058.                         Submit?:      ^K   (S=submit & save, Q=quit & nosave,
  2059.                                             E=edit)
  2060.         ./
  2061.         POP
  2062.  
  2063. DEMOSYS.REF                   Last revised 03/13/93                     Page 46
  2064.  
  2065. Incorporating @ commands in your page prevents all normal key assignments from
  2066. working; all standard KEY statements are ignored.
  2067.  
  2068. Use the (TAB) and (S-TAB) keys to move forward and backward in the fields on the
  2069. screen.
  2070.  
  2071. There must be at least one QUIT=key or VQUIT=key parameter coded in a data-entry
  2072. form page.  Otherwise, the cursor cycles through all of the keyboard fields and
  2073. the user can only leave if the press (C-C) (quit to DOS) or (C-J) (jump to DOS);
  2074. neither of which will process any of their prior inputs.
  2075.  
  2076. The default value is -QUIET (vs QUIET) in a data-entry form.
  2077.  
  2078. See also the PROMPT and PROMPTA commands.
  2079.  
  2080. DEMOSYS.REF                   Last revised 03/13/93                     Page 47
  2081.  
  2082. --------------------------------------------------------------------------------
  2083.  
  2084.                                  KEY statement
  2085.  
  2086. KEY key[,key]... action_command [ parms ]
  2087.  
  2088. where:
  2089.  
  2090. "key" can consist of any of the following:
  2091.  
  2092.         regular keys         (BS)         (LPAREN)        (NONE) <-- form only
  2093.         (special keys)       (DEL)        (PGDN)
  2094.         (MOUSER)             (DOWN)       (PGUP)
  2095.         (MOUSEL)             (END)        (RIGHT)
  2096.         (MOUSEB)             (ENTER)      (RPAREN)
  2097.         (ELSE)               (EQUAL)      (SPACE)
  2098.         (ANY)                (ESC)        (TAB)
  2099.         (A-key)              (HOME)       (UP)
  2100.         (C-key)              (INS)        @key
  2101.         (S-key)              (LEFT)       (ALT-n)
  2102.         (LASTKEY) <-- in BUFFER only
  2103.  
  2104. If multiple keys are coded in one KEY statement, the keys must be separated by
  2105. only a comma, no spaces.
  2106.  
  2107. "action_command" are any of the action commands listed previously.
  2108.  
  2109. "parms" are in fact required for some action commands.
  2110.  
  2111.  
  2112. Four key assignments are made by default by The DEMO System.  If you do not want
  2113. these keys assigned as such, you have to specifically reassign the keys or use
  2114. the (ANY) key assignment.  You cannot use SET KEYS CLEAR or an non-specific
  2115. (GLOBAL) definition to clear them.
  2116.  
  2117.         SET (C-C) QUIT
  2118.         SET (C-F1) ECHO ^P25,65%PageName%@
  2119.         SET (C-J) RUN
  2120.         SET (C-R) REDRAW
  2121.  
  2122.  
  2123. DEMOSYS.REF                   Last revised 03/13/93                     Page 48
  2124.  
  2125. --------------------------------------------------------------------------------
  2126.  
  2127.                          Miscellaneous string concepts
  2128.  
  2129. Screens, displayed text (with a few exceptions), and some action commands can
  2130. have some special things imbedded in them.  Most of them accept one or more of
  2131. the following types of strings:
  2132.  
  2133.   * &Pn     variables passed in when invoking DEMOMAKE itself
  2134.   * ^Uvar^  user-defined variables
  2135.   * ^Evar^  DOS-defined environmental variables
  2136.   * %func%  system-defined functions
  2137.   * ^ctl    system-defined control functions (for cursor positioning, coloring,
  2138.             etc)
  2139.  
  2140. Typically, these can be joined together by just putting them next to each other
  2141. in the parameter line.  For example, FIELD^UCurField^.
  2142.  
  2143. The &Pn parameters can include anything.  You could pass in "DO MACRO1" and have
  2144. a control file that specifies "&P1 &P2" on a line together and that Macro would
  2145. be invoked.  &Pn parameters are discussed below but are ignored in all other
  2146. discussions.  Basic rule: anywhere you can use anything, you can put in a &Pn
  2147. parameter.
  2148.  
  2149. The following table defines which action commands support which of these items.
  2150. It indicates the same for the input screen itself.
  2151.  
  2152.         Action command          ^Uvar^  ^Evar^  %func%  ^ctl
  2153.  
  2154.         ASSIGN  (left side)     OK      n/a     n/a     n/a
  2155.                 (right side)    OK      OK      OK      n/a
  2156.         CALL    (parms)         OK      OK      OK      OK
  2157.         CD      (directory)     OK      OK      OK      n/a
  2158.         CDD     (d:directory)   OK      OK      OK      n/a
  2159.         COPY                    OK      OK      OK      n/a
  2160.         DELETE                  OK      OK      OK      n/a
  2161.         ECHO, ECHOA             OK      OK      OK      OK
  2162.         GOTO    (parms)         OK      OK      OK      OK
  2163.         IF      (conditions)    OK      OK      OK      n/a
  2164.         LOCATE                  OK      OK      OK      n/a
  2165.         MD      (directory)     OK      OK      OK      n/a
  2166.         MSGBOX, MSGBOXA (msg)   OK      OK      OK      n/a
  2167.         PLAY                    OK      OK      OK      n/a
  2168.         PROMPT, PROMPTA (var)   OK      n/a     n/a     n/a
  2169.                 (DEF= parm)     OK      OK      OK      n/a
  2170.         QUIT                    OK      OK      OK      n/a
  2171.         RD      (directory)     OK      OK      OK      n/a
  2172.         RUN, RUNA               OK      OK      OK      n/a
  2173.         SAVE                    OK      OK      OK      n/a
  2174.         WRITE                   OK      OK      OK      n/a
  2175.  
  2176.         Text screens            OK      OK      OK      OK
  2177.  
  2178.  
  2179. DEMOSYS.REF                   Last revised 03/13/93                     Page 49
  2180.  
  2181. &Pn:  Variables passed in when invoking DEMOMAKE itself:
  2182.  
  2183. When your control file is compiled by the DEMOMAKE program, you can include
  2184. up to nine additional parameters.  These nine parameters are filled into your
  2185. control file whenever &P1 to &P9 is encountered in the control file.  For
  2186. example:
  2187.  
  2188.         /* Filename is DEMOPN.CTL
  2189.         /* Demo of &Pn stuff
  2190.         - *Dummy Simple screen to show how they work
  2191.         ECHO &P1 &P2
  2192.         /.
  2193.  
  2194.         I hope you passed in some text:
  2195.         ./
  2196.         QUIT
  2197.  
  2198. You would then invoke the DEMOMAKE program by including (in our case) up to two
  2199. optional parameters:
  2200.  
  2201.         DEMOMAKE DEMOPN.CTL DEMOPN.EXE Wayne Software
  2202.  
  2203. During compilation, &P1 will be substituted with "Wayne" and &P2 will be
  2204. substituted with "Software".  (Note that the output file specification, which is
  2205. normally optional, is required if you pass in additional parameters.)
  2206.  
  2207. If you want multiple words to be passed in and assigned to one variable, enclose
  2208. the words in quotes.  In the example above "Wayne Software" in quotes would have
  2209. filled up just &P1.
  2210.  
  2211. DEMOSYS.REF                   Last revised 03/13/93                     Page 50
  2212.  
  2213. While the above example shouldn't knock your socks off, remember that the
  2214. DEMOMAKE program substitutes the values of the parameters and then compiles the
  2215. program.  This means that you could change commands each time you compile the
  2216. code.  For example:
  2217.  
  2218.         /* Another demonstration.  Pass in either MACRO1 or MACRO2
  2219.         /* when you use the DEMOMAKE command.  That will determine which
  2220.         /* definitions are applied.  If you compile with MACRO1, they
  2221.         /* can't reformat the disk.  If you pass in MACRO2, they can.
  2222.         MACRO MACRO1
  2223.         - @REFORMAT
  2224.         CLS
  2225.         BEEP
  2226.         ECHO You have not been authorized to use this function.
  2227.         ECHO Please check with your system administrator.
  2228.         PAUSE
  2229.         POP
  2230.         MEND
  2231.  
  2232.         MACRO MACRO2
  2233.         - @REFORMAT
  2234.         CLS
  2235.         ECHO ^C2Okay, let's reformat that sucker!
  2236.         RUN FORMAT A:
  2237.         ECHO Press a key to continue
  2238.         PAUSE
  2239.         POP
  2240.         MEND
  2241.  
  2242.         DO &P1
  2243.  
  2244.         - *Testing Another example of a macro
  2245.         SET MOUSE ON
  2246.         KEY (MOUSER) SELECT
  2247.         KEY (UP) FIELD -1
  2248.         KEY (DOWN) FIELD +1
  2249.         KEY @1,R CALL @REFORMAT
  2250.         KEY @2,X QUIT
  2251.         SET CURSOR ^C2==>
  2252.         /.
  2253.         Select an option:
  2254.                 ^K   R Reformat disk (restricted access)
  2255.                 ^K   X Quit
  2256.         ./
  2257.  
  2258.  
  2259. DEMOSYS.REF                   Last revised 03/13/93                     Page 51
  2260.  
  2261. &n: Variables passed in with a DO statement:
  2262.  
  2263. When invoking a macro (using a DO statement), you can pass in up to ten
  2264. parameters.  These parameters are split up as &1 to &9 and expanded wherever
  2265. they occur.  An example of this is provided in the DEMOSYS.DOC manual.
  2266.  
  2267.  
  2268. ^Uvar^: User-defined variables:
  2269.  
  2270. You can establish your own variables within The DEMO System.  These variables
  2271. can be displayed, used in calculations, or reassigned as necessary.  The
  2272. variables must begin with a "^U", followed by any characters except for spaces
  2273. and the "^" character, and end with a "^".  Internally, variables are truncated
  2274. at 8 characters (ignoring the opening "^U" and closing "^" characters).  The
  2275. case of the variable is ignored by the system: "^UName^" and "^UNAME^" are the
  2276. same.
  2277.  
  2278.  
  2279. ^Evar^:  DOS-defined environmental variables:
  2280.  
  2281. You can read (but not set) the value of any DOS environmental variable.  These
  2282. are any variables that show up when you issue the "SET" command in DOS itself.
  2283. Most DOS-environmental variables are optional; if the variable isn't set, ^Evar^
  2284. will return null.  Typical environmental variables:
  2285.  
  2286.         ^ECOMSPEC^      The user's COMSPEC setting; where COMMAND.COM is
  2287.                         loaded from
  2288.         ^EPATH^         The user's SET PATH setting; where the system looks
  2289.                         for EXE, COM, and BAT files
  2290.         ^EPROMPT^       The user's prompt.  Typically, $P$G but some creative
  2291.                         ones exist out there
  2292.  
  2293. If you're designing a menuing system, you may require the user to establish some
  2294. environmental variable in DOS (e.g. SET MENU=X) that you can test.  Frequently,
  2295. networks require environmental variables to be assigned to the user's local
  2296. network directory.  You can test for this too.
  2297.  
  2298. The case of the ^Evar^ parameter is irrelevant; all DOS environmental variables
  2299. are expressed in uppercase letters and The DEMO System translates yours
  2300. appropriately.
  2301.  
  2302.  
  2303. DEMOSYS.REF                   Last revised 03/13/93                     Page 52
  2304.  
  2305. %func%:  System-defined functions:
  2306.  
  2307. The DEMO System provides a number of functions which you can test or display in
  2308. your program.  The functions do not actually change any strings; they themselves
  2309. return a string (or numeric) value which you can use in an ASSIGN statement if
  2310. you want the value retained.
  2311.  
  2312. Some of the functions require one or more parameters, which are typically
  2313. enclosed in parentheses and separated by commas.  All parameters can be strings,
  2314. environmental variables, or user-defined variables.  Strings should not be
  2315. enclosed in quotes.  (It's %Drive%(c), not %Drive%("C").) You cannot use a
  2316. function as a parameter for a function; you have to use a separate ASSIGN
  2317. statement for to resolve a function and then use the resulting variable as your
  2318. parameter.
  2319.  
  2320. If your parameter includes a comma or a close-parenthesis, you would have to
  2321. specify a different delimiter for the parameter.  You can use any of nine other
  2322. delimiters by using one of them instead of the open-parenthesis.  The choice of
  2323. characters is any one of the following:
  2324.  
  2325.                 /               (slash)
  2326.                 [               (open bracket)
  2327.                 |               (vertical bar)
  2328.                 ^               (control character)
  2329.                 :               (colon)
  2330.                 !               (exclamation point)
  2331.                 *               (asterisk)
  2332.                 _               (underscore)
  2333.                 -               (dash)
  2334.  
  2335. This delimiter will have to be used between parameters and at the end of the
  2336. last parameter.  For example, the following are both functionally equivalent:
  2337.  
  2338.                 %Mid%(^UName^,4,5)
  2339.                 %Mid%!^UName^!4!5!
  2340.  
  2341. The functions are listed alphabetically below.  Typical parameter types are
  2342. indicated but, as was mentioned, the parameters can actually be strings,
  2343. environmental variables, or user-defined variables.
  2344.  
  2345. The descriptions indicate "Returns:  xxx" which shows you whether the function
  2346. returns a string ("s"), number ("n"), or single character ("c").
  2347.  
  2348. Also indicated is "Invalid:  xxx" which indicates what sort of value is returned
  2349. if invalid parameters are specified, typically "0" or "-1" (for numeric
  2350. functions), "null" (for string or character functions), or "n/a" (meaning the
  2351. function doesn't accept parameters).
  2352.  
  2353. DEMOSYS.REF                   Last revised 03/13/93                     Page 53
  2354.  
  2355. %Add%(var,num)          Returns: n              Invalid: 0
  2356.   Adds a number to another number.  If the first parameter is undefined, it is
  2357.   assumed to have a value of 0.  Remember, this doesn't change the value of
  2358.   var at all.  You have to do that doing something like this:
  2359.         ASSIGN ^UVar^ = %Add%(^UVal^,1)
  2360.  
  2361. %Col%                   Returns: n              Invalid: n/a
  2362.   Indicates the current column position on the screen.
  2363.  
  2364. %Date%                  Returns: s              Invalid: n/a
  2365.   Returns the current system date in mm/dd/yy format.
  2366.  
  2367. %DateOrig%              Returns: s              Invalid: n/a
  2368.   Returns the date the user initially loaded your program in mm/dd/yy format.
  2369.   Typically the same as %Date%.
  2370.  
  2371. %DateR2S%(num)          Returns: s              Invalid: null
  2372.   Translates a relative date into its mm/dd/yy value.  See %DateS2R%.
  2373.  
  2374. %DateS2R%(date)         Returns: n              Invalid: 0
  2375.   Translates a date (in mm/dd/yy or mm-dd-yyyy format) into its relative date.
  2376.   All relative dates are based on January 1, 1899 for some reason but the year
  2377.   can't be before 1900 so the smallest value you can get is 365 which is for
  2378.   %DateS2R%(01-01-1900).
  2379.  
  2380. %DateValid%(date)       Returns: n              Invalid: 0
  2381.   Returns 1 if the date is valid, 0 otherwise.  You could use %DateS2R% to
  2382.   accomplish the same thing.
  2383.  
  2384. %Dir%                   Returns: s              Invalid: n/a
  2385.   Returns the current directory in drive:directory format.  The function does
  2386.   not put a slash at the end of string unless the directory is the root, in
  2387.   which case it comes back as drive:\.  See the %FileJoin% function.
  2388.  
  2389. %Display%               Returns: s              Invalid: n/a
  2390.   Returns COLOR (primary color set) or MONO (alternate color set).  This doesn't
  2391.   have any relationship to whether the user's monitor is color or monochrome;
  2392.   only which color set you're using.
  2393.  
  2394. %DisplayEGA%            Returns: n              Invalid: n/a
  2395.   Returns 1 if the user's monitor supports EGA, otherwise 0.
  2396.  
  2397. %DisplayNum%            Returns: n              Invalid: n/a
  2398.   Returns 1 (primary color set) or 0 (alternate color set).  This doesn't have
  2399.   any relationship to whether the user's monitor is color or monochrome; only
  2400.   which color set you're using.
  2401.  
  2402. %DisplayVGA%            Returns: n              Invalid: n/a
  2403.   Returns 1 if the user's monitor supports VGA, otherwise 0.
  2404.  
  2405. DEMOSYS.REF                   Last revised 03/13/93                     Page 54
  2406.  
  2407. %Div%(var,num)          Returns: n              Invalid: 0
  2408.   Divides one number by another.  If the first parameter is undefined, it is
  2409.   assumed to have a value of 0.  If the second parameter is undefined or 0, the
  2410.   result is 0.  Remember, this doesn't change the value of var at all.  You have
  2411.   to do that doing something like this:
  2412.         ASSIGN ^UVar^ = %Div%(^UVal^,2)
  2413.  
  2414. %Drive%(drive)          Returns: n              Invalid: 0
  2415.   Returns 1 if the drive indicated by the parameter is valid, 0 if not.  The
  2416.   drive parameter is truncated to one character if a longer one is provided.
  2417.  
  2418. %DriveCur%              Returns: s              Invalid: n/a
  2419.   Returns the current drive letter followed by a colon.
  2420.  
  2421. %DriveDir%(drive)       Returns: s              Invalid: null
  2422.   Returns the default subdirectory on the specified drive.  The subdirectory is
  2423.   preceded by the drive and a colon; it is not followed by a slash (e.g.  it
  2424.   returns "C:\UTIL").  If the default directory is the root, the result will
  2425.   come back with a trailing slash (e.g.  "C:\").  See the %FileJoin% function.
  2426.   The drive parameter is truncated to one character if a longer one is provided.
  2427.  
  2428. %DriveDirOrig%          Returns: s              Invalid: n/a
  2429.   Returns the default drive and directory that was in affect when your program
  2430.   was loaded.  Often useful to return you to the original subdirectory.  See
  2431.   also the %FileOrigDir% and %FileOrig% functions.
  2432.  
  2433. %DriveLabel%(drive)     Returns: s              Invalid: null
  2434.   Returns the label on a given drive.  The label can be a maximum of 11
  2435.   characters in length.  The drive parameter is truncated to one character if a
  2436.   longer one is provided.
  2437.  
  2438. %DriveOrig%             Returns: s              Invalid: n/a
  2439.   Returns the default drive (followed by a colon) that was in affect when your
  2440.   program was loaded.  See also the %FileOrigDir% and %FileOrig% functions.
  2441.  
  2442. %DriveSpace%(drive)     Returns: n              Invalid: -1
  2443.   Returns the amount of free space available on the specified drive.  The drive
  2444.   parameter is truncated to one character if a longer one is provided.
  2445.  
  2446. %FieldMax%              Returns: n              Invalid: n/a
  2447.   Returns the maximum number of user input fields on the current screen.
  2448.  
  2449. %FieldNum%              Returns: n              Invalid: 0
  2450.   Returns the current field number on the current screen.
  2451.  
  2452. DEMOSYS.REF                   Last revised 03/13/93                     Page 55
  2453.  
  2454. %FileDate%(filespec)    Returns: s              Invalid: null
  2455.   Returns the file creation date of the specified file in mm/dd/yy format.
  2456.  
  2457. %FileExist%(filespec)   Returns: n              Invalid: 0
  2458.   Returns 1 if the specified file exists, 0 otherwise.
  2459.  
  2460. %FileJoin%(path,file)   Returns: s              Invalid: null
  2461.   Returns a string with the path joined with the file name.  In so doing, the
  2462.   function adds a trailing slash to the path if necessary.  It then checks the
  2463.   combined filespec and returns a value of null if any of the following
  2464.   conditions are met:  the filespec is invalid, the specified drive does not
  2465.   exist, or the specified subdirectory on the drive does not exist.  See also
  2466.   the %FileValid% function.  Note that DOS accepts a whole bunch of filespecs as
  2467.   "valid" and then alters them later; "ABCDEFGHIJKLM" will actually become
  2468.   "ABCDEFGH.IJK".  This function returns the name before DOS alters it.
  2469.  
  2470. %FileMakeTest%(path)    Returns: n              Invalid: non-0
  2471.   A general-purpose function that tells you a number of things about a drive or
  2472.   directory.  The function tries to create a temporary file in the specified
  2473.   path, deleting it afterward if successful.  If successful, it returns a 0
  2474.   file.  If nut successful, it returns one of the following DOS error codes:
  2475.  
  2476.         3   path not found (or specified incorrectly)
  2477.        15   invalid disk specified
  2478.        19   disk is write protected
  2479.        21   disk not ready (e.g. no disk in drive A)
  2480.        26   disk is not in DOS format
  2481.        32   sharing violation (didn't have write access to the directory)
  2482.  
  2483. %FileOrig%              Returns: s              Invalid: n/a
  2484.   Returns the name of the program that the person loaded including drive and
  2485.   path information.
  2486.  
  2487. %FileOrigDir%           Returns: s              Invalid: n/a
  2488.   Returns just the drive and path of the program that the person loaded.  Useful
  2489.   in cases where there are data files or something in the same location.  The
  2490.   path does not end with a "\" unless it's the root.  See the %FileJoin%
  2491.   function.
  2492.  
  2493. %FileSize%(filespec)    Returns: n              Invalid: -1
  2494.   Returns the size of the specified file in bytes.
  2495.  
  2496. %FileTime%(filespec)    Returns: s              Invalid: null
  2497.   Returns the file creation time of the specified file in hh:mm:ss format.
  2498.  
  2499. %FileValid%(filespec)   Returns: s              Invalid: null
  2500.   Returns a fully formatted filespec (including drive and path information if
  2501.   not provided).  Returns null under any of the following conditions:  the
  2502.   filespec is invalid, the specified drive does not exist, or the specified
  2503.   subdirectory on the drive does not exist.  Note that DOS accepts a whole bunch
  2504.   of filespecs as "valid" and then alters them later; "ABCDEFGHIJK" will
  2505.   actually become "ABCDEFGH.IJK".  This function returns the name before DOS
  2506.   alters it.
  2507.  
  2508. DEMOSYS.REF                   Last revised 03/13/93                     Page 56
  2509.  
  2510. %FreeEMS%               Returns: n              Invalid: 0
  2511.   Returns the amount of free EMS memory in kilobytes.
  2512.  
  2513. %Instr%(str1,str2)      Returns: n              Invalid: n/a
  2514.   Returns the column position in string1 in which string2 is found.  For
  2515.   example, %Instr%(Bruce,uc) returns a value of 3.  Note that the search is case
  2516.   sensitive.
  2517.  
  2518. %Instr2%(n,str1,str2)   Returns: n              Invalid: 0
  2519.   Returns the column position in string1 in which string2 is found, starting
  2520.   the search in column position n.  The search is case sensitive.  If n is 1,
  2521.   then you can use the %Instr% function instead.
  2522.  
  2523. %Left%(string,num)      Returns: s              Invalid: null
  2524.   Returns the leftmost num characters from string.
  2525.  
  2526. %Len%(string)           Returns: n              Invalid: n/a
  2527.   Returns the length of the specified string.
  2528.  
  2529. %Lower%(string)         Returns: n              Invalid: n/a
  2530.   Returns the specified string expressed in lowercase letters.
  2531.  
  2532. %Mid%(str,offset,num)   Returns: s              Invalid: null
  2533.   Returns a subset of a given string, starting at position offset and taking
  2534.   num characters from that point.  If the num parameter is left as blank, the
  2535.   function will return all characters starting at offset and going until the
  2536.   end of the string.  Note that three parameters are required so you have to
  2537.   code this like: %Mid%(Bruce,3,)
  2538.  
  2539. %Mouse%                 Returns: n              Invalid: 0
  2540.   Returns the number of buttons the user's mouse has.  Typically 2 or 3 if a
  2541.   mouse is present, 0 if not.
  2542.  
  2543. %Mult%(var,num)         Returns: n              Invalid: 0
  2544.   Multiplies one number by another.  If the first parameter is undefined, it is
  2545.   assumed to have a value of 0.  Remember, this doesn't change the value of
  2546.   var at all.  You have to do that doing something like this:
  2547.         ASSIGN ^UVar^ = %Mult%(^UVal^,3)
  2548.  
  2549. DEMOSYS.REF                   Last revised 03/13/93                     Page 57
  2550.  
  2551. %PageDesc%              Returns: s              Invalid: n/a
  2552.   Returns the description for the current filename reference.
  2553.  
  2554. %PageLines%             Returns: n              Invalid: 0
  2555.   Returns the number of lines on the current display screen.
  2556.  
  2557. %PageMax%               Returns: n              Invalid: n/a
  2558.   Returns the maximum defined screen in the current program.
  2559.  
  2560. %PageName%              Returns: s              Invalid: n/a
  2561.   Returns the current file page name.  This may be "@label", "*ref", or
  2562.   "filename" depending on what type of page it was.
  2563.  
  2564. %PageNum%               Returns: n              Invalid: n/a
  2565.   Returns the current page number.
  2566.  
  2567. %PathCanMake%(path)     Returns: n              Invalid: 0
  2568.   Returns 1 if the specified path can be created.  A 0 will be returned if the
  2569.   path is invalid, the specified path exists already, or if the necessary
  2570.   subdirectories don't exist to build it upon; e.g.  creating \TC\NEW when \TC
  2571.   doesn't exist.  The DEMO System actually determines the validity of this by
  2572.   trying to create the path, and then removing the path once done.  See also the
  2573.   %FileCreateTest% function.
  2574.  
  2575. %PathExist%(path)       Returns: n              Invalid: 0
  2576.   Returns 1 if the specified path exists already.
  2577.  
  2578. %PrinterReady%(num)     Returns: n              Invalid: 0
  2579.   Returns 0 if the specified printer is not ready.  The printer must be
  2580.   specified by its number: 1 is LPT1, 2 is LPT2, 3 is LPT3.  COM printers
  2581.   cannot be tested.
  2582.  
  2583. %Proper%(str)           Returns: s              Invalid: n/a
  2584.   Returns a string in proper name case format.  The first letter of every word
  2585.   is capitalized and the other characters are not.  So "WAYNE software" comes
  2586.   out as "Wayne Software".
  2587.  
  2588. %ReplaceStr%(str,old,new) Returns: s            Invalid: n/a
  2589.   Returns a string with any occurence of the old string converted to the
  2590.   new string.  For example, "%ReplaceStr%(Bruce,uce,at)" would return "Brat".
  2591.   The old and new strings can be of any length.
  2592.  
  2593. %Right%(str,num)        Returns: n              Invalid: null
  2594.   Returns the right-most num characters from the specified string.
  2595.  
  2596. %Row%                   Returns: n              Invalid: n/a
  2597.   Returns the current row.
  2598.  
  2599. DEMOSYS.REF                   Last revised 03/13/93                     Page 58
  2600.  
  2601. %Sub%(var,num)          Returns: n              Invalid: 0
  2602.   Subtracts one number from another.  If the first parameter is undefined, it is
  2603.   assumed to have a value of 0.  Remember, this doesn't change the value of
  2604.   var at all.  You have to do that doing something like this:
  2605.         ASSIGN ^UVar^ = %Sub%(^UVal^,1)
  2606.  
  2607. %Time%                  Returns: s              Invalid: n/a
  2608.   Returns the current system time in hh:mm:ss format.
  2609.  
  2610. %TimeElapsed%           Returns: s              Invalid: 0
  2611.   Returns the elapsed time between when the program started (%TimeOrig%) and
  2612.   the current time (%Time%) in hh:mm:ss format.  Result will be 0 if the time
  2613.   extends over midnight.
  2614.  
  2615. %TimeOrig%              Returns: s              Invalid: n/a
  2616.   Returns the time at which the program was initially started in hh:mm:ss
  2617.   format.
  2618.  
  2619. %TimeR2S%(num)          Returns: s              Invalid: null
  2620.   Returns a relative time converted to hh:mm:ss format.
  2621.  
  2622. %TimeS2R%(string)       Returns: n              Invalid: 0
  2623.   Converts a time string (in hh:mm:ss format) converted to the number of seconds
  2624.   after midnight.
  2625.  
  2626. %Trim%(string)          Returns: s              Invalid: n/a
  2627.   Trims leading and trailing spaces from a specified string.
  2628.  
  2629. %Upper%(string)         Returns: s              Invalid: n/a
  2630.   Returns a string with all lowercase letters converted to uppercase.
  2631.  
  2632. %Weekday%(date)         Returns: s              Invalid: null
  2633.   Returns the weekday (in proper case format--"Sunday") for a given date in
  2634.   mm/dd/yy or mm-dd-yyyy format.
  2635.  
  2636. %1% to %9%              Returns: s              Invalid: n/a
  2637.   These are the parameters passed in by a CALL, GOTO, or SCREEN command.
  2638.  
  2639.  
  2640. DEMOSYS.REF                   Last revised 03/13/93                     Page 59
  2641.  
  2642. ^ctrl:  Control codes:
  2643.  
  2644. The screens themselves can include codes which establish colors, input
  2645. locations, and other things.  There are seven types of control codes that The
  2646. DEMO System accepts in text strings (including logos and cursor indicators) but
  2647. one of them (the "^Prow,col" indicator) should not be used within a screen.
  2648. These codes are as follows:
  2649.  
  2650.         ^Cn             /* Set the color to color (or monochrome) set "n"
  2651.         ^K              /* Establish this as a keyboard-input field
  2652.         ^Evar^          /* Print a DOS-defined environmental variable here
  2653.         ^Uvar^          /* Print a user-defined variable here
  2654.         %func%          /* Print a function result here
  2655.         ^Tn             /* Print "n" non-destructive spaces here
  2656.         ^Sn             /* Print "n" destructive spaces here (used only
  2657.                         /* to reduce the size of your input file; The DEMO
  2658.                         /* System automatically uses space compression when it
  2659.                         /* encounters five or more spaces together)
  2660.         ^Pr,c           /* Locate the cursor at row "r" and column "c":
  2661.                         /* this setting is not allowed within text screens
  2662.                         /* themselves and should only be used in SET CURSOR,
  2663.                         /* SET LOGO, ECHO, PROMPT, etc commands
  2664.         ^_              /* Ignored.  Typically used only if you want to
  2665.                         /* print out one of the other control key sequences
  2666.  
  2667. Any text that is not part of these control codes (including spaces) are treated
  2668. as text and is printed as is.
  2669.  
  2670.  
  2671. DEMOSYS.REF                   Last revised 03/13/93                     Page 60
  2672.  
  2673. --------------------------------------------------------------------------------
  2674.  
  2675.                           Primary vs alternate screen
  2676.  
  2677. There are actually two screens that The DEMO System uses.  The first screen, the
  2678. "primary screen", is used automatically for all text screens and by most of the
  2679. commands.  The second screen, called the "alternate screen", is typically used
  2680. when you want to run a DOS command and not have the output from this command
  2681. affect the text screen the user is viewing.  Sometimes, you will want the output
  2682. of the command to disappear completely.
  2683.  
  2684. There are are number of commands that provide the capability of writing to
  2685. either of these two screens:
  2686.  
  2687.                         Primary   Alternate
  2688.  
  2689.                         CLS       vs CLSA
  2690.                         ECHO      vs ECHOA
  2691.                         MSGBOX    vs MSGBOXA
  2692.                         PAUSE     vs PAUSEA
  2693.                         PROMPT    vs PROMPTA
  2694.                         RUN       vs RUNA
  2695.  
  2696. In most cases, stick to the command without the "A" suffix.
  2697.  
  2698.  
  2699. --------------------------------------------------------------------------------
  2700.  
  2701.                                 System maximums
  2702.  
  2703. Several (but not all) of these maximums can be expanded if necessary.  If this
  2704. becomes a problem, contact Wayne Software at the address specified at the top of
  2705. this document.
  2706.  
  2707.                Maximum number of pages: 1000
  2708.                Maximum number of pages with imbedded text: 999
  2709.                Keys (or actions) defined per screen: 255
  2710.                Keyboard input fields per screen: 90
  2711.                Color sets: 8 (0 to 7)
  2712.                CALL return stack: last 20 calls
  2713.                Maximum number of user variables used in program: 30
  2714.                Maximum number of lines per screen: 25
  2715.                Maximum supported number of columns per screen: 80
  2716.                Maximum screen size (in bytes): 2K
  2717.  
  2718.