The Devil's Doorknob BBS Capture (1996-2003)/devilsdoorknobbbscapture1996-2003.iso/Dloads/WINDOWSU/UNICOM.ZIP/UCSCRIPT.HLP

Text File | 1990-08-05 | 27KB | 843 lines

& "Introduction"

A script file is a text file constructed by you containing
commands that UNICOM will execute.  Script files are useful
in automating manual tasks such as dialing, logging in,
initiating file transfers, hanging up and so on.

Instead of manually entering commands to UNICOM and to a host
computer, complex tasks may be performed automatically with
the execution of a single script file.

Consider the following script language commands:

WHILE NOT CONNECTED        ; This step will repeat dial until
  DIAL "555-6666"          ; the remote computer answers
ENDWHILE

WAITFOR "Password:"        ; We wait for the password prompt
SEND "your password"       ; then send it to the remote

WAITFOR "command prompt"   ; Wait until we are prompted
SEND "download command"    ; then issue a download command

GETFILE protocol "received.dat"  ; retrieve a file

WAITFOR "command prompt"   ; Again, wait until we are
                             prompted
SEND "logoff command"      ; then logout
HANGUP                     ; Tell UNICOM to hangup, we're
                                                    done

This example illustrates how a script language file can be
used to automate the manual tasks of dialing, transferring
data and disconnecting the phone line.

A script file may also be constructed to make decisions
based on information or events encountered during execution.

The following example illustrates conditional branching:

   Message "Do you Wish to Quit?" "?" yesno
   IF yes
     QUIT         ; exit UNICOM if User presses the yes
button
   ELSE
     .
     .  <-------- IF No, These steps are performed
     .
   ENDIF


The example above will display a message within a windows
message box that contains two buttons: yes and no.
If the user presses the yes button, a predefined conditional
variable named 'yes' will become true.  The IF statement is
used within the script language to test the value and branch
accordingly.

UNICOM supports other statements that can be used for
conditional branching.  See the WHILE and SWITCH statements
in the Script Command Language Definition section.

Additional, more powerful script language applications may
be developed beyond the examples discussed so far.  UNICOM
provides a rich and powerful set of commands that can be
used to solve very complex tasks.

UNICOM script statements and commands span the following
categories:

 1) Script Execution Control:
    IF, WHILE, SWITCH, CASE, EXIT, EXECUTE, TRACE

 2) File Control:
    CHDIR, LOG

 3) Query Functions:
    FINDWINDOW, FINDFILE, FIND

 3) Program Settings:
    PORT, EMULATE, ASSIGN

 4) Port Interaction and Control:
    BREAK, FLUSH, WAITFOR, SEND

 5) User Interaction:
    ALARM, MESSAGE, INPUTSTRING, DISPLAYSTRING

 6) Action Processing:
    DIAL, HANGUP, GETFILE, SENDFILE, DELAY, SNAPSHOT

 7) Process and Window Control:
    KILLWINDOW, SHOWWINDOW, MOVEWINDOW, TITLEWINDOW, RUN, CLEAR



& "Script Language Syntax"

All script commands are case insensitive.  String variables
may be substituted for all commands that specify an immediate
string parameter.  For example:
Send "Hello"

Will instruct UNICOM to transmit the same string as in the
following case:
Assign s1 "Hello"
Send s1

UNICOM script command statements may be written using UPPER
and/or lower case.

Blank spaces must delimit command arguments.  Double quote
characters can be used to enclose a string argument
containing spaces as shown in the example below.

ASSIGN arg1 "This quoted string is one argument"

Only one script command is allowed per line.  Lines are
limited to 80 characters in length.  Command arguments cannot
wrap around to the next line.

& "Editing and Creating Script Files"

Your personal text editor may be activated from UNICOM when
editing or creating script language files.  Before using this
feature, the complete editor pathname must be stored in the
script editor field located within the general setup window.

To open a script file for editing, select the edit command
from the script menu.  A file selection window will appear
displaying all files found in the UNICOM directory with a
.SCR extension.


& "Executing Script Command Files"

