home *** CD-ROM | disk | FTP | other *** search
/ Frostbyte's 1980s DOS Shareware Collection / floppyshareware.zip / floppyshareware / BOYDOC50.ZIP / BOYFILES.ZIP / BD5 < prev    next >
Text File  |  1991-07-01  |  105KB  |  1,973 lines
  1.                                   Chapter 5
  2.  
  3.                      BOYAN Power--Macros and Script Files
  4.  
  5.  
  6.    5.1  Overview
  7.  
  8.  
  9.    A macro is a sequence of commands which instructs BOYAN to  perform some
  10.    action.  Beneath the  "surface"  of BOYAN which you normally see, macros
  11.    are responsible for a variety of tasks--for instance, dialing the modem,
  12.    handling your  keyboard  commands,  and  maintaining  the  activity log.
  13.    Because all these macros are user-programmable, you have a great deal of
  14.    power  in  determining  what BOYAN does, and when and how  it  does  it.
  15.    BOYAN's  Macro  Programming  Language is described in section 5.2.  Many
  16.    useful sample macros are presented in section 5.3.
  17.  
  18.    To automate even the most  complex communication tasks, BOYAN allows you
  19.    to link many macros together into text files called "scripts."  Although
  20.    BOYAN  can create simple scripts automatically  with  the  Script  Learn
  21.    facility (section 4.7.3), you  can  write much more powerful scripts.  A
  22.    script file could take control of your computer at a  pre-assigned time,
  23.    dial into a database, perform a search, and print the  results--all with
  24.    nobody  at  the  keyboard.  BOYAN's Host Mode is written completely as a
  25.    script file.   Still  another  application  for script files might be to
  26.    create  a  customized  front-end  menu  interface  for  all  of  BOYAN's
  27.    commands.  BOYAN scripts are explained in section 5.5.
  28.  
  29.  
  30.    5.2  The Macro Programming Language
  31.  
  32.  
  33.    Most macro/script commands  consist  of a backslash plus two characters;
  34.    for  example,  \zs  is the command to "zap" (clear) the  screen.    Many
  35.    commands also require further information enclosed  in  square brackets;
  36.    for  example,  \di[730-2917]  is the command to dial the specified phone
  37.    number.  A macro is a sequence  of  one  or  more  commands,  all strung
  38.    together on a  line  of  text.    Thus the macro \zs \di[730-2917] would
  39.    instruct BOYAN  to  first  clear  the  screen,  and then dial the modem.
  40.    Spaces may be placed between  commands to make the macro easier to read.
  41.  
  42.  
  43.    5.2:  BOYAN Power--Macros and Script Files                            81
  44.    ________________________________________________________________________
  45.  
  46.  
  47.    The Macro Programming Language also provides approximately 100 variables
  48.    which can be  included  in  any  command.   Variables are specified by a
  49.    percent  sign  plus  two  characters;  for example, %XP  represents  the
  50.    current X-position of the cursor.  Wherever a BOYAN variable is found in
  51.    a  macro, it is replaced by its current value.  (A variable may also  be
  52.    specified  with  an  @-sign,  e.g.,  @XP  instead of %XP.  The technical
  53.    difference between % and @ is explained in section 5.5.6.2.)
  54.  
  55.    The  next  several  sections explain the many variables and commands you
  56.    can use to automate BOYAN.  The commands and variables have been divided
  57.    into categories such as String  Output,  Dialing,  File  Transfers, User
  58.    Variables, and Script-specific commands.    Note  that  there is also an
  59.    alphabetical summary of all  macro  commands and variables at the end of
  60.    this chapter.
  61.  
  62.    5.2.1  String Output
  63.  
  64.    Any macro can include a string of text like "password".    Such a string
  65.    is sent directly over the modem.  Eight characters--the caret, quotation
  66.    mark, backquote, tilde, left curly  brace,  percent  sign,  at-sign, and
  67.    backslash--have  special meanings and are not  sent  directly  over  the
  68.    modem  unless  they  are  preceded  by  a  quotation  mark.  The special
  69.    meanings of these  characters  are  described  in  section  3.9.1.   The
  70.    following example demonstrates some basic commands:
  71.  
  72.       ATZ{~```\$```WELCOME CLASS OF "`99{
  73.  
  74.    The example sends ATZ <Enter> to the modem, and then pauses for one-half
  75.    second  (~).  The backquotes are for spacing  and  the  macro  processor
  76.    ignores  them.    The  \$  command  causes  Shortcut  macro  #114 to  be
  77.    processed.   Finally, the phrase WELCOME CLASS OF `99  is  sent  to  the
  78.    modem,  where  the  quotation  mark  signifies that the  character  that
  79.    follows, the backquote, should be sent over the modem, not  ignored like
  80.    the other backquotes.
  81.  
  82.    5.2.2  How to Read the Macro Definitions
  83.  
  84.    In the command format descriptions, the following conventions are used:
  85.  
  86.    c                represents a single character, like  Y
  87.  
  88.    x, y, or z       represents an integer number, like  12.  Numbers may be
  89.                     specified in hexadecimal if  they  are  preceded by a $
  90.                     sign, like $1B.
  91.  
  92.    filename         represents  a full filename specifier, such as  FOO.ZIP
  93.                     or C:\MODEM\FILES\BOYAN.DOC.
  94.  
  95.  
  96.    5.2.2:  BOYAN Power--Macros and Script Files                          82
  97.    ________________________________________________________________________
  98.  
  99.  
  100.    string           represents a string of characters not  to  be processed
  101.                     as a macro, like  WELCOME!
  102.  
  103.    macro            represents an executable macro, like  \DI[730-2917]
  104.  
  105.    5.2.2.1  Conditional Macro Syntax
  106.  
  107.    Conditional  macro  commands  allow your macros to make decisions.  With
  108.    each conditional command, you enclose a macro in brackets which is to be
  109.    executed  only  if the condition is met.    For  example,  the  \CA+[..]
  110.    conditional macro tests whether there is a carrier signal.  The macro:
  111.  
  112.         \CA+[\ST[You are online.]]
  113.  
  114.    displays the Status message "You are online" only if there is a carrier.
  115.    If there is no carrier, then the macro has no effect.
  116.  
  117.    If-then-else decisions may  be  programmed by placing the special string
  118.    |ELSE inside the  enclosed  macro.    You  may abbreviate the |ELSE by a
  119.    single vertical bar |.  The part of the macro beyond the |ELSE string is
  120.    executed only if the condition was NOT met.  For example, the macro:
  121.  
  122.         \CA+[\ST[You are online.] |ELSE \ST[You are offline.]]
  123.  
  124.    displays "You are online" if the carrier signal is detected, or "You are
  125.    offline" if no carrier is present.  The identical effect can be achieved
  126.    using the complementary \CA-[..] macro:
  127.  
  128.         \CA-[\ST[You are offline.] |ELSE \ST[You are online.]]
  129.  
  130.                                *    *    *    *
  131.  
  132.    Each macro command and variable below is presented with  its  format  on
  133.    the  left,  an example on the right,  and  a  mnemonic  and  description
  134.    following.
  135.  
  136.    5.2.3  Modem Commands
  137.  
  138.    ^c                                                                    ^[
  139.    Sends the specified control  character;  e.g., ^X sends a control-X;  ^[
  140.    sends the <Escape> character.  Note that ^M, which sends a <Return>, can
  141.    also be represented as { in a BOYAN macro.
  142.  
  143.    \CA+[macro]           \CA+[\DM[You have connected!]|\DM[No connection.]]
  144.    \CA-[macro]                                                \CA-[ATS0=0{]
  145.    CArrier?  The \CA+ command processes the enclosed macro  only  if  BOYAN
  146.    detects carrier, that is, if the modem is currently connected.  The \CA-
  147.    command processes its macro only if BOYAN does not detect carrier.
  148.  
  149.  
  150.    5.2.3:  BOYAN Power--Macros and Script Files                          83
  151.    ________________________________________________________________________
  152.  
  153.  
  154.    \CH[x]                                                          \CH[127]
  155.    CHaracter.   Sends the ASCII character with code  x  (0..255)  over  the
  156.    modem.    For  example, ASCII 127  represents  the  "Del"  key  on  many
  157.    terminals, so \CH[127]  would  simulate pressing "Del."  ASCII character
  158.    27 is "Escape", so \CH[27] has the same effect as ^[.
  159.  
  160.    \CM
  161.    Change Modem parameters.  This macro calls up  a  menu,  from  which the
  162.    user can change the modem device, speed, or parity.
  163.  
  164.    \CD[x]                                                            \CD[2]
  165.    %MD   %MA   %MN                                                2  3E8  4
  166.    Change Device (serial port).  The \CD macro changes  the  current  modem
  167.    device  to  port  1, 2, 3, or 4, and resets that port.  The %MD variable
  168.    holds the number of the current Modem Device (1..4).  Variable %MA holds
  169.    the memory address of the port in hexadecimal (without the $  sign), and
  170.    %MN holds the IRQ Interrupt line used by the port (2, 3, 4, or 5).
  171.  
  172.    \CS[x]                                                            \CS[1]
  173.    %MS   %MM                                                           1200
  174.    Change  Speed.  This changes the current modem  speed  setting  to  300,
  175.    1200, 2400, 4800, 9600, 19200, or 38400 baud depending on whether  x  is
  176.    3, 1, 2, 4, 9, 0, or 8.  You may also  use  the full number if you wish,
  177.    like \CS[19200].  %MS holds the current baud  rate,  and  %MM  holds the
  178.    Maximum Modem speed as configured in Config Area <S>.
  179.  
  180.    \CP[c]                                                            \CP[E]
  181.    %MP                                                                    E
  182.    Change Parity.  This  changes  the current modem parity setting to None,
  183.    Even,  or Odd depending on whether  c  is N, E, or O.   You may use  the
  184.    full word if you wish, like    \CP[Even].   %MP stores the current Modem
  185.    Parity--N, E, or O (not the full word).
  186.  
  187.    \DD+   \DD-   \DD*
  188.    Drop  DTR.  \DD+ causes the DTR signal to be Dropped upon changing ports
  189.    or exiting BOYAN,  in  effect  hanging  up  the modem.  \DD- makes BOYAN
  190.    maintain the DTR signal when exiting.  \DD* toggles between the two.
  191.  
  192.    \DT+   \DT-   \DT*                                            \DT-~~\DT+
  193.    DTR.   Use \DT+ to turn the Data Terminal Ready signal ON, \DT- to  turn
  194.    DTR OFF, or \DT* to toggle its state.  Turning DTR  off  for  one second
  195.    usually makes the modem hang up.
  196.  
  197.    \HU
  198.    Hang Up.  This hangs up the modem by running BOYAN macro #4.
  199.  
  200.    \PL
  201.    Purge Line.  This purges the data line of all incoming characters; i.e.,
  202.    ignore all incoming characters until the receive buffer is empty.
  203.  
  204.  
  205.    5.2.4:  BOYAN Power--Macros and Script Files                          84
  206.    ________________________________________________________________________
  207.  
  208.  
  209.    \SB
  210.    Send Break.  This sends a modem break signal.
  211.  
  212.    5.2.4  Terminal Characteristics
  213.  
  214.    \AM[]
  215.    \AM[c]                                                            \AM[G]
  216.    Action  Module.   If the space between  the  brackets  is  empty,  BOYAN
  217.    provides  a menu from which you can select a new Action Module.  If  you
  218.    include a character between  the  brackets,  BOYAN  attempts to load the
  219.    Action  Module corresponding to that character: [1]=VT-100,  [G]=GOSSIP,
  220.    etc.
  221.  
  222.    %AM                                                                    G
  223.    Action Module.  The  letter  or digit corresponding to the current BOYAN
  224.    Action Module in use.
  225.  
  226.    %AN                                                               GOSSIP
  227.    Action module Name.  The full name of the current BOYAN Action Module.
  228.  
  229.    %AP                                                                    1
  230.    Action  module (Previous).  The letter or  digit  corresponding  to  the
  231.    previous  BOYAN  Action  Module in use; that is, the module which was in
  232.    use  before  the  current  one  was  selected.    For example, the macro
  233.    \AM[%AP]  would  instruct  BOYAN  to  switch back to the previous action
  234.    module.
  235.  
  236.    \B8+   \B8-   \B8*   %B8
  237.    Bit 8.  The \B8 command controls whether  or  not  BOYAN  recognizes the
  238.    eighth  (high)  bit  of incoming characters.  \B8+ makes BOYAN recognize
  239.    the eighth  bit,  allowing  IBM  graphics  characters  to be seen.  \B8-
  240.    causes BOYAN to strip the eighth bit, converting IBM graphics characters
  241.    to their regular 7-bit  ASCII  equivalents.  \B8* toggles back and forth
  242.    between  the  two  states.  The %B8 variable equals "ON" when the eighth
  243.    bit is allowed, or "OFF" when the eighth bit is stripped.
  244.  
  245.    \BD+   \BD-   \BD*   %BD
  246.    Backspace/Del swap.  Certain terminal  emulation BAMs such as VT-100 and
  247.    IBM-3101 offer an option to swap  the  Backspace  and Del keys.  When in
  248.    such  a  BAM,  you may use the \BD+ macro to  swap  the  keys,  \BD-  to
  249.    "unswap" the keys, \BD* to toggle between \BD+  and  \BD-,  and  the %BD
  250.    variable to reflect whether  BS  and Del are currently swapped ("ON") or
  251.    normal ("OFF").
  252.  
  253.    \BU+   \BU-   \BU*   %BU
  254.    BUffering.  You must have the National Semiconductor  16550AN  UART chip
  255.    to use this command.  The 16550AN provides FIFO  buffering  of  received
  256.    modem  text,  which  makes high-speed downloads reliable  even  under  a
  257.    multitasking or network  environment.   The \BU+ command initializes the
  258.  
  259.  
  260.    5.2.4:  BOYAN Power--Macros and Script Files                          85
  261.    ________________________________________________________________________
  262.  
  263.  
  264.    FIFO  buffer  to its maximum size of  14  bytes,  and  modifies  BOYAN's
  265.    interrupt processing routine appropriately.  \BU-  disables  the buffer,
  266.    and \BU* toggles.  Technical note:  when you shell to DOS or exit BOYAN,
  267.    FIFO  buffering  is restored to the state it was in upon entering BOYAN.
  268.  
  269.    \CT+   \CT-   \CT*
  270.    CTS/RTS.  Use \CT+ to turn  CTS/RTS  hardware  flow control ON,  \CT- to
  271.    turn  CTS/RTS  flow control OFF, and \CT*  to  toggle  between  the  two
  272.    settings.
  273.  
  274.    \EC+   \EC-   \EC*   %EC
  275.    ECho.   \EC+  turns  local  echo ON, \EC- turns local echo OFF, and \EC*
  276.    toggles  back and forth between the two.  The %EC variable can always be
  277.    used to determine the current state  of  echo  mode:  %EC equals "ON" or
  278.    "OFF".
  279.  
  280.    \LF+   \LF-   \LF*   %LF
  281.    Line Feeds.  \LF+ turns add  line  feeds  mode ON, \LF- turns line feeds
  282.    OFF, and \LF* toggles between the two.  %LF maintains the  current state
  283.    of the toggle, "ON" or "OFF".
  284.  
  285.    \TT+   \TT-   \TT*   %TT
  286.    Translation  Table.  \TT+ turns the table ON;  \TT- turns it OFF;   \TT*
  287.    toggles it.   The  %TT  variable  reflects  whether the table is "ON" or
  288.    "OFF".
  289.  
  290.    \XX+   \XX-   \XX*
  291.    Xon/Xoff.   Use \XX+ to turn Xon/Xoff software flow control ON,  \XX- to
  292.    turn Xon/Xoff control OFF, and \XX* to toggle between the two settings.
  293.  
  294.    5.2.5  Backspace Buffer
  295.  
  296.    \BC
  297.    Back destructively over Character.  This command is identical to sending
  298.    a backspace (^H), except  the  deleted character is not added to BOYAN's
  299.    backspace buffer.
  300.  
  301.    \BW+   \BW-
  302.    Back over Word.  This sends backspaces until a space  is  reached.  \BW+
  303.    saves the erased word in the backspace buffer; \BW- does not.
  304.  
  305.    \FC
  306.    Forward Character.  This  sends  the most recent character stored in the
  307.    backspace buffer.
  308.  
  309.    \FW
  310.    Forward Word.  This  sends  characters from the backspace buffer until a
  311.    space is reached.
  312.  
  313.  
  314.    5.2.6:  BOYAN Power--Macros and Script Files                          86
  315.    ________________________________________________________________________
  316.  
  317.  
  318.    5.2.6  Timing
  319.  
  320.    ~    (tilde)
  321.    BOYAN pauses  for approximately 0.5 seconds whenever the tilde character
  322.    is found in a macro.  For long pauses, \PA[x] is a better alternative.
  323.  
  324.    %HR   %MI   %SE                                             18   09   59
  325.    HouR,  MInute,  SEcond.   These variables hold the current hour, minute,
  326.    and second, respectively.  Each is exactly two digits long.  The hour is
  327.    given in 24-hour notation:  i.e., at six o'clock PM,  %HR  equals 18; at
  328.    midnight, %HR equals 00.
  329.  
  330.    %MO   %DA   %YR                                             09   03   92
  331.    MOnth, DAy, YeaR.  Each of these variables is exactly two digits long.
  332.  
  333.    \PA[x]                                                           \PA[20]
  334.    PAuse.  This makes BOYAN pause for x (1..32767) seconds.    See also the
  335.    \AL macro  command,  which  sounds  an  alarm  for a specified number of
  336.    seconds (section 5.2.10).
  337.  
  338.    \PU[##:##]                                                     \PU[2:30]
  339.    Pause Until.   Make  BOYAN  pause  until  the specified time.  The above
  340.    example would make BOYAN wait until 2:30 AM before continuing.   Use 24-
  341.    hour notation to specify  times  after  noon;  e.g., \PU[14:30] to pause
  342.    until 2:30 PM.  Note that midnight = 0:00.
  343.  
  344.    \SL[x]                                                            \SL[0]
  345.    Set  Line pacing to x (0..255) milliseconds.  This is the amount of time
  346.    BOYAN will pause after sending a Carriage Return  in  a  macro  or ASCII
  347.    upload, in addition to the character pacing time.
  348.  
  349.    \SP[x]                                                           \SP[10]
  350.    Set Pacing.  This sets character pacing to x (0..255)  milliseconds, the
  351.    amount  of time BOYAN will pause between sending  each  character  in  a
  352.    macro or ASCII upload.
  353.  
  354.    \UT##:##[macro]                              \UT`20:00[\DM[%HR:%MI:%SE]]
  355.    Until Time.  Until the  specified time (24-hour format), this repeatedly
  356.    executes the enclosed macro.  The above example would display  a running
  357.    clock on the screen until 20:00 (8:00 PM).
  358.  
  359.    5.2.7  Handshaking
  360.  
  361.    \IF+string[macro]                       \IF+End of messages[\GB[LogOff]]
  362.    \IF-string[macro]                  \IF-File not found[\DLk[twiddle.arc]]
  363.    If Found?  The \IF+ command processes the  enclosed  macro  only  if the
  364.    specified  string  is  found  on  the  current  screen  line or the line
  365.    immediately above the cursor.  The \IF- command processes its macro only
  366.    if the string is not on the current line or line above.  The matching is
  367.  
  368.  
  369.    5.2.7:  BOYAN Power--Macros and Script Files                          87
  370.    ________________________________________________________________________
  371.  
  372.  
  373.    not case-sensitive.  Once a given string on the screen is matched, it is
  374.    highlighted  and will not be matched again.  See the related \WF and \UN
  375.    commands.
  376.  
  377.    \IW+[macro]                                \IW+[\DM[Log-on successful!]]
  378.    \IW-[macro]                      \IW-[\DM[Log-on interrupted.]\GB[quit]]
  379.    If  Waitfor  successful?   The \IW+ command processes the enclosed macro
  380.    only If the last WaitFor, UNtil, or IF command was successful.  The \IW-
  381.    command processes the enclosed macro only if the last such command timed
  382.    out before successfully making a match.
  383.  
  384.    \TO[x]                                                           \TO[40]
  385.    TimeOut.   Set the handshake timeout to x (0..255) seconds.  This is the
  386.    amount of time BOYAN waits before "giving up" trying to  match  a \WF or
  387.    \WL  command.  If x is 255, then it means "indefinitely":  \TO[255] sets
  388.    an indefinite timeout, and BOYAN will never give up waiting for a match!
  389.  
  390.    \UNstring[macro]                                     \UN`End of file[^K]
  391.    UNtil.   This repeatedly executes the macro  enclosed  in  the  brackets
  392.    until the specified string arrives from the modem.   The  above  example
  393.    sends a continuous stream of control-K characters until  BOYAN  sees the
  394.    "End of file"  message.
  395.  
  396.    \WF[]                                                              \WF[]
  397.    \WF[string]                           \WF[Enter your name:]John Johnson{
  398.    Wait For the specified string to arrive from the modem.    If 30 seconds
  399.    (or  whatever value you configure or set with the  \TO  command) elapses
  400.    before the string appears, the macro times out and will continue  to the
  401.    next command.  The string is  not  case-sensitive,  so  NAME  will match
  402.    NaMe .   If  the  brackets  are  empty,  BOYAN  will simply wait for any
  403.    character.  While  BOYAN  is  waiting,  if you press <space>, BOYAN will
  404.    assume the matching was unsuccessful and continue to  the  next command.
  405.    (Pressing <Esc> always aborts the entire macro/script.)  You can use the
  406.    \IW  command to test for the success  of  the  waitfor  (section 5.2.7).
  407.    See also the \UN (until) and \IF (if found) commands.
  408.  
  409.    \WL                                                                  \WL
  410.    Wait for a new Line (carriage return) from the modem.
  411.  
  412.    \WP[x]                                                           \WP[2]{
  413.    Wait  for Pause.  This command instructs BOYAN to Wait for a Pause of  x
  414.    seconds in the remote  system's  input.  Suppose you execute the command
  415.    \WP[2].  As long as input continues to flow in from the modem, the macro
  416.    will  simply  wait.    However,  when  there is a pause in the  flow  of
  417.    input--in this case, two seconds during which nothing  new  arrives from
  418.    the modem--the \WP[2] command will  finish, and the macro processor will
  419.    continue on to the next command.  In effect, \WP[2] makes BOYAN wait for
  420.    the next prompt for input!  See the TCOMM.BSC script for details.
  421.  
  422.  
  423.    5.2.8:  BOYAN Power--Macros and Script Files                          88
  424.    ________________________________________________________________________
  425.  
  426.  
  427.    5.2.8  Dialing
  428.  
  429.    \AD+   \AD-   \AD*
  430.    Auto-Detect.  Use \AD+ to turn auto-detection of the modem connect speed
  431.    ON,  \AD- to turn Auto-Detection  OFF,  and   \AD* to toggle between the
  432.    two.  This feature is explained in section 3.8.
  433.  
  434.    \CC+   \CC-   \CC*
  435.    Carrier Checking.  \CC+ enables BOYAN's carrier checking before dialing.
  436.    With carrier checking enabled,  BOYAN  will prompt you to verify that it
  437.    is "OK  to  dial  despite  carrier" if you try to dial while already on-
  438.    line.  \CC- disables carrier checking; \CC* toggles.
  439.  
  440.    \CO[x]                                                           \CO[60]
  441.    COnnect timeout.  Set the COnnect wait time to x seconds (0..99).  After
  442.    dialing with <Alt-D>, BOYAN will assume that no connection has been made
  443.    if the modem fails to respond within this amount of time.
  444.  
  445.    \DI[]                                                              \DI[]
  446.    \DI[x]                                                           \DI[12]
  447.    \DI[string]                                              \DI[Compuserve]
  448.    \DI[###-####]                                              \DI[381-6441]
  449.    DIal.    If the brackets are empty,  \DI[]  simply  enters  the  dialing
  450.    directory.  If a number from  1-200  is enclosed, this command dials the
  451.    system  with  the  specified  dialing  directory  code;  if you  make  a
  452.    connection, the appropriate automatic logon script will also be run (see
  453.    section 5.5.2).  If a string is enclosed, BOYAN will search your dialing
  454.    directory for an  entry  whose  name  contains that string, and dial the
  455.    first such entry it finds.    (This  may  be  preferable  to  giving the
  456.    precise  code  number,  since  the  code  may  change  if  you sort  the
  457.    directory.)  Finally, if  the  string does not match any directory entry
  458.    name, BOYAN attempts to manually dial the enclosed string.
  459.  
  460.    %F:                                                        C:\BOYAN\FON\
  461.    Fon  path.   This variable stores the name of the path  in  which  BOYAN
  462.    expects to find all its FON directories.  To reconfigure this  path, see
  463.    section 3.6.
  464.  
  465.    \FD[filename]                                           \FD[CHICAGO.FON]
  466.    %FD                                                          CHICAGO.FON
  467.    Fon  Directory.   The \FD macro command  loads  the  specified  new  Fon
  468.    Directory.  The filename suffix of  .FON  is  optional.  If the file you
  469.    specify is not a valid BOYAN directory, the previous .FON directory will
  470.    be  reloaded.  The name of the current FON directory is always stored in
  471.    the %FD variable.
  472.  
  473.  
  474.    5.2.8:  BOYAN Power--Macros and Script Files                          89
  475.    ________________________________________________________________________
  476.  
  477.  
  478.    \IS+x,y,..,z[macro]              \IS+1,6,114,0,3,30[password1|password2]
  479.    \IS-x,y,..,z[macro]                      \IS-0[\DM[Phone number = %SF.]]
  480.    Is  System?    The \IS+ command processes the enclosed macro only If the
  481.    directory  code of the System you last dialed is on the list of numbers.
  482.    The \IS- command processes its macro when the last-dialed system  is not
  483.    on the code list.   The  codes  run  from  1-200  for  dialing directory
  484.    entries, and 0 for manual dialing.  This command is convenient when, for
  485.    example, you use different passwords on otherwise-identical systems, and
  486.    need to select a password based on which system you connected to.
  487.  
  488.    %PW                                                               ibm-pc
  489.    %S#                                                                   12
  490.    %SF                                                       1-301-854-3076
  491.    %SN                                                    BOYAN Support BBS
  492.    %SS                                                              PCBOARD
  493.    %SL                                                              0:15:30
  494.    System information.   These  six variables contain information about the
  495.    system  which  is  currently online.  If you are online  with  a  system
  496.    dialed from the dialing directory:  %PW equals its password;  %S# equals
  497.    its code number  (1-200);  %SF  equals  its phone number; %SN equals its
  498.    Name; %SS equals the name of its logon  script  file  (without  the .BSC
  499.    suffix);  and %SL is the total elapsed time  since  the  connection  was
  500.    made.  These values can be used in Auto-macros #6  and  #7, for example,
  501.    to update the BOYAN.USE activity log.  When you are offline,  %PW equals
  502.    the default value set in Config  Area  <S>;  %S# equals 0, the %SL clock
  503.    keeps running, and the other variables are blank.
  504.  
  505.    5.2.9  Queue Redialing
  506.  
  507.    \QA[x]                                                           \QA[12]
  508.    \QA[###-####]                                              \QA[381-6441]
  509.    \QA[string]                                           \QA[Boyan Support]
  510.    \QA+[string]                                         \QA+[Boyan Support]
  511.    Queue Add.  If a number  from  1-200  is enclosed, this command adds the
  512.    system with the specified dialing directory code to the redialing queue.
  513.    Otherwise, BOYAN searches the dialing  directory for an entry whose name
  514.    contains string, and adds that entry to the  Queue.    If  a + is placed
  515.    before the left bracket, then all matching entries will be added  to the
  516.    queue; with no +, only the first matching entry is added.  If the string
  517.    in brackets  is  not  an  entry name but a phone number, then BOYAN will
  518.    simply add that number to the queue.
  519.  
  520.    \QA-[x]                                                         \QA-[12]
  521.    \QA-[string]                                                   \QA-[%SN]
  522.    Queue  Subtract.   If a number from  1-200  is  enclosed,  this  command
  523.    deletes  the entry with that code number from the redialing queue.  If a
  524.    string is enclosed,  then  all  queue  entries  whose  names  are "close
  525.    enough" to that string are removed  from  the  queue.  To BOYAN, a queue
  526.    name is  "close  enough"  to  the  specified  string if that string, not
  527.  
  528.  
  529.    5.2.9:  BOYAN Power--Macros and Script Files                          90
  530.    ________________________________________________________________________
  531.  
  532.  
  533.    including its last character,  is  contained as a substring of the queue
  534.    name.  For example,  the  command \QA-[BOYAN Support Line 2] will delete
  535.    queue entries named BOYAN  Support  Line 1  and  BOYAN Support Line 3 as
  536.    well  as BOYAN Support Line 2.  If you insert the command \QA-[%SN] into
  537.    Auto-macro  #6, then after connecting to a  system,  all  other  systems
  538.    whose  names  are  "close enough" will automatically be deleted from the
  539.    queue.
  540.  
  541.    \QC
  542.    Queue Clear.  Clear the queue of all entries.
  543.  
  544.    \QD
  545.    Queue Dial.  This makes BOYAN  repeatedly  dial the numbers in the queue
  546.    until a connection is made.  When BOYAN connects, it removes that number
  547.    from the queue and rings the connect alarm.  If the connected system has
  548.    a logon script specified  in  its  Dialing  Directory entry, BOYAN stops
  549.    ringing the alarm after the "Script Keyboard Timeout"  has  expired, and
  550.    runs the script's LOGON block as described in  section  5.5.2.    If the
  551.    queue is empty, this command does nothing.
  552.  
  553.    \QE
  554.    Queue Enter.  The \QE command causes BOYAN to enter the  redialing queue
  555.    and wait for user key commands.
  556.  
  557.    %QS                                                 \IE+%QS,0[\EX | \QD]
  558.    Queue Size.  The number of  entries  in  the Queue (0..20).  The example
  559.    macro  will  exit  BOYAN if the queue is empty, or begin queue redialing
  560.    otherwise.
  561.  
  562.    \QU[##:##]                                                     \QU[6:15]
  563.    Queue Until.  This command is identical to the \QD command,  except that
  564.    redialing will stop at the specified time if no connection has been made
  565.    yet.  Use 24-hour notation, e.g., \QU[23] to redial until 11:00 pm.  See
  566.    section  5.3.2  for an example of how to use this command  in  an  Auto-
  567.    macro.
  568.  
  569.    5.2.10  Screen & Sound
  570.  
  571.    \ALx[y]                                                          \AL1[5]
  572.    \ALx[0]                                                          \AL3[0]
  573.    \ALx[]                                                            \AL2[]
  574.    ALarm.  BOYAN provides three alarms: alarm #1 is a constant  tone; alarm
  575.    #2 is a two-tone "ringing"; and  alarm  #3  is a descending squawk.  The
  576.    pitch of the alarm is controlled by the alarm  volume  setting  (below).
  577.    The \ALx command rings alarm # x (1, 2, or 3).  The number y (0..255) in
  578.    brackets determines the  length of the alarm in seconds.  If y is 0, the
  579.    alarm tone sounds just once, and stops.  If the brackets are left empty,
  580.    then the alarm will ring continuously until the user presses a key.
  581.  
  582.  
  583.    5.2.10:  BOYAN Power--Macros and Script Files                         91
  584.    ________________________________________________________________________
  585.  
  586.  
  587.    \AV[x]                                                            \AV[4]
  588.    Alarm  Volume.   Change the alarm volume from 1 to 10,  or  silence  all
  589.    alarms with 0.
  590.  
  591.    \BB+   \BB-   \BB*   %BB                                      \AV[0]\BB-
  592.    Beeps  &  Bells.   \BB+ turns Beeps & Bells mode ON;  \BB- turns it OFF;
  593.    and  \BB*  toggles between the two states.  The %BB variable equals "ON"
  594.    or  "OFF"  as  appropriate.    The  example  macro above can be used  to
  595.    completely silence all BOYAN sound effects.
  596.  
  597.    \DMC[x]                                                        \DMC[240]
  598.    %DM                                                                  240
  599.    Display Message Color.    Set  the  Display Message Color to x (1..255).
  600.    This  color  will  be  used  for messages displayed with subsequent  \DM
  601.    commands.  Note that numbers greater than 128 are flashing; for example,
  602.    select  color  240  for flashing black on white.  The %DM variable holds
  603.    the Display Message color.
  604.  
  605.    \DM[string]                                     \DM[You have connected!]
  606.    \DMx,y[string]                                 \DM40,10[Menu of Options]
  607.    \DMy[string]                         \DM1[This message is in color %DM.]
  608.    \DMx,[string]                           \DM30,[The time is now %HR:%MI.]
  609.    Display Message.  The \DM command  is  used  to display a message on the
  610.    screen.  The string will  be  displayed  at  column  x  (1..80),  line y
  611.    (1..24).   If  either  x  or y is omitted before the string in brackets,
  612.    then BOYAN substitutes default  values.   If x is omitted, BOYAN flushes
  613.    the string to the right  of the screen.  If y is omitted, BOYAN uses the
  614.    line above the  current  cursor  position.   In the examples above, "You
  615.    have connected" is flushed right on the line above the cursor;  "Menu of
  616.    Options" is at column 40, row 10;   "This  message  is  in color ###" is
  617.    flushed right on line 1;  and "The time is now ##:##" is at column 30 on
  618.    the line above  the cursor.  \DM can be used in conjunction with the \KV
  619.    command to make user menus, for example (see section 5.2.14).
  620.  
  621.    \GL+   \GL-   \GL*   %GL
  622.    Grab screen  Lines  (EGA/VGA  monitors  only).    \GL+ loads the 8x8 ROM
  623.    screen font, causing an EGA adapter to display 43 lines of text or a VGA
  624.    adapter  to  display  50 lines of text.  \GL- restores a 25-line screen.
  625.    \GL* toggles between \GL+ and \GL-.    The variable %GL always holds the
  626.    current number of lines displayed (25, 43, or 50).
  627.  
  628.    \GX[x]                                                           \GX[40]
  629.    Goto  X-position.    This moves the cursor horizontally to the specified
  630.    column (1..80).
  631.  
  632.    \GY[y]                                                           \GY[20]
  633.    Goto Y-position.  This moves the cursor vertically to the  specified row
  634.    (1..24).
  635.  
  636.  
  637.    5.2.10:  BOYAN Power--Macros and Script Files                         92
  638.    ________________________________________________________________________
  639.  
  640.  
  641.    \KS   \RS
  642.    Keep  Screen,  Restore  Screen.    These commands are useful for  making
  643.    user-defined "pop-up" menus.  \KS does several things:  it saves  a copy
  644.    of  the  top 24 lines of the screen into memory; it  saves  the  current
  645.    cursor position; and it  temporarily  inhibits  all  I/O from the modem.
  646.    After  \KS,  you  could  clear  the  screen  (with  \ZS) or display menu
  647.    messages (with \DM).  When you  want  to Restore the Screen contents and
  648.    cursor  position,  use  the \RS macro.  Note:  BOYAN restores the screen
  649.    automatically, even without \RS, if either 1) you invoke a command which
  650.    needs to save the  screen  (e.g., Dialing Directory or a file transfer),
  651.    or 2) you abort the macro/script by pressing <Esc>.
  652.  
  653.    \MC[x]                                                          \MC[112]
  654.    %MC                                                                  112
  655.    Menu Color.  \MC[x] sets the Menu and help screen  Color  to x (1..127).
  656.    The %MC variable holds the current Menu Color in use.
  657.  
  658.    \NC[x]                                                            \NC[7]
  659.    %NC                                                                    7
  660.    Normal Color.  \NC[x] sets the Normal text Color to x (1..127).  The %NC
  661.    variable holds the current Normal text Color in use.
  662.  
  663.    \RC
  664.    Restore Color.  This command Restores the default normal text Color.
  665.  
  666.    \RX[x]                                                          \RX[-10]
  667.    Relative  X-position.    This  moves  the  cursor  horizontally  by  the
  668.    specified number  of  spaces,  backward  (negative  numbers)  or forward
  669.    (positive numbers).  The cursor will not go  beyond  either  end  of the
  670.    line.
  671.  
  672.    \RY[y]                                                            \RY[5]
  673.    Relative Y-position.  This moves  the cursor vertically by the specified
  674.    number of lines, up (negative numbers) or down (positive numbers).   The
  675.    cursor will not go beyond either end of the screen.
  676.  
  677.    \SN[string]                                                     \SN[%SN]
  678.    System Name status.  This displays the string on the  right  side of the
  679.    status line, where the current System Name is normally displayed.
  680.  
  681.    \ST[string]                              \ST[Beeps & Bells are now %BB.]
  682.    STatus.  This displays the string on the left side  of  the status line.
  683.    This sample  macro  displays  the  current  status  of the Beeps & Bells
  684.    toggle.
  685.  
  686.    %XP   %YP
  687.    X-Position,  Y-Position.    These  variables  equal  the  current column
  688.    (1..80) and row (1..24) of the cursor, respectively.
  689.  
  690.  
  691.    5.2.11:  BOYAN Power--Macros and Script Files                         93
  692.    ________________________________________________________________________
  693.  
  694.  
  695.    \ZS
  696.    "Zaps" (clears) the Screen.
  697.  
  698.    5.2.11  Session Logging & Printing
  699.  
  700.    \LD+   \LD-   \LD*   %LD   %LN       \LD*\ST[Logging to %LN is now %LD.]
  701.    \LD+[filename]                                  \LD+[C:\%MO-%DA-%YR.LOG]
  702.    Log to Disk.    \LD+ opens a log file.  If no filename is specified, the
  703.    default (or most recently-used log file) is used.  Opening the  log file
  704.    runs  Auto-macro  #14,  which inserts a header with the date and time in
  705.    the  file.    While  the  log  file is open, all text appearing  on  the
  706.    communication screen is saved to the file.   \LD-  closes  the  open log
  707.    file;   \LD* toggles logging ON and OFF.  The %LD variable maintains the
  708.    status of the log file as "ON" or "OFF".  %LN holds the full name of the
  709.    last log file opened, or the  default  BOYAN.LOG if none has been opened
  710.    yet.  In the second example above, the date variables are used to open a
  711.    log file with the date in the filename; for example, on November fourth,
  712.    the filename used would be C:\11-04-91.LOG.
  713.  
  714.    \LM[string]                                  \LM[== Connected to %SN ==]
  715.    Log Message.  This inserts  a  message  in  the  log file if the file is
  716.    open.  If you include the example macro above in your Connect Auto-macro
  717.    #6, then whenever you connect to a system while the log  file  is  on, a
  718.    line with that system's name will be added to the log.
  719.  
  720.    \PM[string]                    \PM[== Connected to system number %S# ==]
  721.    Print  Message.    This command prints  the  specified  string  on  your
  722.    printer.   You can use this command to  set  up  printer  initialization
  723.    codes; for example, \PM[^X^[g] sends <Ctrl-X>,<Escape>,<g>.
  724.  
  725.    \PP[x]                                                            \PP[2]
  726.    Printer Port.  Select a new device (1, 2, 3, or  4)  for  all subsequent
  727.    printing.
  728.  
  729.    \PR+   \PR-   \PR*   %PR
  730.    PRinter.  \PR+ turns printer log mode on.    If  used  in a script file,
  731.    printer  logging  starts  immediately;  otherwise, BOYAN's printer setup
  732.    menu is displayed.  All text appearing on the  communication  screen  is
  733.    printed until  printer  logging  is  turned  off  by \PR-.  \PR* toggles
  734.    printer logging; %PR equals "ON" or "OFF" as appropriate.
  735.  
  736.    \PS
  737.    Print Screen.  This is identical to keying <Shift-PrtSc> by hand.
  738.  
  739.    \SS   %DN
  740.    Save Screen to disk.  This command saves the current screen to the BOYAN
  741.    screen dump  file  (see  section  3.6).  The Dump file Name is stored in
  742.    variable %DN.
  743.  
  744.  
  745.    5.2.11:  BOYAN Power--Macros and Script Files                         94
  746.    ________________________________________________________________________
  747.  
  748.  
  749.    \UF+   \UF-   \UF*   %UF                    \UF*\ST[Usage file now %UF.]
  750.    \UF+[filename]   %UN                                  \UF+[LONGDIST.USE]
  751.    Usage File.    \UF+  and  \UF- turn the BOYAN.USE usage file on and off,
  752.    respectively.  If a filename is specified after the \UF+  command, BOYAN
  753.    will use that filename for the usage file.  \UF* toggles the usage file,
  754.    and the %UF variable holds its current status, "ON" or "OFF".  %UN holds
  755.    the full Name of the current Usage file.
  756.  
  757.    \UM[string]                             \UM[Current DOS directory = %C:]
  758.    Usage Message.    This  command  enters a line into the usage file.  The
  759.    date and time are  automatically  appended to the beginning of the line,
  760.    in whatever format  you specify (see section 3.6).  To add a line to the
  761.    usage file without  the  date/time prefix, use the command \AF%UN[..your
  762.    msg  here..] instead.  If the Usage File is OFF, the \UM command has  no
  763.    effect.  The example above would add a line to the end of the usage file
  764.    showing the current DOS path.
  765.  
  766.    5.2.12  DOS
  767.  
  768.    \AFfilename[string]      \AF`LETTER.TXT[This file is dated %MO/%DA/%YR.]
  769.    Append to text File.  This very powerful command allows scripts to build
  770.    custom  text files.  The string is appended to the end of the text  file
  771.    specified by filename.  If that  file  does not exist, BOYAN creates it.
  772.    The Host Mode script uses this command to create a  message  file as the
  773.    message is being typed.  See  also  the  \GV command (for reading from a
  774.    text file).
  775.  
  776.    %B:                                                            D:\BOYAN\
  777.    BOYAN path.  This variable holds the BOYAN home directory's drive+path.
  778.  
  779.    %C:                                                                  A:\
  780.    Current  path.    This  variable  holds  the  current  disk  directory's
  781.    drive+path.
  782.  
  783.    \CF+   \CF-   \CF*
  784.    Check Free.   \CF+  tells  BOYAN  to automatically check free disk space
  785.    before each download and within the directory file manager.   \CF- means
  786.    you must manually press <Alt-F> in  the  download  menu or F in the file
  787.    manager to see remaining disk space.  \CF* toggles.
  788.  
  789.    \DC[string]                                      \DC[pkunzip -v boyan5a]
  790.    \DC-[string]                                             \DC-[dir >prn:]
  791.    \DC+[string]                                              \DC+[type %DN]
  792.    DOS  Command.    BOYAN  invokes  the  COMMAND.COM  processor to  execute
  793.    [string]  as  a DOS command.  If you use the \DC-  command,  BOYAN  will
  794.    continue immediately after the  DOS  command  finishes.   With \DC+, you
  795.    will  be  prompted  for a keypress before returning to BOYAN.  The plain
  796.    \DC command (with no minus) usually prompts for a keypress, but does not
  797.    if there is a script file running.
  798.  
  799.  
  800.    5.2.12:  BOYAN Power--Macros and Script Files                         95
  801.    ________________________________________________________________________
  802.  
  803.  
  804.    %DR                                                                    A
  805.    DRive.  This variable holds the currently-logged disk drive letter.
  806.  
  807.    %DS                                                                  125
  808.    DOS Shell  space.    This  variable  equals  the amount of memory (in K)
  809.    available  for  DOS  Shells.    If  %DS equals 0, then the \JD  and  \DC
  810.    commands cannot function.
  811.  
  812.    \FE+filename[macro]           \FE+c:\files\twiddle.arc[\UL[twiddle.arc]]
  813.    \FE-filename[macro]              \FE-boyan5a.zip[\DC[pkzip boyan5a *.*]]
  814.    File Exists?   With  the  \FE+  command, the enclosed macro is processed
  815.    only if the specified file  exists  on  your  disk.    The  \FE- command
  816.    processes the enclosed macro only if the specified file does not already
  817.    exist.
  818.  
  819.    \FM[filespec]                                              \FM[c:\util\]
  820.    \FMc[filespec]                                                    \FMU[]
  821.    \FMstring[filespec]                             \FM`pkunzip -v[%D:*.ZIP]
  822.    The File Manager.  Within the brackets, specify the path and/or wildcard
  823.    pattern of files to display, or leave the brackets empty to  display all
  824.    files  in the current directory.  There are also two ways to specify the
  825.    File Manager "default command", which is the the  command  selected when
  826.    you press <Enter> or double-click the mouse on a filename:
  827.  
  828.       1.  Between \FM and [filespec], include a single letter (any of C D E
  829.           F  I  L  M R S U V W).  The File Manager command corresponding to
  830.           that letter will become the default command.  For example, \FMU[]
  831.           invokes the File Manager in  the current directory with Upload as
  832.           the default command.
  833.  
  834.       2.  Between \FM and [filespec],  include  a  DOS  command two or more
  835.           characters long.  The File  Manager default will then invoke that
  836.           DOS command, giving it the name(s) of the selected file(s) as its
  837.           argument.    The  "pkunzip  -v"  example above invokes  the  File
  838.           Manager  on  all  *.ZIP files in your Download directory; to view
  839.           the contents of a .ZIP file, you would simply highlight that file
  840.           and press <Enter>.
  841.  
  842.    \FS[c]                                                          \FS[%DR]
  843.    Free Space.  This displays a status message showing the number  of bytes
  844.    of free space on the specified disk drive.
  845.  
  846.    \JD                                                            \AT+[\JD]
  847.    Jump to DOS.    You must type EXIT <Enter>  to return to BOYAN from DOS,
  848.    so be sure this command is not processed when BOYAN is unattended.
  849.  
  850.  
  851.    5.2.12:  BOYAN Power--Macros and Script Files                         96
  852.    ________________________________________________________________________
  853.  
  854.  
  855.    %LC                                                                 TYPE
  856.    List Command.  This  variable  holds the DOS command you have configured
  857.    for  viewing a file.  For example, to view the BOYAN.USE file, you would
  858.    run the \DC[%LC boyan.use] macro.
  859.  
  860.    \ND[string]                                             \ND[b:\download]
  861.    New Directory.  This command selects a new default disk drive or path.
  862.  
  863.    %S:                                                     D:\BOYAN\SCRIPT\
  864.    Script path.  This variable holds BOYAN's script file disk drive+path.
  865.  
  866.    %SC                                                             HOST.BSC
  867.    SCript.  This variable holds the name of the current script file running
  868.    (or the last script file run, if none is active).
  869.  
  870.    %WC                                                                EDLIN
  871.    Word processor Command.  This variable holds the DOS  command  you  have
  872.    configured for editing a file.
  873.  
  874.    5.2.13  File Transfers
  875.  
  876.    \AU+   \AU-   \AU*   %AU           \AU* \ST[Auto-downloading is now %AU]
  877.    AUto-downloading.  \AU+ enables  auto-downloading,  \AU-  disables, \AU*
  878.    toggles between the two.  %AU maintains the current state of the toggle,
  879.    "ON" or "OFF".
  880.  
  881.    %D:                                                         C:\MODEM\DL\
  882.    %U:                                                                  B:\
  883.    Download  path,  Upload path.  These variables  hold  the  name  of  the
  884.    default download and upload directories, respectively.
  885.  
  886.    \DLc-[filename]                                    \DLY-[c:\twiddle.zip]
  887.    DownLoad.  The  \DL  command  offers  three parameters, all of which are
  888.    optional:
  889.  
  890.       1.  The first parameter is a  letter or digit specifying the protocol
  891.           to  use for the download.  The letter should be the same one used
  892.           in the protocol menu,  e.g.,  X=Xmodem, K=Kermit, etc.  If you do
  893.           not specify  a protocol letter, the current default protocol will
  894.           be used.  Example: \DLY[] would invoke the  Download  Window with
  895.           Ymodem as the default protocol selection.
  896.  
  897.       2.  The second parameter is an optional - minus sign.  If you include
  898.           the minus sign, then BOYAN  will bypass its Download Window where
  899.           you confirm the  protocol,  path, and filename; the download will
  900.           begin immediately.  Example:    \DL-[]  is used in Auto-macro #12
  901.           so that auto-downloads start without any keypresses on your part.
  902.  
  903.  
  904.    5.2.13:  BOYAN Power--Macros and Script Files                         97
  905.    ________________________________________________________________________
  906.  
  907.  
  908.       3.  The  third  parameter,  enclosed in brackets, is the full name of
  909.           the file to download.  You may also specify a  path  only (but no
  910.           filename), or leave the brackets empty.  If you do not  specify a
  911.           filename, BOYAN will use its automatic  filename-find  feature to
  912.           determine the  name.    (Some  external  protocols  determine the
  913.           filename automatically,  in which case you may leave the brackets
  914.           empty.)    If you do not specify  a  filename  and  BOYAN  cannot
  915.           determine  the name from the screen, BOYAN  will  name  the  file
  916.           FILE####.BDL, where #### is  the  time  of  day when the download
  917.           started.    Examples:    \DL-[twiddle.zip] will immediately begin
  918.           downloading twiddle.zip  into  your  default  Download directory.
  919.           \DL[%S:] will direct  a  download to your BOYAN script directory,
  920.           prompting you for the filename.
  921.  
  922.    \DP[c]                                                            \DP[K]
  923.    %DP                                                                    K
  924.    Default Protocol.  This sets the default file transfer  protocol.    Put
  925.    the  first  letter  of the protocol (A, C, K, X,  Y,  Z,  etc.)  in  the
  926.    brackets.  The current  default  protocol's  letter  is always stored in
  927.    variable %DP.
  928.  
  929.    \IP+c[macro]                                      \IP+K[\DLK[] | \DLX[]]
  930.    \IP-c[macro]                           \IP-Z[\DM[Zmodem not installed.]]
  931.    If  Protocol  available?   The \IP+ command processes the enclosed macro
  932.    only If the Protocol specified by the character  c  is  available.   The
  933.    first example above performs a Kermit download if the Kermit protocol is
  934.    available, or an Xmodem download  otherwise.  The \IP- command processes
  935.    the enclosed macro only if the specified protocol is not available.
  936.  
  937.    \IT+[macro]                 \DLy[]\IT+[\DM[Ymodem download successful.]]
  938.    \IT-[macro]                   \ULk[boyan5a.zip]\IT-[\DM[Upload failed.]]
  939.    If Transfer successful?  The \IT+ command processes  the  enclosed macro
  940.    only If the most recent file Transfer completed successfully.   The \IT-
  941.    command processes its macro only if the last transfer was unsuccessful.
  942.  
  943.    %P:                                                   D:\BOYAN\EXTPROTS\
  944.    Protocol  path.   This variable holds the  full  name  of  the  external
  945.    protocol program path, configured in Configuration Area <D>.
  946.  
  947.    %T:                                                         C:\MODEM\DL\
  948.    %TF                                                          TWIDDLE.ARC
  949.    Transfer path, Transfer Filename.    The %T: variable stores the name of
  950.    the most recent directory selected for  a  file transfer;  %TF holds the
  951.    name of the file most recently selected to be transferred.
  952.  
  953.    %TI                  Ymodem DL: ALLFILES.ARC     44,160 0:04:36    67.4%
  954.    Transfer  Information.     After   a  file  transfer,  BOYAN  builds  an
  955.    information string  like  the  one  above.    The string consists of the
  956.    protocol used, UL or  DL,  filename,  file  size, transfer duration, and
  957.  
  958.  
  959.    5.2.13:  BOYAN Power--Macros and Script Files                         98
  960.    ________________________________________________________________________
  961.  
  962.  
  963.    efficiency  percentage.    If  the  transfer is unsuccessful,  the  word
  964.    (FAILED) follows the filename.  This string can be included in the usage
  965.    log, for example, as in Auto-macro #8 ("After a file transfer").
  966.  
  967.    %UD                                                                   UL
  968.    UpLoad or DownLoad?   This variable holds "UL"  after an upload or  "DL"
  969.    after a download.
  970.  
  971.    \ULc-[filename]                         \UL-[c:\modem\files\twiddle.arc]
  972.    UpLoad.  The use of this command, UpLoad file, is  analogous  to the use
  973.    of the  \DL  command.  The protocol letter (c), minus sign, and filename
  974.    parameters  are  all  optional.  If  BOYAN  cannot  find  the  file  for
  975.    uploading, however, the upload will be aborted.
  976.  
  977.    \WW+   \WW-   \WW*
  978.    Word Wrap.  \WW+ enables, \WW- disables, and \WW* toggles  the automatic
  979.    word wrap handling feature of message uploads.
  980.  
  981.    5.2.14  User Variables
  982.  
  983.    %V0   %V1  ...  %V9
  984.    %VA   %VB  ...  %VZ
  985.    These  36  user-definable  variables,  along  with  the  following macro
  986.    commands, give the macro  language  enormous power.  A user variable can
  987.    hold a string, a number, or a macro.
  988.  
  989.    \DVc[x]                                             \II+;,%V0[\DV0[%II]]
  990.    Deletes the leading x characters from the specified user Variable.   For
  991.    example,  \SV0[Justin] \DV0[3]  results  in %V0 being set to "tin".  The
  992.    more complicated example above has the effect of deleting all characters
  993.    up to the first semicolon in %V0.  Combined with  the  \LV command, this
  994.    command  lets  you  pick out any substring from within a variable.  (See
  995.    HOST.BSC for many examples.)
  996.  
  997.    \GVc[filename]                    \RE[ \GV5[FOO.DOC] %V5{ \IV5+^Z[\EM] ]
  998.    \GVc[]                                                            \GV5[]
  999.    Get Variable from file.  This  command  reads  from an ASCII file into a
  1000.    user variable.  Each  successive  call  to  \GV1[foo.txt] reads one more
  1001.    line  from  the  specified file foo.txt.    If  you  switch  to  another
  1002.    filename, e.g., \GV3[bar.doc], then foo.txt will be closed and the first
  1003.    line of bar.doc  will  be read.  When you reach the end of the file, the
  1004.    user  variable will contain the control-Z (EOF)  marker.    The  example
  1005.    given above actually  performs  an  ASCII  upload of FOO.DOC:  the macro
  1006.    repeatedly gets a line of text from FOO.DOC into %V5,  then  sends %V5 +
  1007.    <CR> over the modem, and checks to see if the ^Z marker was reached.  It
  1008.    is a good idea to close any files opened this way  by  using  the \GVc[]
  1009.    command.
  1010.  
  1011.  
  1012.    5.2.14:  BOYAN Power--Macros and Script Files                         99
  1013.    ________________________________________________________________________
  1014.  
  1015.  
  1016.    \IVc+string[macro]               \IV5+secret[Welcome! | Wrong password.]
  1017.    \IVc-string[macro]                           \IV0-[\DM[Input accepted.]]
  1018.    If Variable equals?    The  \IV  command tests whether variable c equals
  1019.    string.    \IVc+string[macro]   is   actually   just   a   shortcut  for
  1020.    \IE+%Vc,string[macro] , and similarly with  \IVc-.    The  first example
  1021.    sends  the  "Welcome!"  message  if  %V5 equals "secret", or the  "Wrong
  1022.    password" message otherwise.    The  second  example tests to see if %V0
  1023.    equals the  empty  string--that  is,  if %V0 is empty.  If not, then the
  1024.    "Input accepted" message is displayed.
  1025.  
  1026.    \KVc[string]                                       \KV0[Your selection?]
  1027.    \KVcstring1[string2]                 \KV8%DR[New disk drive: ] \ND[%V8:]
  1028.    Keyboard Variable.   This  command  lets  you  make  BOYAN's  macros and
  1029.    scripts interactive.  BOYAN prompts you for keyboard input on the status
  1030.    line; what you  type is stored in variable c.  The string in brackets is
  1031.    the prompt; e.g., the first example above prompts the  user  with  "Your
  1032.    selection?".    You can specify a default  response  to  the  prompt  by
  1033.    placing another string  before  the  first  left  bracket.    The second
  1034.    example above uses  the  %DR  variable  to make the default response the
  1035.    current  drive letter; it then uses the \ND command to change to the new
  1036.    drive letter typed by the user.  Note:  when responding to a \KV prompt,
  1037.    you  must  press  <Enter> after typing your response, unless the default
  1038.    response is one character long.  If the  default  response  is  a single
  1039.    character, BOYAN expects a keyboard  response of only one character, and
  1040.    does not require you to press <Enter>.   In  the  second  example above,
  1041.    since the current  drive  letter  %DR  is always just one character, the
  1042.    user does not have to press <Enter> after responding.
  1043.  
  1044.    \LVc[x]                                                 \SV1[%B:]\LV1[2]
  1045.    \LVc[]   %LV                          \LV5[]  \ST[Length of %V5 is %LV.]
  1046.    Length of Variable.  This command allows your macros  to  perform  basic
  1047.    string manipulation.  If a numeric argument x  is  given,  \LV  sets the
  1048.    length of variable c to be exactly x (0..80)  characters,  padding  with
  1049.    spaces  if needed.  In the first example above, %V1 is set to the  BOYAN
  1050.    directory (e.g. "C:\BOYAN"),  and  then truncated down to two characters
  1051.    so  %V1 = "C:".  The %LV variable holds the new length of the  variable.
  1052.    If  no  argument  is enclosed in the brackets, then the  length  of  the
  1053.    string is left unchanged.  The second example above demonstrates  how to
  1054.    find the length of a variable's contents without changing the variable.
  1055.  
  1056.    \RVc[y]                                 Please type your name:  \RV1[30]
  1057.    \RVc*[y]                           Please type your password:  \RV2*[20]
  1058.    \RVc-[y]                                       \WF[Time left:] \RVT-[20]
  1059.    \RVc+[y]                                                       \RVL+[70]
  1060.    Read Variable.  This command is used to read input  from  the modem into
  1061.    user variable c.  Up to y characters are accepted, and the entry must be
  1062.    terminated by a <Return>.   Backspacing is allowed and handled properly.
  1063.    With  the * parameter, BOYAN echoes asterisks  rather  than  the  actual
  1064.    typed text back to the  modem.    With  the  -  parameter,  BOYAN echoes
  1065.  
  1066.  
  1067.    5.2.14:  BOYAN Power--Macros and Script Files                        100
  1068.    ________________________________________________________________________
  1069.  
  1070.  
  1071.    nothing at all; this can  be used to read prompts from a BBS into a user
  1072.    variable.   Finally,  the  +  parameter  tells  BOYAN to "read with word
  1073.    wrap":  if the input text exceeds the given maximum  length  y, then the
  1074.    previous  word  of  input will be erased and saved for  the  next  \RVc+
  1075.    command.  See the HOST.BSC script for many examples of how \RV is used.
  1076.  
  1077.    \SVc[string]                      \SV4[The current time is %HR:%MI:%SE.]
  1078.    Set Variable.  This command lets you Set user Variable  c.   The example
  1079.    above sets variable %V4 equal to a message containing the current time.
  1080.  
  1081.    \TVc[y]                                                         \TV1[84]
  1082.    Terminal keyset macro into  Variable.   This command is analagous to the
  1083.    \MV command, moving the  contents  of  BOYAN  Secondary Keyset macro # y
  1084.    (41..110) into user variable c.
  1085.  
  1086.    \+Vc[y]                           \SV1[68]  \+V1[34]  \DM[ 68+34 = %V1 ]
  1087.    Plus Variable.  This command  lets your macros perform basic arithmetic.
  1088.    The number y is added to the contents of user variable c, and the result
  1089.    is again stored in variable c.   To  perform  subtraction,  let  y  be a
  1090.    negative number, e.g. \+V1[-34].  The valid range for  numeric  data  is
  1091.    -10000..10000.  In the example above, the  \+V1[34] command  changes the
  1092.    value of %V1 from 68 to 102.
  1093.  
  1094.    5.2.15  Macro Control
  1095.  
  1096.    \\string                         \DL[]  \\ that command downloads a file
  1097.    (Macro  comment)    BOYAN ignores all characters in a macro after the \\
  1098.    command.  Use this to insert remarks in a macro.  BOYAN also ignores any
  1099.    spaces which immediately precede the "\\", so that you can use spaces to
  1100.    align  comments in a script file.  The above example has the same effect
  1101.    as "\DL[]" alone.
  1102.  
  1103.    \AB                       \KV2Y[Continue? ]\IV2+N[\AB]\DM[Continuing...]
  1104.    ABort  current  macro  (or script file) processing.  The example prompts
  1105.    the user with the "Continue?" prompt.  If  the  user  responds  "N", the
  1106.    macro or  script  is  aborted,  and  none  of the following commands are
  1107.    processed.
  1108.  
  1109.    \AT+[macro]                                                    \AT+[\MM]
  1110.    \AT-[macro]                       \AT-[\PM[Script file %CS is running.]]
  1111.    ATtended?  The \AT+  command  processes the enclosed macro only if BOYAN
  1112.    is  attended,  that is, if there is no script file running.    The  \AT-
  1113.    command processes the enclosed macro only if BOYAN is not attended--when
  1114.    a script file is running.
  1115.  
  1116.    \EM                                         \RE[ \DM[ %RE ]  \CA+[\EM] ]
  1117.    End Macro:  stops the current macro; if in a script file, advance to the
  1118.    next  line of the script.  This command is most often used to break  out
  1119.    of an infinite  REpeat  loop.    In  the example above, BOYAN displays a
  1120.  
  1121.  
  1122.    5.2.15:  BOYAN Power--Macros and Script Files                        101
  1123.    ________________________________________________________________________
  1124.  
  1125.  
  1126.    running counter until the CArrier signal is detected, at which point the
  1127.    \EM command breaks the loop.
  1128.  
  1129.    \IE+string1,string2[macro]             \IE+%UD,DL[\DM[File downloaded.]]
  1130.    \IE-string1,string2[macro]        \IE-0,%DS[\JD|\ST[Can't jump to DOS.]]
  1131.    If  Equal?    The \IE command tests the equality of string1 and string2.
  1132.    \IE+  processes  the  enclosed macro if  the  strings  are  equal;  \IE-
  1133.    processes  its  macro  only if they are not.  The  first  example  above
  1134.    displays the "File downloaded"  message  if the last file transfer was a
  1135.    download (the %UD variable would equal "DL").  The second  example jumps
  1136.    to DOS if the amount  of  DOS  Shell  space  (%DS) does not equal 0, and
  1137.    writes a status message if %DS does equal 0.   Case  is NOT significant,
  1138.    so ibm-PC matches Ibm-Pc.
  1139.  
  1140.    \II+string1,string2[macro]  \II+Put,Computer[\DM['Put' found at position
  1141.                                                                      %II.]]
  1142.    \II-string1,string2[macro]    \II-PCA,%V6[\DM[Error:  %V6 should contain
  1143.                                                                    'PCA'.]]
  1144.    %II   %IM                                           \II+;,%V8[\LV8[%IM]]
  1145.    If  Included?    The \II command tests  If  string1  is  Included  as  a
  1146.    substring of  string2,  as  "Put"  is  a  substring of "Computer".  \II+
  1147.    processes  its  macro  if string1 is included in string2; \II- processes
  1148.    macro if string1 is not  in  string2.    The  %II  variable  returns the
  1149.    numeric position within string2  where  string1  was  found, if \II+ was
  1150.    successful,  so  the  first example macro above  displays  the  message,
  1151.    "'Put' found at position 4".  The %IM macro simply equals %II Minus one.
  1152.    This  is used in the third example above to truncate %V8 at the position
  1153.    where a semicolon was  found;  e.g.,  if %V8 = Justin Boyan;ibm-pc, then
  1154.    processing the \LV8[%IM] macro leaves %V8 = Justin Boyan.
  1155.  
  1156.    \IK+[macro]                        \ST[Press any key: _] \RE[\IK+[\EM] ]
  1157.    \IK-[macro]
  1158.    %IK                                         \IE-%IK,Q[\MA[61] |ELSE \AB]
  1159.    If  Keypressed?   \IK+ runs its enclosed macro only if a  key  has  been
  1160.    pressed during the operation of the current macro or script block.  \IK-
  1161.    runs its enclosed macro if no  key  has  been pressed.  The %IK variable
  1162.    always  holds  the  last character typed by the user.  The first example
  1163.    above repeatedly checks for a keypress, ending the macro once  you press
  1164.    a key.  The second example runs macro #61 if the  last  key  you pressed
  1165.    was  q; if the last key you pressed was not q, then the macro/script  is
  1166.    aborted.  Compare %IK with the \KV macro command  described  in  section
  1167.    5.2.14.  The difference is that  \KV  stops macro processing to wait for
  1168.    user input, while %IK checks to see if you have typed anything while the
  1169.    macro is running.
  1170.  
  1171.    \MA[x]                                                            \MA[9]
  1172.    MAcro.  This invokes BOYAN macro  #  x  (1-120).  For example, the macro
  1173.    command \MA[9]  runs the initialization Auto-macro;  \MA[38] invokes the
  1174.    <Alt-X> (exit BOYAN with verify) macro.
  1175.  
  1176.  
  1177.    5.2.15:  BOYAN Power--Macros and Script Files                        102
  1178.    ________________________________________________________________________
  1179.  
  1180.  
  1181.    \REx[macro]                                                  \RE5[\WF[]]
  1182.    \RE[macro]                    \ST[Waiting for carrier...] \RE[\CA+[\EM]]
  1183.    %RE                                             \RE24[\DM%RE[Hi there!]]
  1184.    REpeat  macro.    If  a  number  x  (1..32767) is given before the  left
  1185.    bracket,  then  the  enclosed macro will be executed x times.  The first
  1186.    example above would wait  for  five characters to arrive from the modem.
  1187.    If no number is specified,  the enclosed macro is repeated indefinitely.
  1188.    To break out of such an "infinite loop," the enclosed macro must contain
  1189.    an  ABort,  End Block, or End Macro command (or the user  can  abort  by
  1190.    pressing <Esc>).  Above, the \CA+[\EM]  command  is used to break out of
  1191.    the  repeat  loop as soon as the carrier signal is detected.    The  %RE
  1192.    variable holds the counter number of the innermost repeat loop.   In the
  1193.    third example above, the message "Hi there" is displayed on line 1, line
  1194.    2, line 3, ... all the way to line 24.
  1195.  
  1196.    5.2.16  Miscellaneous
  1197.  
  1198.    \CB[]                                                        \AT+[\CB[]]
  1199.    \CB[c]                                                            \CB[T]
  1200.    Configure BOYAN.  \CB[] invokes BOYAN's main configuration menu.  If you
  1201.    specify a letter (any of S C D E M A T  X)  within  the  brackets, BOYAN
  1202.    will  jump directly to the specified Config  Area.    The  configuration
  1203.    choices  must be made from the keyboard, so do not run this macro unless
  1204.    the keyboard is attended.
  1205.  
  1206.    \EX                                       \KV0Y[OK to exit? ]\IV0+Y[\EX]
  1207.    EXit BOYAN immediately!   A macro like the one above may be used to make
  1208.    the user confirm that he wants to exit.
  1209.  
  1210.    \HE
  1211.    HElp.  This invokes BOYAN's main help screen, the BOYAN Command Menu.
  1212.  
  1213.    \HK
  1214.    Help with function Keys.    This calls up BOYAN's screen of user-defined
  1215.    function key descriptions.
  1216.  
  1217.    \RB
  1218.    Review Buffer.  This calls up the scroll-back buffer for viewing, script
  1219.    learning, etc.
  1220.  
  1221.    \SK+   \SK-   \SK*   %SK
  1222.    Secondary Keyset (Scroll locK).    \SK+  sets Scroll-Lock ON, activating
  1223.    the Secondary Keyset of the current BAM.  \SK-  turns  Scroll-Lock  OFF,
  1224.    \SK* toggles Scroll-Lock, and %SK returns  Scroll-Lock's  current status
  1225.    (ON or OFF).
  1226.  
  1227.  
  1228.    5.2.16:  BOYAN Power--Macros and Script Files                        103
  1229.    ________________________________________________________________________
  1230.  
  1231.  
  1232.    \SMx[string]                                         \SM1[ATDT 9,"@SF"{]
  1233.    Set BOYAN Macro  # x to the specified macro.  This new macro is saved to
  1234.    the BOYAN.MAC file, just as if it were reconfigured in Config  Area <M>.
  1235.    The example sets macro #1 (the Dialing command) to ATDT 9,@SF{  which is
  1236.    useful for dialing out from Centrex-type phone extensions.
  1237.  
  1238.    \TMx[string]                                                \SN101["\HK]
  1239.    Set  BOYAN  Terminal  Keyset Macro # x (41..110) to the specified macro.
  1240.    This  new  macro  is saved to the .CNF file corresponding to the current
  1241.    BAM, e.g., VT-100.CNF, HOST.CNF,  etc.   Also see the \TV command above,
  1242.    which reads a macro from the secondary keyset into a user variable.
  1243.  
  1244.    5.2.17  <Shift-F1> Trace Mode
  1245.  
  1246.    BOYAN's macro language provides  a  "trace"  feature  which can help you
  1247.    learn  how  a  macro  works  or  discover why a macro or script  is  not
  1248.    working.  When Trace Mode is  on,  the  middle of the Status Line always
  1249.    displays the two letters of the current macro  command  being processed.
  1250.    (When  sending text to the modem, you will see a small arrow rather than
  1251.    two letters.)  In addition, while  a  script file is running, the Status
  1252.    Line  will  indicate  the  current  line  number  of  the  script  being
  1253.    processed.
  1254.  
  1255.    An especially handy feature is the ability to slow down and speed up the
  1256.    script dynamically, as the script is running.  When the  Num-Lock toggle
  1257.    is  not  locked,  the macro or script being traced will  race  along  at
  1258.    normal speed.  At this speed it is impossible to follow the trace output
  1259.    closely.    When  Num-Lock   is   locked,   however,  BOYAN  pauses  for
  1260.    approximately one-half second between displaying  the  macro's  name and
  1261.    actually executing  it.    You  may turn Num-Lock on and off at any time
  1262.    while a script is running.
  1263.  
  1264.    \NK+   \NK-   \NK*   %NK
  1265.    Num locK.  \NK+  sets  Num-Lock, \NK- unsets Num-Lock, \NK* toggles Num-
  1266.    Lock,  and  %NK  returns Num-Lock's current status (ON or OFF).  A handy
  1267.    debugging tool is to insert the \NK+ command  at  the  position  in your
  1268.    script where you are having trouble.  When the script gets  to precisely
  1269.    that  point,  it will slow down so that you can follow  the  Trace  Mode
  1270.    output.
  1271.  
  1272.    \TR+   \TR-   \TR*   %TR
  1273.    The \TR+  and  \TR-  macros  are used to actually turn Trace Mode on and
  1274.    off.    \TR*  toggles the Trace Mode, and %TR reports the current status
  1275.    (ON or OFF).
  1276.  
  1277.  
  1278.    5.3:  BOYAN Power--Macros and Script Files                           104
  1279.    ________________________________________________________________________
  1280.  
  1281.  
  1282.    5.3  BOYAN Macro Tutorial, Examples
  1283.  
  1284.  
  1285.    The best way to learn how BOYAN's macros work is  to  experiment:  write
  1286.    one, and see what it does!    The <Alt-M> "Enter macro manually" command
  1287.    is useful for trying out  a  short  macro.    Many  example  macros have
  1288.    already been given, next to the descriptions of all the macro commands.
  1289.  
  1290.    The following additional examples illustrate  how  BOYAN's  120 built-in
  1291.    macros give you flexibility unlike any other communications program.  To
  1292.    edit the BOYAN macros, press <Alt-K>.  You can then  choose  a macro for
  1293.    editing by either typing its number (1-120) and pressing <Enter>,  or in
  1294.    the case of keystroke  macros,  simply  pressing  the keystroke (such as
  1295.    <F2>) itself.  For a review  of  basic macro editing, please see section
  1296.    3.9.4.
  1297.  
  1298.    Don't  worry  about  destroying  BOYAN's  original   macros   while  you
  1299.    experiment.  You can always restore  all  of the preset macros by simply
  1300.    deleting the BOYAN.MAC file from your disk and starting BOYAN over.
  1301.  
  1302.    5.3.1  Built-in Keystroke Examples
  1303.  
  1304.    This section studies some of the built-in BOYAN keystroke macros to show
  1305.    you  how  they  work and to aid you in modifying them if you like.  They
  1306.    are ordered roughly from simplest to most complex.
  1307.  
  1308.    >                    <F2>:  Send your name + <Enter>                   <
  1309.    Macro #72: Justin Boyan{
  1310.    The simplest kind of macro!  The left curly brace stands for the <Enter>
  1311.    or <Return> character.
  1312.  
  1313.    >                  <F3>:  Send your password + <Enter>                 <
  1314.    Macro #73: %PW{
  1315.    When you  a  dial  a  system  from  the dialing directory, that system's
  1316.    private  password is stored in BOYAN's %PW variable.    This  key  macro
  1317.    sends that password and the <Return> character over the modem.
  1318.  
  1319.    >               <Alt-F10>:  Display current time and date              <
  1320.    Macro #110: \ST[It is now %HR:%MI:%SE on %MO/%DA/%YR.]
  1321.    The  \ST[..]  macro  command displays a string on the Status line.  This
  1322.    example shows how Macro Variables may be used in such a string.
  1323.  
  1324.    >                     <Alt-N>:  New disk directory                     <
  1325.    Macro #28: \KV0%C:[NEWDIR: ]  \ND[%V0]  \ST[%C:]
  1326.    This  example shows how BOYAN's interactive macros  work.    First,  the
  1327.    macro  uses the "\KV#default[prompt]" command to  prompt  the  user  for
  1328.    input.    In  this case, the user's prompt is "NEWDIR:  ";  the  default
  1329.    response is %C:, a variable which  returns  the name of the current disk
  1330.    directory; and the user's final response is kept in  user  variable  #0.
  1331.  
  1332.  
  1333.    5.3.1:  BOYAN Power--Macros and Script Files                         105
  1334.    ________________________________________________________________________
  1335.  
  1336.  
  1337.    Then, the \ND[%V0]  command  switches  to  a New Directory given by %V0.
  1338.    Finally, the \ST command displays a status message, consisting of simply
  1339.    the (new) current disk directory.
  1340.  
  1341.    >               <Shift-F1>:  Toggle BOYAN's "Trace Mode"               <
  1342.    Macro #39: \TR* \ST[Macro trace mode now %TR]
  1343.    First, the \TR* command has the effect of actually  toggling  the  Trace
  1344.    Mode setting.  Then, a status message is displayed  which  includes  the
  1345.    new value of  the Trace Mode variable %TR, either ON or OFF.  This macro
  1346.    is typical of BOYAN toggle commands.  (The  trace  mode  itself  is very
  1347.    useful for understanding macros and scripts; see section 5.2.17.)
  1348.  
  1349.    >                     <Alt-L>:  Toggle Disk Logging                    <
  1350.    Macro #26: \IE+OFF,%LD[\KV0%LN[Log to: ]] \LD*[%V0] \ST[Logging now %LD]
  1351.    This is another toggle command like <Shift-F1>, but it inserts  an extra
  1352.    conditional  command  at  the  beginning.   The conditional  (If  Equal)
  1353.    command checks if logging to disk (%LD) is equal to OFF.    If  so, then
  1354.    the  \KV command prompts the user for a filename to "Log to", giving the
  1355.    default log name (%LN) as a default.
  1356.  
  1357.    >                         <F6>:  View usage log                        <
  1358.    Macro #76: \DC[%LC %UN]
  1359.    This macro  uses  the  \DC[..]  macro to execute a DOS Command.  The %LC
  1360.    variable  names  your  file lister program (specified in Config Area D).
  1361.    The %UN variable  contains  the  name  of  your usage log file.  Putting
  1362.    these  together, the DOS command that <F6>  executes  looks  like  "LIST
  1363.    C:\BOY5\BOYAN.USE".   Similarly, you can assign any  DOS  command  to  a
  1364.    single keystroke.
  1365.  
  1366.    >        <Ctrl-F1>:  View the BOYAN.DOC file, this user's manual       <
  1367.    Macro  #81:  \SV0[%B:BOYAN.DOC]  \FE+%V0[\DC[%LC  %V0]  |  \ST[File  not
  1368.    found.]]
  1369.    This macro adds complexity  to  the <F6> example above because it checks
  1370.    that  the file exists before trying to view it.  In this case, the  file
  1371.    to be viewed is BOYAN.DOC, which if it exists is assumed to live in your
  1372.    BOYAN home directory (specified by %B:).  Here's how  the  macro  works.
  1373.    First, it sets  user  variable  0  to  hold  the  full name of the file,
  1374.    %B:BOYAN.DOC.  Then it uses  the  \FE+  macro  to  check  that  the file
  1375.    exists.   If  it  does,  the macro calls DOS to list the file; otherwise
  1376.    (|), it prints a "File not found" status message.
  1377.  
  1378.    >                <Alt-V>:  View file using File Manager                <
  1379.    Macro #36: \( \KV0[VIEW: ] \RS \IV0+[\FMV[] |ELSE \DC[%LC %V0]]
  1380.    Macro #119: \KS \DM1,24[  (Leave blank for directory.)  ]
  1381.    If a key macro is too long to fit in the space provided, one solution is
  1382.    to break it  up  into  two  separate  macros.  The <Alt-V>, <Alt-R>, and
  1383.    <Alt-W>  key  macros  all make use of macro #119, the \( Shortcut macro.
  1384.    This shortcut does two things:  it stores an image of the current screen
  1385.    in  memory  (\KS), and it displays a brief message on line  24.    After
  1386.  
  1387.  
  1388.    5.3.1:  BOYAN Power--Macros and Script Files                         106
  1389.    ________________________________________________________________________
  1390.  
  1391.  
  1392.    invoking the  shortcut  \(,  the  <Alt-V>  macro  prompts the user for a
  1393.    filename, and then restores the  screen  (\RS),  thus  un-displaying the
  1394.    "Leave  blank  for  disk directory" message.   Finally,  the  \IV0+[...]
  1395.    command tests whether the user's response  (%V0)  was empty.  If it was,
  1396.    then the File Manager is invoked with "View" as  the  default  selection
  1397.    (\FMV[]); otherwise, the  <Alt-V>  macro  calls  DOS  to  view  the file
  1398.    immediately.
  1399.  
  1400.    5.3.2  Auto-macro Examples
  1401.  
  1402.    >               Clear screen automatically before dialing              <
  1403.    Macro #1:  \ZS ATDT@SF{
  1404.    BOYAN dials a number by simply executing Macro #1, the  dialing command.
  1405.    The @SF variable is used  to  insert  the  System  FON  number  into the
  1406.    command.  To make BOYAN automatically clear the  terminal  screen before
  1407.    dialing, just insert the command \ZS (Zap Screen) into macro #1.
  1408.  
  1409.    >          Remove same-named systems from Queue after connect          <
  1410.    Macro #6:  \UM[%SN (%MS baud): %SF]  \QA-[%SN]
  1411.    When  you  connect  to a system, BOYAN automatically deletes that system
  1412.    from the Redialing Queue.  However, by appending  the  \QA-[%SN] command
  1413.    to  macro #6, you instruct BOYAN to also delete from the Queue any other
  1414.    systems with  a  similar  System  Name.    For example, suppose you have
  1415.    systems named "Bob's BBS Line 1", "Bob's BBS  Line  2",  and  "Bob's BBS
  1416.    Line 3" all in the Queue.  When you connect to any one of those systems,
  1417.    this macro will automatically remove all three systems from the Queue.
  1418.  
  1419.    >        Eliminate the "squawk" BOYAN makes after disconnecting        <
  1420.    Macro #7:  \RC \SK- \UM[| Disconnected after %SL]
  1421.    Simply  delete  the    \AL3[0]   command from the "After  disconnecting"
  1422.    Auto-macro (#7).
  1423.  
  1424.    >     Automatically return to dialing directory after disconnecting    <
  1425.    Macro #7:  \AL3[0] \RC \SK- \UM[| Disconnected after %SL] \DI[]
  1426.    As soon as the  connection's  carrier signal is lost, BOYAN executes its
  1427.    Auto-macro #7.  By adding the  command  "\DI[]"  to the end of macro #7,
  1428.    you instruct BOYAN  to  automatically invoke the dialing directory after
  1429.    disconnecting.
  1430.  
  1431.    >                Automatically log all sessions to disk                <
  1432.    Macro #6: \UM[%SN (%MS baud): %SF]  \LD+[%B:BOYAN%S#.LOG]
  1433.    Macro #7: \AL3[0] \RC \SK- \UM[| Disconnected after %SL]  \LD-
  1434.    If  you  add  these \LD commands to Auto-macros #6 and  #7,  BOYAN  will
  1435.    automatically maintain a  separate,  permanent log file for each dialing
  1436.    directory  entry.    The  log  files  will  be stored in the BOYAN  home
  1437.    directory  (%B:) and  named  BOYAN1.LOG,  BOYAN2.LOG, ...  BOYAN200.LOG,
  1438.    depending on the system's entry number in the  dialing  directory (%S#).
  1439.    The  appropriate  log  file is opened by Macro #6 whenever  you  make  a
  1440.    connection  and closed by Macro #7 (\LD-) as  soon  as  you  disconnect.
  1441.  
  1442.  
  1443.    5.3.2:  BOYAN Power--Macros and Script Files                         107
  1444.    ________________________________________________________________________
  1445.  
  1446.  
  1447.    Thanks to Auto-macro #14 (the "Log file init macro"), a header line will
  1448.    separate the sessions within each system's log file.
  1449.  
  1450.    >             Log each day's sessions to a dated disk file             <
  1451.    Macro #9: ATX4S0=0{  \LD+[%B:%MO-%DA-%YR.LOG]
  1452.    Unlike the previous example, where the  name  of the log file depends on
  1453.    which system you call, this example opens a log file whose  name depends
  1454.    on  the  current  date.  Every time you start BOYAN, this start-up macro
  1455.    (#9) will open a log file in the BOYAN home directory (%B:) named by the
  1456.    current  date, e.g., 05-28-92.LOG on May 28,  1992.    BOYAN's  conclude
  1457.    macro contains the \LD- command, so the log will be closed when you exit
  1458.    BOYAN.
  1459.  
  1460.    >       Automatically fill the redialing queue at BOYAN start-up       <
  1461.    Macro #9:  \DM[ Welcome to BOYAN! ] ATX4S0=0{ \QA[1] \QA[4] \QA[5]
  1462.    Suppose you dial systems 1, 4, and 5  in  your  dialing  directory every
  1463.    time you use BOYAN.  If  you  append  the commands  \QA[1] \QA[4] \QA[5]
  1464.    to  the  BOYAN  start-up  macro  (#9),  then  those three  systems  will
  1465.    automatically  appear in the redialing queue.   You  could  also  append
  1466.    either of the \QE (enter redialing queue) or \QD (begin queue redialing)
  1467.    commands.
  1468.  
  1469.    >           Report the current Action Module name at start-up          <
  1470.    Macro #9: ATX4S0=0{  \ST[Using Action Module: %AN]
  1471.    After initializing the modem with ATX4S0=0 <Return>, this BOYAN start-up
  1472.    macro will display  a  status  message  such  as  "Using  Action Module:
  1473.    VT-100".  The %AN variable holds the name of the current action module.
  1474.  
  1475.    >          Get path confirmation before starting auto-download         <
  1476.    Macro #12: \AT+[\DL[]]
  1477.    Remove the "-" from the default Auto-download macro to make BOYAN   wait
  1478.    for you to confirm the download path before beginning an auto-download.
  1479.  
  1480.    >           Dial multiple systems in the middle of the night           <
  1481.    Macro #99: \QC \QA[Joe] \QA[Liz] \QA[Bob] \PU[3] \QU[6]
  1482.    Macro #7: \UM[| Disconnected after %SL] \QU[6]
  1483.    Let's see how these work.  Macro #99 corresponds to the  <Shift-F9> key.
  1484.    The first thing that happens when you press <Shift-F9> is that the queue
  1485.    is cleared.  Then, the \QA  command  adds  systems to the queue from the
  1486.    Dialing Directory.  \PU tells BOYAN to Pause  Until  3:00  am,  at which
  1487.    point  \QU will tell BOYAN to begin Queue redialing--but to give up at 6
  1488.    am if no connection has been made.
  1489.  
  1490.    If  a  connection  is made, however, then Macro #99 will finish, and the
  1491.    auto-logon script for that  system  (say, JOE.BSC) will take over.  This
  1492.    script  might read your mail on Joe's BBS and capture it to a file,  for
  1493.    example (see section 5.5).  At some point, JOE.BSC logs you off from the
  1494.    BBS.  Here's where macro #7, the "After Disconnecting" Auto-macro, comes
  1495.    into  play.   As soon as the carrier signal drops, Macro  #7  wakes  up,
  1496.  
  1497.  
  1498.    5.3.2:  BOYAN Power--Macros and Script Files                         108
  1499.    ________________________________________________________________________
  1500.  
  1501.  
  1502.    records a message in the usage log, and begins redialing again  with the
  1503.    \QU command.  The systems that remain in the queue (Liz and Bob) will be
  1504.    handled just like Joe's, as  soon  as  a  connection  is made.  At 6 am,
  1505.    queue redialing will stop, even if there are some systems  which haven't
  1506.    yet been reached.
  1507.  
  1508.    5.3.3  Yet More Key Examples!
  1509.  
  1510.    >              Make <Home> call up the BOYAN Command List              <
  1511.    Macro #45: \HE
  1512.  
  1513.    >           Make left mouse button invoke the Dial Directory           <
  1514.    Macro #11: \DI[]
  1515.  
  1516.    >          Make left mouse button run the MOUSMENU.BSC script          <
  1517.    Macro #11: \SC[MOUSMENU]
  1518.    This demonstrates how  you  can  link  the mouse button (or any function
  1519.    key) directly to a script file.
  1520.  
  1521.    >               Make <Alt-D> offer a "Quick-Dialing" bar               <
  1522.    Macro #18: \KV0[DIAL: ] \DI[%V0]
  1523.    If you alter the <Alt-D> keystroke macro (#18) as above, then instead of
  1524.    going  straight  to  the Dialing Directory, <Alt-D> will prompt you with
  1525.    "DIAL:" on  the  Status  Line.    First,  the \KV0 command requests your
  1526.    input,  storing  what  you type in user variable %V0.  Then the \DI[%V0]
  1527.    command dials that number, whether it is the name of  a  system from the
  1528.    Dialing Directory, the code number of a system from the directory,  or a
  1529.    full phone number entered manually.  If you typed only <Enter>, then %V0
  1530.    would  be  empty,  so  \DI[%V0]  conveniently would invoke  the  Dialing
  1531.    Directory.
  1532.  
  1533.    >              Make <Alt-0> "Kill" all BOYAN sound effects             <
  1534.    Macro #69: \BB- \AV[0] \ST[Sound effects Killed.]
  1535.    Now the <Alt-0> command (macro #69) will both turn Beeps & Bells off and
  1536.    set the Alarm Volume to  0.  As a friendly touch, it will also display a
  1537.    status message.
  1538.  
  1539.    >       Make <F9> invoke your editor on the last script file run       <
  1540.    Macro #79: \DC-[%WC %S:%SC]
  1541.    This macro makes a  handy  command  by  combining three macro variables:
  1542.    %WC, which holds the  name  of your word processor/text editor; %S:, the
  1543.    script directory, and %SC, the last script file run.    It  concatenates
  1544.    them to form a string such as "QEDIT  C:\BOY5\SCRIPT\CIS.BSC",  and then
  1545.    executes that string as a DOS Command.  The - in \DC- tells BOYAN not to
  1546.    wait for you to press a key after returning from the editor.
  1547.  
  1548.  
  1549.    5.3.3:  BOYAN Power--Macros and Script Files                         109
  1550.    ________________________________________________________________________
  1551.  
  1552.  
  1553.    >         Make <PgUp> remember the directory of the last upload        <
  1554.    Macro #47: \UL[%T:]
  1555.    BOYAN's normal upload macro,  \UL[],  chooses  your Upload Directory (as
  1556.    specified in Config  Area  <D>)  as  the  default path to search for the
  1557.    upload filename.  This macro tells \UL to search the  path  given by %T:
  1558.    instead, where %T: stores the path used by the previous file transfer.
  1559.  
  1560.    >                Make <End> reset the current modem port               <
  1561.    Macro #46: \CD[%MD]
  1562.    The trick is  to  tell  BOYAN  to  "change devices" to the current modem
  1563.    device--resetting the device  in  the  process.   This is what the <End>
  1564.    keystroke macro (#45) above does.  Running certain external programs may
  1565.    cause the port to "lock up"; if that  happens,  running  this  macro (by
  1566.    pressing <End>) should fix the problem.
  1567.  
  1568.    >            Make <Alt-F5> toggle the "GOSSIP" Action Module           <
  1569.    Macro #105: \IE-%AN,GOSSIP[\AM[G] |ELSE \AM[%AP]]
  1570.    The \AM macro command selects a new BOYAN Action  Module;  for  example,
  1571.    \AM[G] invokes BOYAN's Gossip Mode.  The <Alt-F5> keystroke macro (#105)
  1572.    presented above is  more  sophisticated:    if you are already in Gossip
  1573.    mode,  pressing  <Alt-F5>  again  will  return you to your prior  Action
  1574.    Module.  Here's how it works:  the  \IE-  command  checks  to see If the
  1575.    current  Action module Name, %AN, is not Equal to "GOSSIP".  If they are
  1576.    not equal, then the Gossip Mode  is  invoked by "\AM[G]".  Otherwise, if
  1577.    GOSSIP is the  current  name,  then  the previous module is invoked with
  1578.    "\AM[%AP]".   (The %AP variable remembers  the  previous  Action  module
  1579.    letter.)
  1580.  
  1581.    >            Make <Ctrl-F8> view the contents of a ZIP file            <
  1582.    Macro #88: \FM`pkunzip -V[*.ZIP]
  1583.    This macro invokes the File Manager on all  .ZIP  files  in  the current
  1584.    directory.    The  default  command  for  the  File  Manager is given as
  1585.    PKUNZIP -V, which is the DOS command to view the contents of a ZIP file.
  1586.  
  1587.    >             Make <Ctrl-F9> build a ZIP of selected files             <
  1588.    Macro   #89:\FML[]   \KV0[Build   zip:]  \DC-[pkzip  %V0  "@boymark.lst]
  1589.    \ST[Done!]
  1590.    First,  this macro invokes the File Manager with  the  List  command  as
  1591.    default.  While in the File Manager, you may use the <space> key to mark
  1592.    files, and then  <Enter>  to  list  those files to the BOYMARK.LST file.
  1593.    The  macro then prompts you for the name of the .ZIP file to build,  and
  1594.    invokes  the  DOS  Command PKZIP @BOYMARK.LST to actually build the .ZIP
  1595.    using the filenames in BOYMARK.LST.
  1596.  
  1597.    >            Make <Shift-F10> turn BOYAN into an alarm clock           <
  1598.    Macro #100: \KV0%HR:%MI[Set alarm: ] \UT%V0[\DM[ %HR:%MI:%SE ]] \AL2[3]
  1599.    This  macro   uses  several  advanced  commands.    The  first  command,
  1600.    \KV0%HR:%MI[Set alarm: ], requests keyboard input into user variable %V0
  1601.    with the prompt, "Set alarm: ".  A default of %HR:%MI, the current time,
  1602.  
  1603.  
  1604.    5.3.3:  BOYAN Power--Macros and Script Files                         110
  1605.    ________________________________________________________________________
  1606.  
  1607.  
  1608.    is  provided.   The second  command,  \UT%V0[\DM[ %HR:%MI:%SE ]],  loops
  1609.    Until the Time has become  %V0--which  is  the  time  read  in  from the
  1610.    keyboard.  During each loop it Displays a Message of the current time on
  1611.    the  screen.  When the \UT loop finally  finishes,  the  third  command,
  1612.    \AL2[3], rings an alarm (type 2) for three seconds.
  1613.  
  1614.                                *    *    *    *
  1615.  
  1616.    The macros above are just a small sample  of  the  range  of flexibility
  1617.    BOYAN's built-in macros can offer.  If you write a clever  macro, please
  1618.    submit it for inclusion in the next edition of this manual!
  1619.  
  1620.  
  1621.    5.4  The BOYAN Command Line
  1622.  
  1623.  
  1624.    Normally, you run BOYAN by issuing the simple command  BOYAN  from  DOS.
  1625.    BOYAN's  first  step  is  to  execute Auto-macro #9, the BOYAN  start-up
  1626.    macro.  However, in some cases,  you  may wish to avoid BOYAN's start-up
  1627.    macro.  BOYAN allows  you  to specify an alternative start-up macro when
  1628.    invoking BOYAN, directly from the DOS command line.  For example, if you
  1629.    ran  BOYAN  with  the DOS Command BOYAN ATZ{ , then BOYAN would send the
  1630.    ATZ <Return>  modem  string,  rather  than  executing  macro #9.  If you
  1631.    invoked  BOYAN by typing BOYAN \DI[Boyan Support]  ,  then  BOYAN  would
  1632.    immediately  dial  the specified number.  If  you  ran  BOYAN  with  the
  1633.    command  BOYAN \\  , then BOYAN would do  nothing  at  all  at  start-up
  1634.    (bypassing its normal start-up macro), since \\ signifies  only  a macro
  1635.    comment.    This might be useful if  you  were  already  on-line  before
  1636.    invoking BOYAN.
  1637.  
  1638.    Another application of the command line macro feature is that  BOYAN can
  1639.    be run from  a batch file.  For example, a batch file could invoke BOYAN
  1640.    with the command, BOYAN \MA[9] \SC[NIGHT] .  At  start-up,  BOYAN  would
  1641.    first run macro  #9  (the  normal  start-up macro), and then execute the
  1642.    NIGHT.BSC script file.
  1643.  
  1644.    Your DOS command line may also specify the amount of memory BOYAN should
  1645.    reserve for the DOS Shell.   For  example,  type BOYAN 100 to have BOYAN
  1646.    reserve 100K of memory for the Shell.  A start-up macro could follow the
  1647.    memory specification; e.g., BOYAN 100  \MA[9]  \DI[Boyan  Support] would
  1648.    make BOYAN reserve 100K  of  memory for DOS, execute its normal start-up
  1649.    macro, and finally dial the Boyan Support BBS.
  1650.  
  1651.  
  1652.    5.5:  BOYAN Power--Macros and Script Files                           111
  1653.    ________________________________________________________________________
  1654.  
  1655.  
  1656.    5.5  Script Files
  1657.  
  1658.  
  1659.    BOYAN script files can be created  by  any text editor or word processor
  1660.    which can edit standard text files--for instance, the EDLIN editor which
  1661.    comes with DOS, or the SideKick notepad.   Script  files  must  be named
  1662.    with  a suffix of .BSC, and should be placed in the default BOYAN script
  1663.    directory (although that is not mandatory).
  1664.  
  1665.    The simplest kind of script file is just  a  sequence  of  BOYAN macros.
  1666.    BOYAN processes such a script  file by sequentially evaluating each line
  1667.    of  the  file as a macro, until it reaches the end of the file.    Blank
  1668.    lines  are ignored.  This is the type of script created by BOYAN's auto-
  1669.    matic Script Learn facility.
  1670.  
  1671.    In more complex script files, you may organize the  sequence  of  macros
  1672.    into as many as 500 "blocks."   The start of a  block  is  defined  by a
  1673.    line of text which begins with the  vertical  bar    |    symbol (shift-
  1674.    backslash)  plus a block label.  Labels can be as long as you wish,  but
  1675.    only the first eight characters  are  significant,  e.g.,   MessageReply
  1676.    and  MessageRead  are equivalent labels.  Since case is not significant,
  1677.    |LOGON  and |LogOn also refer to the same block.  All macros following a
  1678.    block label are  considered  a  part  of that block until either another
  1679.    block label or the end of the file is reached.
  1680.  
  1681.    5.5.1  Script-specific Macro Commands
  1682.  
  1683.    The  Macro  Programming Language provides  several  additional  commands
  1684.    specifically  for power in script files.   These  commands  allow  BOYAN
  1685.    scripts to use looping, block nesting, and even recursion.
  1686.  
  1687.    \AB
  1688.    ABort.   Aborts all current script files, just as if you had pressed the
  1689.    <Esc> key.  If the script has a block named *WRAPUP  in  it,  that block
  1690.    will be executed before  you  are returned to terminal mode (see section
  1691.    5.5.4).
  1692.  
  1693.    \BL[label]                                                    \BL[LogOn]
  1694.    BLock.  Calls the block with the specified label.   When  that block has
  1695.    completed, control is returned to the calling macro.
  1696.  
  1697.    \EB                                             \IF+end of messages[\EB]
  1698.    End the current Block.  You can use this within a  conditional statement
  1699.    to end the block prematurely.  See also \EM (End Macro).
  1700.  
  1701.    \GB[label]                                                    \GB[LogOn]
  1702.    Goto Block.  Go directly to  the  block  with the specified label.  When
  1703.    the end of that block is reached, the script is finished; control is not
  1704.    returned to the calling macro.
  1705.  
  1706.  
  1707.    5.5.1:  BOYAN Power--Macros and Script Files                         112
  1708.    ________________________________________________________________________
  1709.  
  1710.  
  1711.    \GS[filename]                                                  \GS[rbbs]
  1712.    \GS[filename;label]                                   \GS[rbbs;messages]
  1713.    Goto  Script.  Go directly to the script  with  the  specified  filename
  1714.    (.BSC  suffix  assumed).   If a  semicolon  and  label  are  given,  the
  1715.    specified block of the script  is executed; otherwise, the entire script
  1716.    runs from start to finish.
  1717.  
  1718.    \KO[x]                                                            \KO[0]
  1719.    Keyboard timeOut.  Set the unattended keyboard timeout to x seconds.  If
  1720.    BOYAN requires keyboard  input  while  a  script file is active, it will
  1721.    wait  x seconds for the user to manually respond.  If there has been  no
  1722.    keyboard  response  after  x seconds, BOYAN goes ahead using the default
  1723.    response.  After the  \KO[0]  command,  for example, BOYAN automatically
  1724.    accepts the default response immediately.
  1725.  
  1726.    %S:                                                     D:\BOYAN\SCRIPT\
  1727.    %SC                                                          PCBOARD.BSC
  1728.    Script  path.    The %S: variable  contains  BOYAN's  script  file  disk
  1729.    drive+path;    %SC  holds  the  name  of  the  currently active (or most
  1730.    recently active) script file.
  1731.  
  1732.    \SC[filename]                                                  \SC[rbbs]
  1733.    \SC[filename;label]                                      \SC[rbbs;LogOn]
  1734.    SCript.   Invoke the script with the  specified  filename  (.BSC  suffix
  1735.    assumed).    If  a semicolon and label are given, the specified block is
  1736.    executed; otherwise, the entire script runs from start to finish.   When
  1737.    that script has completed, control is returned to the calling macro.  If
  1738.    the filename is not preceded by  a  DOS pathname, BOYAN assumes that the
  1739.    script file is located in the default Script directory.
  1740.  
  1741.    5.5.2  Automatic Logon Scripts
  1742.  
  1743.    In section 4.7.3.1, you  saw  how BOYAN's Script Learn Facility could be
  1744.    used to  write  scripts  for  automatic  logging-on  to a system.  BOYAN
  1745.    allows a  completely  hands-free  logon  through  its  dialing directory
  1746.    Script field.  Using the Edit command in the dialing directory,  you can
  1747.    assign each entry a 1-8  character  script  name,  like    PC-BOARD   or
  1748.    MCIMAIL .    The  next  time you connect to the system using the <Alt-D>
  1749.    Dial or <Alt-Q> Queue Redial  commands, BOYAN loads the specified script
  1750.    file (the .BSC suffix is automatically  added).   It then searches for a
  1751.    block labeled |LOGON.  If there  is  a  |LOGON block in the script, then
  1752.    only that block is executed.  Otherwise, the entire script  is processed
  1753.    from beginning to end.
  1754.  
  1755.  
  1756.    5.5.3:  BOYAN Power--Macros and Script Files                         113
  1757.    ________________________________________________________________________
  1758.  
  1759.  
  1760.    5.5.3  Running Script Files
  1761.  
  1762.    BOYAN  can  automatically  process  a  logon script file after making  a
  1763.    connection.  However, you may often need to run a  script  at some other
  1764.    time.    BOYAN  provides  a  number of convenient methods for  executing
  1765.    either an entire script file or just a single block from a script file.
  1766.  
  1767.    When specifying a script file, you may include  the  script's directory,
  1768.    its name (.BSC suffix  assumed),  and optionally a semicolon and a block
  1769.    label.  For example, the following are all valid script specifiers:
  1770.  
  1771.    c:\text\menu;DownLoad
  1772.                         This  specifies  the  drive, directory, script name
  1773.                         (MENU.BSC), and block to execute.
  1774.  
  1775.    RBBS.BSC;LogOn       This  specifies  the LOGON block  of  the  RBBS.BSC
  1776.                         script.  BOYAN will search for this script first in
  1777.                         the Script  Directory (set in Config Area <D>).  If
  1778.                         it is not found there,  BOYAN will also look for it
  1779.                         in the current directory.
  1780.  
  1781.    A:INIT               This  specifies  the  A:INIT.BSC  script,   but  no
  1782.                         particular block.  BOYAN will run the entire script
  1783.                         from start to finish.
  1784.  
  1785.    Besides specifying an auto-logon script, you can run a  script  file  in
  1786.    the following ways:
  1787.  
  1788.       1.  Use BOYAN's <Alt-R> command from terminal mode.   Respond  to the
  1789.           "SCRIPT:" prompt with a specifier  like any of the three examples
  1790.           above.  If your response is  blank,  you will be given the chance
  1791.           to select a script directly from your Script Directory.
  1792.  
  1793.       2.  Select the script  file  directly from the <Alt-F> Directory File
  1794.           Manager (section 4.6.1).  If the file cursor is over a  file with
  1795.           a .BSC suffix, pressing E will execute the script.
  1796.  
  1797.       3.  Use the \SC[filename;label]   command  in  any  BOYAN macro.  For
  1798.           example,  you  could  assign   a   function   key  to  the  macro
  1799.           \SC[tcomm;DownLoad] .    Another  use might be to  set  macro  #9
  1800.           (Start-Up  macro) or macro #10 (Conclude  macro)  to  have  BOYAN
  1801.           automatically run a STARTUP.BSC or CONCLUDE.BSC script  each time
  1802.           it  starts  or  concludes.   You can also invoke  a  script  file
  1803.           directly from the DOS command line, as described above in section
  1804.           5.4.
  1805.  
  1806.  
  1807.    5.5.4:  BOYAN Power--Macros and Script Files                         114
  1808.    ________________________________________________________________________
  1809.  
  1810.  
  1811.    5.5.4  During Script Execution
  1812.  
  1813.    Once  a script file takes control, the  BOYAN v5  message in the  middle
  1814.    of the status line disappears, and  the  script file name flashes in its
  1815.    place.  When this happens, BOYAN is "unattended" and its normal terminal
  1816.    mode commands are disabled.  To regain control before  the  script  file
  1817.    finishes, you must press the <Esc> key.
  1818.  
  1819.    The <Tab> key also has a  special  function during script execution.  If
  1820.    you press <Tab>, the script stops whatever task it is  in  the middle of
  1821.    and jumps to  the  block  labelled  *TAB.    It  is as if pressing <Tab>
  1822.    inserts the command \GB[*TAB] into the middle of your script.   The Host
  1823.    Mode  script  uses  this feature to make the Sysop Menu available at all
  1824.    times.
  1825.  
  1826.    Another special script block is the *WRAPUP block.   Whenever  a  script
  1827.    finishes, either normally or by <Esc>, BOYAN searches for and executes a
  1828.    block in that script  named  *WRAPUP.  Consult HOST.BSC and ETCH.BSC for
  1829.    examples of how to use *WRAPUP.
  1830.  
  1831.    5.5.5  Script Examples
  1832.  
  1833.    Several  sample  script  files are included on  the  BOYAN  Distribution
  1834.    Diskettes.  These scripts are well-commented, so by  studying  them, you
  1835.    can learn a lot about writing your own scripts.
  1836.  
  1837.     - CIS.BSC  is a simple script file for logging  on  to  the  CompuServe
  1838.       Information Service.  You must use a text editor to include  your own
  1839.       CompuServe ID in the script file.
  1840.  
  1841.     - ETCH.BSC demonstrates macro screen  control  by  turning BOYAN into a
  1842.       computer etch-a-sketch!  After invoking this script (with the <Alt-R>
  1843.       command), use the I,J,K, and M keys to "draw" on  the  screen.  Press
  1844.       <Esc> to exit the script.
  1845.  
  1846.     - HOST.BSC contains the complete BOYAN Host Mode.  This script  is very
  1847.       complex,  using  extensive  branching,  file transfers, DOS commands,
  1848.       macro arithmetic, and  BOYAN  Auto-macros.  Section 4.8 describes how
  1849.       to use the Host Mode.
  1850.  
  1851.     - PCBOARD.BSC is a simple logon script file for the  PC-Board  type  of
  1852.       Bulletin Board System.  It expects that macro #72 (the <F2> keystroke
  1853.       macro) contains your full name +  the  { symbol.  By configuring this
  1854.       keystroke macro and entering your password into the Dialing Directory
  1855.       entry, you do away with the need to edit the PCBOARD.BSC file.
  1856.  
  1857.  
  1858.    5.5.5:  BOYAN Power--Macros and Script Files                         115
  1859.    ________________________________________________________________________
  1860.  
  1861.  
  1862.     - TCOMM.BSC  is  a  logon script file for TComm Bulletin Board Systems.
  1863.       It also expects your name + { to be stored in macro #72.  This script
  1864.       demonstrates  a  very  flexible  method  for  responding  to  prompts
  1865.       regardless of the order in which they arrive.
  1866.  
  1867.     - VARS.BSC displays the 36 user variables in two full-screen displays.
  1868.  
  1869.    BOYAN's Trace Mode  (section  5.2.17)  is  a terrific aid in following a
  1870.    script as it runs.  Many other script files written  by  BOYAN users are
  1871.    available for downloading from the BOYAN Support BBS.
  1872.  
  1873.    5.5.6  Technical Notes
  1874.  
  1875.    5.5.6.1  The Macro Compiler
  1876.  
  1877.    Macros are automatically compiled as they are run; there is  no separate
  1878.    compiling stage.
  1879.  
  1880.    When  interpreting  text  enclosed  in  brackets, the compiler  makes  a
  1881.    distinction depending on whether the text is a [string] or a [macro]:
  1882.  
  1883.     - In a string, the first unquoted right bracket always denotes  the end
  1884.       of the string; in order to  include  a right bracket inside a string,
  1885.       you must precede the bracket with a quotation mark.  For  example, to
  1886.       make BOYAN WaitFor the "Press  [Enter] to continue" message, you must
  1887.       write:
  1888.  
  1889.            \WF[Press [Enter"] to continue]
  1890.  
  1891.       As  a string is compiled, all macro variables  contained  in  it  are
  1892.       expanded.
  1893.  
  1894.     - However, in commands which  have  a [macro] in their syntax (the \RE,
  1895.       \UN, \UT, and all conditional commands),  the  compiler automatically
  1896.       matches  internal brackets.  For example, to  REpeat  (5  times)  the
  1897.       command \RX[1] \RY[1], you would simply write,
  1898.  
  1899.            \RE5[\RX[1] \RY[1]]
  1900.  
  1901.       without  having  to  quote  the  brackets inside.  Variables are  not
  1902.       expanded inside macros; for example, the macro
  1903.  
  1904.            \UT`12:00[\DM[%HR:%MI:%SE]]
  1905.  
  1906.       displays a running clock  on  the screen until noon, rather than just
  1907.       displaying  whatever  the  time  was  when you first invoked the  \UT
  1908.       command.
  1909.  
  1910.  
  1911.    5.5.6.1:  BOYAN Power--Macros and Script Files                       116
  1912.    ________________________________________________________________________
  1913.  
  1914.  
  1915.    The macro processor ignores spaces and tabs between macro commands.   If
  1916.    you actually want to send a number of spaces to the modem, add a "dummy"
  1917.    backquote following those spaces, as in
  1918.  
  1919.         here come five spaces     `
  1920.  
  1921.    Alternatives are to precede each space with a quotation mark, or  to use
  1922.    the macro \CH[32].
  1923.  
  1924.    5.5.6.2  Variable Prefixes: % vs. @
  1925.  
  1926.    BOYAN  Macro  Variables may be referred to with either the %  or  the  @
  1927.    prefix.    When  a variable is specified by %, then  any  special  macro
  1928.    command characters (such as ^ % @ \ ` ,  etc.)  are automatically quoted
  1929.    with ".  When specified by @, no extra quoting is done.
  1930.  
  1931.    For example, assume that variable V0 holds the string D:\UL.  If a macro
  1932.    referred to  that  variable  as  %V0,  BOYAN  would add a quotation mark
  1933.    before the \, as it does before every special character.    As a result,
  1934.    BOYAN would  send  the  literal  string D:\UL to the modem.  It does not
  1935.    treat \UL like a macro command, but rather like a bunch of characters.
  1936.  
  1937.    Now, change the % to  a @, making the variable @V0.  In this case, BOYAN
  1938.    does not add  a  quotation mark before the \.  It would send the D and :
  1939.    over  the  modem  and report a syntax error on the  \UL  macro  command.
  1940.    Thus, one use  for the @ variable prefix is to execute the contents of a
  1941.    variable as if they made  up  a  BOYAN  macro.   This is why the Dialing
  1942.    Command refers to the System Fon number as @SF rather than  %SF--so that
  1943.    Shortcut  macros,  etc.  may be used within the phone number.  A similar
  1944.    application of the @ prefix can be seen in the <Alt-M> macro.
  1945.  
  1946.    Another use  of  the  @  prefix is to force the evaluation of a variable
  1947.    which is used within another variable.  For example, suppose at  1:15 pm
  1948.    you set V1 and V2 as follows:
  1949.  
  1950.    \SV1[Time is %HR:%MI]
  1951.                         (This sets V1 = Time is 13:15.)
  1952.    \SV2[Time is "%HR:"%MI]
  1953.                         (This sets V2 = Time is %HR:%MI.)
  1954.  
  1955.    If you displayed these variables on the monitor five minutes  later, you
  1956.    would get the following results:
  1957.  
  1958.    \DM[%V1]             displays, Time is 13:15
  1959.    \DM[@V1]             displays, Time is 13:15
  1960.    \DM[%V2]             displays, Time is %HR:%MI
  1961.    \DM[@V2]             displays, Time is 13:20
  1962.  
  1963.  
  1964.    5.6:  BOYAN Power--Macros and Script Files                           117
  1965.    ________________________________________________________________________
  1966.  
  1967.  
  1968.    The  automatic  quoting  done in interpreting  %V2  means  that  %HR  is
  1969.    displayed, not evaluated.  In  contrast, @V2 substitutes the contents of
  1970.    V2 directly into the \DM[..] command, so %HR and %MI are evaluated.
  1971.  
  1972. ********* End Chapter 5 **********
  1973.