Script files may be executed at any time when in terminal
mode.  To activate a script file, select EXECUTE from the
script menu.  A file selection window will appear displaying
all files found containing a .SCR extension in the UNICOM
files directory.

Once invoked, a script file will execute until an EXIT
statement is encountered.  Script execution may be
interrupted at any time by pressing the ESC key.

During script execution, the UNICOM keyboard remains enabled
for user interaction.

& "Tracing Script Execution"

Script file commands may be echoed to your screen as they are
executed.  To enable this feature, select the TRACE menu
toggle from the script menu.  Each command will be echoed
line by line starting at the top of the terminal screen.
After reaching the bottom of the terminal screen buffer,
additional echoed commands will cause the terminal to scroll.

Tracing is useful for observing the behavior of a script file
during execution.  Tracing may be enabled or disabled via
script command or through a menu selection.


& Alarm

ALARM [seconds]

The ALARM command will alert the user to an event by ringing
the speaker bell.  The [seconds] parameter determines the
amount of time the alarm will sound.  If the [seconds]
parameter is omitted, the alarm will sound for 1 second.

Returns: nothing
Example:  ALARM 4        (Sounds and alarm for 4 seconds)

& Assign

ASSIGN variable "string"

This command assigns the value of "string" to a user defined
variable.  To set a user variable from within your command
file, use the ASSIGN command.

Returns: nothing
Examples: ASSIGN MyVar "Hello World"
          ASSIGN V3 MyVar

& Break

BREAK [time]

The BREAK command will place the communication line into a
break state. The optional [time] argument determines the
length of the break in milliseconds.  If [time] is not
specified, UNICOM will default to 350 milliseconds.

Returns: nothing
Examples: BREAK          (sends a 350 msec break)
          BREAK 250      (sends a 250 msec break)


& Chdir

CHDIR "drive:directory"

The CHDIR command will change the default drive and/or
directory to that specified in the argument string.

Returns: SUCCESS
Examples: CHDIR "D:"          ( sets the drive to D:)
          CHDIR "C:\WINDOWS"  ( default to drive c:\windows)
          CHDIR "\Win"        ( default to directory \Win)

& Clear

CLEAR

CLEAR will erase the contents of the current terminal display.
The scrollback buffer is not affected.  If operating in color
mode, the screen will be set to the currently selected
background color.

Returns: nothing
Example:  CLEAR     (erases the terminal screen)

& Delay

DELAY [milliseconds]

This command will pause script execution for the specified
number of milliseconds.  Data arriving from the
communications port is buffered during this delay.  The
amount to delay should not exceed the time necessary to fill
4K at the current baud rate.

UNICOM will default to a 1 second delay if the time argument
is omitted.

Returns: nothing
Example:  DELAY 5000     (pauses the script 5 seconds)

& Dial

DIAL  "phone number"

The DIAL command will instruct the modem to dial the number
specified in the argument string.  The string is prefixed
with  a Hayes dialing command.  Use the IF [NOT] CONNECTED
command obtain the success or failure of this command.

Returns: CONNECTED
Example:  DIAL "555-1212"  (causes ATE1D*555-1212 to be sent to the
modem)
                           * = T or P as defined in modem setup.

& DisplayString

DISPLAYSTRING row column "string"

This command will place an argument string at the specified
row and column on the terminal screen.  The row values may
range from 0 to 23.  The column values may range from 0 to
79.  If the row and column arguments are omitted,
DISPLAYSTRING will default to row 0 and column 0.  The
current terminal cursor position is not affected.

Returns: nothing
Example: DISPLAYSTRING 4 6 "Hello" (places Hello at row 4 column 6

& Emulate

EMULATE [ansi|vt52|tty|color]

This command sets UNICOM to operate using the specified
terminal emulation.  If no argument is provided, UNICOM will
default to ANSI Color Emulation.

Returns: nothing
Example:  EMULATE ansi (sets UNICOM to B&W ANSI Emulation)

& Execute

EXECUTE "cmd file"

The EXECUTE command allows you to begin execution of a
different script file.  The currently executing script file
is interrupted  and control does not return.  This command
is a one-way chain to another script command file.  The
complete file specification must be provided in the
argument.  String variables are not reset when chaining to
different script files and may be used by the called file.

Returns: nothing
Examples: EXECUTE "login.scr"  (execute file login.scr)
          INPUTSTRING  FileName "Enter the File to Execute"
          EXECUTE FileName

& Exit

EXIT

The EXIT command terminates the executing script file and
returns UNICOM to Terminal Mode operation.

Returns: nothing
Examples: SEND "Terminating Session" (disconnect host)
          HANGUP                     (hangup modem   )
          EXIT                       (enter Terminal Mode)

& Find

FIND VarName "Target"

The FIND command examines the specified variable for an
occurrence of the "target" string.  The result of this command
can be obtained using the IF FOUND command.  The FIND command IS
CASE SENSITIVE.

Returns: FOUND
Examples: INPUTSTRING S1 "Enter a Password"  (get response)
          FIND S0 "password"                 (search for
password)
          IF NOT FOUND
             MESSAGE "Invalid password" "ERROR"
          ELSE
             EXECUTE "other.scr"
          ENDIF


& FindFile

FINDFILE "filename"

The FINDFILE command is used to determine if a specific file
exists in the directory path specified in the DOS PATH
environment variable.  The IF [NOT] FOUND command should be
used to test the result of this command.

Returns: FOUND
Example: FINDFILE "unicom.exe"
         IF FOUND
           MESSAGE "Unicom was Found" "Attention"
         ELSE
           MESSAGE "Unicom Exists" "Found It!"
         ENDIF

& FindWindow

FINDWINDOW "targetwindowtitle"

The FINDWINDOW command is useful for testing for the
existence of any window.  The argument string must specify
the title appearing in the target Window.

Returns: FOUND
Example: FINDWINDOW "Clock"   (look for the clock application)
         IF FOUND
            MESSAGE "Clock Is Running" "Attention"
         ELSE
            MESSAGE "Clock Not Found" "Attention"
         ENDIF

& Flush

FLUSH [Receive|Transmit]

This command will empty the receive or transmit buffers.
Flushing should not be considered complete after execution
of this command.  Use of a DELAY command is recommended for
up to 1 second after flushing.

Returns: nothing
Example: FLUSH R      (empties the receive buffer)
         DELAY 1000   (allow time to flush completely)

& GetFile

*GETFILE [protocol]   ["filename"]
           XMODEMCS    "filename"
           XMODEMCRC   "filename"
           XMODEM1K    "filename"
           YMODEMBAT
           YMODEMG
           ZMODEM
           B
           QUICKB
           ASCII       "filename"

This command will initiate a file download with the specified
protocol.  The optional "filename" parameter is not required
for ZMODEM, YMODEM KERMIT, B, and QUICKB protocols since it
is provided by the host computer.  Use the IF [NOT] SUCCESS
statement to determine the result of the transfer.

Example: INPUTSTRING F1 "Enter a file to Download"
         GETFILE XMODEMCRC F1
         IF SUCCESS
             MESSAGE "FILE RECEIVED" "DOWNLOAD"
         ELSE
             MESSAGE "FILE RECEIVED FAILED" "DOWNLOAD"
         ENDIF

*NOTE: Use of GetFile requires registration

& Hangup

HANGUP [DTR] [droptime]

HANGUP (with no parameters) will cause the modem attention
sequence '+++' to be transmitted in an effort to place the
modem into command mode.  Once in command mode, the "ATH"
string is sent to disconnect the line.

If the DTR parameter is specified, UNICOM lowers the Data
Terminal Ready Signal for 'droptime' milliseconds to
instruct the modem to hang up.  The modem must be configured
to sense the loss of DTR.  There is no return value for this
hangup method.

The IF [NOT] CONNECTED command can be used to test the
result of the first hangup method.  The result is determined
by obtaining the modem OK result string upon sending the
hangup command.

Examples:  HANGUP
           IF NOT CONNECTED
              MESSAGE "Hangup Completed" "Attention"
           ENDIF

           HANGUP DTR 4000    (lowers DTR for 4 seconds)
& Host
HOST

The Host command causes UNICOM to enter host mode.
Script execution is halted at this line.

& IF

IF condition

The IF command is used to provide conditional control over
script execution.  The following syntax is represented as
follows:

IF condition
   [perform these commands]
    .
    .
ELSE
   [perform these steps]
    .
    .
ENDIF

IF (continued)

The ELSE is optional and there must be an ENDIF for every IF
statement.  Commands may be nested up to 12 levels deep.

Valid conditions for the IF command are SUCCESS, CONNECTED,
FOUND, WAITFOR, OK, CANCEL, ABORT, RETRY, IGNORE, YES, NO

The OK, CANCEL, ABORT, RETRY, IGNORE, YES and NO conditions,
when true, indicates the user response to a MESSAGE command.

The FOUND condition is used to test the result of the last
FIND type command.

FIND, FINDFILE, FINDWINDOW will set the FOUND condition
flag.  The CONNECTED condition is used to test the result of
the DIAL and HANGUP commands.  The WAITFOR condition is used
to check the result of the last WAITFOR command.  If the
"target" specified in the WAITFOR command was received, the
WAITFOR condition would be set true.  The WAITFOR condition
would be set false if the last WAITFOR command timed out
before receiving the "target".  The NOT operator may prefix
any conditionals.  The NOT will reverse the value of the
condition it prefixes.  For example, if SUCCESS is false,
then NOT SUCCESS would be true.

& InputString

INPUTSTRING variable ["user prompt"]

This command will display a pop-up window containing an Edit
Box to accept a user entered string.  When entered, the
string is assigned to the variable specified.  An optional
prompt string may be specified that will be displayed in the
title of the window.  The accepted string length is limited
to 80 characters.

Returns: SUCCESS
Example: INPUTSTRING V23 "Enter your Name"
The above example causes a Window titled:
 "Enter Your Name"  to appear with an edit box.

& KillWindow

KILLWINDOW "string"

The KILLWINDOW command searches for a window containing a
title matching the string argument.  If one is found, UNICOM
will send a Destroy message to that window.  Applications
may be destroyed if their top level (main) window is killed.

Returns: SUCCESS
Example: KILLWINDOW "Clock"   (kills the clock application)

& LoadKeys

LOADKEYS [filename]

The loadkey function loads a predefined keyboard macro file
into memory.  The User Key buttons (if displayed) are updated
immediately.  The keyboard macro file is expected to reside
in the UNICOM files directory.

& Locate

LOCATE row col

The LOCATE command positions the terminal cursor to the  row
and column specified.  Rows are numbered 0-23, columns 0-79.
Row 0, column 0 is defined as the upper left corner of the
screen.

Returns: nothing
Examples: LOCATE 10 20     (set cursor to row 10 col 20)
          LOCATE R1 CX      (set cursor row and col
                        contained in variables R1 and CX)

& Log

LOG [option]
     OPEN ["filename"]
     CLOSE
     SUSPEND
     RESUME
     TRUNC ["filename"]

The LOG command controls file logging during execution of a
script language file.  The OPEN command will create a new
file or append to an existing file by the same name.  If the
filename is omitted, UNICOM.LOG will be used by default.

The CLOSE command will close an open log file.
The SUSPEND command pauses file logging without closing the
file (maintaining its file position).
The RESUME command will resume logging once a SUSPEND
command has been executed.
TRUNC will open a log file and destroy the contents of
the file if it exists.


Returns: SUCCESS
Examples: LOG OPEN       (opens UNICOM.LOG for logging)
          LOG SUSPEND      (pauses logging)
          LOG RESUME       ( resume logging)
          LOG CLOSE        ( close log file)


& Message

MESSAGE "string" ["title"] [button options] [icon options]
        button options =   [ok]           (DEFAULT)
                           [abortretryignore]
                           [okcancel]
                           [yesno]
                           [yesnocancel]
                           [retrycancel]

        icon options   =   [iconhand]     (DEFAULT = No Icon)
                           [iconquestion]
                           [iconexclamation]
                           [iconasterisk]

When executed, the MESSAGE command will display a windows
message box containing a message passed in the string
argument.  The message box may contain an optional title
that will appear in the title of the window.  The button
style is selected using the optional button style field.  If
omitted, the OK style is used as a default.  An optional
icon can be displayed in the message box by specifying an
icon type in the icon options field.  If omitted, the
default for this field is no icon.  Message will set a
conditional flag that corresponds to the button selected by
the user.  The conditional flags shown below may be tested
using the IF statement.

Returns:  ok|cancel|abort|retry|ignore|yes|no
Example:  INPUTSTRING name "Enter your Name"
          MESSAGE name "You Entered" okcancel iconquestion
          IF cancel
            exit
          ELSE
            MESSAGE "You Entered Ok" "OK!"
          ENDIF

& MoveWindow

MOVEWINDOW "title" x y width height

This command will move and size any window.  The title argument
string is the title of the window to be moved.  The x and y
parameters represent the screen location where the upper left
corner of the window will be placed.  Width and height parameters
specify the dimension (in pixels) for resizing.  If omitted, the
x, y, width and height parameters will default to zero which can
produce strange results.

Returns: SUCCESS
Example: MoveWindow "Clock" 100 150 200 100

& Port

PORT "device;baud;parity;wordsize;stopbits;duplex"

PORT sets the communication port to the settings listed in
the argument.  All arguments are required, arguments must be
separated by semicolons with no separating blanks.

Returns:  SUCCESS
Example:  PORT "COM1;1200;N;8;1;FULL"
          PORT "NONE"    (Closes Current Port)

Argument Field           Supported Values
DEVICE                   NONE|COM1|COM2|COM3|COM4
BAUD                     300 |1200|2400|4800|9600|19200
PARITY                   N|E|O  (None, Even, Odd)
WORD SIZE                7|8
STOP BITS                1|2
DUPLEX                   FULL|HALF

& Quit

QUIT

When executed, the QUIT command will terminate execution of
the script file and immediately close UNICOM with no
questions asked.  The UNICOM window is destroyed.

Returns: nothing
Example:    SEND "Bye"    (log off host)
            HANGUP        (hangup the modem)
            QUIT          (exit UNICOM)

& Run

RUN "program" [param1 param2 ...paramN]

The RUN command will execute another Windows or DOS
application.  RUN sets the SUCCESS condition flag if the
program was successfully run.

Examples:  ASSIGN prog "Excel.exe"
           RUN prog
           IF SUCCESS
             MESSAGE "Excel is running" "OK!"
           ELSE
             MESSAGE "Unable to Run Excel" "ATTENTION"
           ENDIF

& Send

SEND "string"

The SEND command will transmit the specified string to the
remote host computer.  Control characters can be transmitted
with the use of the '^' prefix character.

Returns:  nothing
Example:  SEND "Hello^M"   (sends Hello followed by a CR)

& SendFile
* SENDFILE  [protocol][filename|filelist]
              KERMIT    "filename"
              XMODEMCS  "filename"
              XMODEMCRC "filename"
              XMODEM1K  "filename"
              YMODEMBAT file1 [file2 file3 ...]
              YMODEMG   file1 [file2 file3 ...]
              ZMODEM    file1 [file2 file3....]
              ASCII     "filename"
              B         "filename"
              QUICKB "filename"

The SENDFILE command will initiate a file upload to the
remote host computer using a protocol specified in the
list above.

Returns:  SUCCESS
Examples: WAITFOR "Begin the transfer now"  (wait until ready)
          ASSIGN F1 "stock.xls"
          ASSIGN F2 "tax.xls"
          INPUTSTRING F3 "Enter another File to send"
          SENDFILE ZMODEM F1 F2 F3 "other.dat"

The above example sends files stock.xls, tax.xls, a user named
file in F3, and other.dat using ZMODEM batch protocol.

* NOTE: Use of this function requires Registration


& ShowWindow

SHOWWINDOW "title" [HIDE|ZOOM|MINIMIZE|SHOW]

SHOWWINDOW will control the appearance of any Window that
can be identified by its title.  Optional parameters shown
above, instruct the window to enter a new state as defined
below:

HIDE:      Iconize the window and activate another
ZOOM:      Zoom the window to full screen
MINIMIZE:  Activate window - display as iconic
SHOW:      (DEFAULT) Activates and displays a window. If it
is iconic or Zoomed, the window is restored to its original
size and position.

Returns: SUCCESS
Example: SHOWWINDOW "Clock" ZOOM   (zooms clock to full screen)

& SnapShot

SNAPSHOT

This command will send the current contents of rows 0-24 of
the terminal screen to the windows spooler for printing.

Returns: nothing
Example: SNAPSHOT

& SWITCH

SWITCH variable

The SWITCH command allows script execution to branch
conditionally based on comparison of the SWITCH argument to
a CASE argument.  SWITCH compares the value of a string
variable against the values of CASE arguments.  Control will
branch to the next command following a matching CASE
argument.

  SWITCH NAME              (Compare cases to NAME variable)
    CASE "Alfred"          (if it matches  )
         (do these commands)
    ENDCASE                (until reaching ENDCASE)
    CASE "George"          (does NAME = George?)
    ENDCASE                (required to terminate each case)
    DEFAULT                (execute these commands )
  ENDSWITCH                (this ends the SWITCH   )

NAME is a string variable containing a string value obtained
by an ASSIGN or INPUTSTRING command.  A CASE argument found
to match the SWITCH argument, will cause UNICOM to begin
script file execution starting with the command immediately
following the matching CASE.  Execution continues until an
ENDCASE command is found.  Upon encountering an ENDCASE,
UNICOM skips to the command immediately following the
matching ENDSWITCH command and resumes execution.  Note that
each CASE statement must have a matching ENDCASE, and each
SWITCH a matching ENDSWITCH.  The optional DEFAULT case is a
special case that will be executed provided no CASE
statements evaluate to TRUE.  The DEFAULT case must be
positioned behind all CASE/ENDCASE statements for the
SWITCH.  If there is no DEFAULT case, and no other match is
found, command file execution will continue with the
statement following the ENDSWITCH command.

& TitleWindow

TITLEWINDOW oldtitle newtitle

This command will replace the title for the first window
found that contains a title matching the oldtitle parameter.

Returns:  nothing
Example:   ASSIGN TARGETWINDOW "Clock"
           TITLEWINDOW TARGETWINDOW "MyClock"

The above example will replace the title of the Clock
application with the argument string: "MyClock"

& Trace

TRACE [ON|OFF]

The TRACE command allows you to "trace" the execution of a
command file.  If you set TRACE ON, every command will be
echoed to the screen as it is executed.  TRACE is useful for
debugging script command files.

Returns: nothing
Example: TRACE ON       (sets tracing on)
         TRACE          (sets tracing off) DEFAULT

& Transmit

TRANSMIT "string"

See the SEND command - it is identical.

& Waitfor

WAITFOR "target" [delay]

The WAITFOR command allows you to pause script execution
until a specific string has been received from the remote
host.  The [delay] option instructs UNICOM wait for the
"target" string for a maximum of delay seconds before timing
out.  A timeout will cause execution to proceed.  If no
[delay] is specified, UNICOM will wait 30 seconds by
default.

Use the IF WAITFOR condition to test the results of a
WAITFOR command.  Control characters may be expressed in the
"target" string with the use of the '^' control prefix
character.

Examples: WAITFOR "^J USERNAME"   (waits for LF, space, USERNAME)
                                  ( using a 30 Second Wait)
          IF WAITFOR              (it found w/o timeout)
            TRANSMIT "username"   (send username)
          ENDIF

NOTE: WAITFOR targets are CASE SENSITIVE

& WHILE

WHILE condition

The WHILE statement allows commands that precede an ENDWHILE
statement to execute repeatedly until the WHILE condition
evaluates true.

Example:  WHILE NOT CONNECTED  (dial forever until connected)
            DIAL "555-1212"
          ENDWHILE