Chip 2000 November/Chip_2000-11_cd2.bin/sharewar/wincron/WinCron.CAB/commands.txt

Text File | 2000-04-22 | 17.6 KB | 550 lines

WinCron - Internal Commands Reference (Version: 1.40)
=====================================

  INTERNAL commands are built into WinCron. All internal commands
begin with a "$". If a command does not begin with a "$" WinCron
assumes it is an EXTERNAL command and tries to execute it. External
commands are EXE, COM, or BAT files that reside on the hard drive.
WinCron cannot run internal DOS commands (like DIR, COPY etc), however
most internal DOS commands are duplicated with WinCron commands.

  Most internal WinCron commands take parameters such as filenames,
strings, or numeric values. Multiple parameters must be separated by
spaces. If a parameter consists of a filename or string that contains
spaces, it must be enclosed within quotes. Some commands (such as
commands that display messages or send keys) should not contain quotes,
or, if included, will be treates as regular characters (see detailed
reference).

Example:
    Quotes not required:    $COPY file1.txt file2.txt
    Quotes required:    $COPY "file 1.txt" "file 2.txt"


Command    Description
-------    -----------
$ASK     - Asks if you want to run a command.
$COMPARE    - Compares two strings
$COPY    - Copies a single file.
$DELAY    - Delays execution.
$DIAL    - Display/start dial-up connection.
$DISABLE - Disables a specified task.
$DISPLAY    - Displays bitmap pictures.
$ENABLE    - Enables a specified task.
$EXIT    - Exits the WinCron program.
$EXITWIN     - Exits Windows in a specific way.
$IF        - Compare two numbers
$IF{condition}    - Checks condition and runs command
    $IFEQUAL
    $IFNOTEQUAL
    $IFLESS
    $IFGREATER
$IFEXISTS    - Checks if a file exists.
$IFWINDOW    - Checks if a window is open.
$KILL    - Deletes a file.
$LOAD    - Re-loads the task list file.
$LOADNEW    - Loads new task list.
$LOG    - Writes a string to the WinCron log file.
$LOGBACK    - Backs up the wincron log file with the current date.
$MKDIR    - Creates a new directory.
$MSG    - Displays a message string and waits for OK.
$MSGLOG    - Writes a string to the Message log file and displays the log.
$NEWLOG    - Saves the log file using the current date .
$NO    - Executes commandline only if condition was false.
$PLAY    - Plays a media file.
$PROMPT    - Displays a prompt and waits for YES/NO.
$RENAME    - Renames or moves a file.
$RMDIR    - Removes a directory.
$RUN     - Runs a script.
$SAVE    - Saves task list (IE: to record "Last-Run" info).
$SEND    - Sends keys to a specific window.
$KEYS    - Sends keys to the currently active window.
$SETSTRING    - Assigns a string to a variable
$SKIPTO    - skips forward to a labelled line.
$START    - Loads document into associated application.
$STOP    - Aborts processing of the current script.
$WAITSEC - Waits for a specific time.
$WAITWINDOW    - Waits for windows to open or close.
$WRITE    - appends a string to a text file.
$YES    - Executes commandline if condition was true.

**Timer Commands:
$COUNTDOWN    - Starts a count-down timer.
$COUNTUP    - Starts a count-up timer.
$IFZERO    - Runs a command if the timer is zero.
$SETTIMER    - Sets the specified timer (0-9).
$TIMER    - Controls the timer operation.
$IFTIMER    - Checks if the timer is active.
$CHECKTIMER - Checks the timer value.


Detailed Reference:
===================
Note:    "Sets condition" means:
        If the command was successful the condition is set
        to YES (true), otherwise it is set to NO (false).
    Use the $YES and $NO commands to test the condition


Command    Description
-------    -----------
$ASK {commandline}
    Displays the task description and commandline and asks you if
    you would like to execute the task.

    Note:
    * Processing of additional tasks is halted until a button is
      clicked, so make sure someone is around to see the message!

$COMPARE {string1} <=> {string2}
    Compares string1 to string2 and sets the condition. Use the
    $IF{condition} commands to check the result

    Example:
        $COMPARE fred <=> barney   ;condition set to GREATER.
        $IFGREATER $MSG Fred is greater than barney

    Notes:    * Either string can contain on or more quotes.
        * Useful for comparing string variables

$COPY {source} {destination}
    Copies the source file to the destination. The destination
    MUST include a filename. Filename wildcards (*,?) are NOT
    supported. Sets condition.

    Example:
    $COPY C:\MY FILES\TEST.TXT C:\FOLDER\TEST.TXT

$DELAY {milliseconds}
    Delays for the specified period (Max 60 seconds). One second
    EQUALS 1000 milliseconds. Useful in scripts to delay keystrokes
    sent to other applications with the $SEND or $KEYS commands.

    See Also: $WAITSEC, $WAITWINDOW, $IFWINDOW

$DIAL {connection} {NOW}
    Brings up a pre-configured and named dial-up-networking
    connection. If NOW is specified the connection will be
    started immediately.

    Notes:
    * For Windows 9x ONLY!
    * for un-attended operation the password must be set in
      conjunction with the "Save password" option.
    * If the connection is active this command will display
      the connection status window. The connection can be
      shut down by sending appropriate keystrokes.

$DISABLE {ME|taskdescription}
    Disables the specified task from running. To disable the
    current task specify "ME" as the task description.

    Note:
    * Can't be used in scripts run from the command-line
    * Matches partial task descriptions. Be careful when naming
      tasks with similar descriptions!


$DISPLAY {option} {picturefile}
    Displays bitmap pictures in BMP, GIF or JPG format. Displays
    the picture but does NOT stop script execution.

    OPTIONS:
    * OPEN: Opens a full-screen window with a black background
        and displays the picture centred in the window.
        Clicking the window closes it.
    * NOCLICK: As above but cannot be closed with mouse click.
    * CLOSE: closes the display window.

    Example: $DISPLAY OPEN splash.bmp

$ENABLE {taskdescription}
    Enables the specified task. Useful for enabling tasks that
    only need to run after other tasks have finished or certain
    conditions are met.

    Note:
    * Can't be used in scripts run from the command-line
    * Matches partial task descriptions. Be careful when naming
      tasks with similar descriptions!

$EXIT
    Exits WinCron immediately.

$EXITWIN {method}
    Exits Windows using the specified method:
        LOGOFF, SHUTDOWN, REBOOT, or POWEROFF

    The system will exit in a friendly way. If other programs
    are running that can't be terminated the operation will fail.
    If you want to FORCE the method, and make other programs
    exit regardless, add an "!" to the end (IE: REBOOT!).

    Note:
    * For Windows 9x ONLY!

    CAUTION!:
    * Use this command carefully.
    * Data may be lost if applications are forced to exit!

$GETENV {n} {variable}
    Gets the system environment variable and assigns it to the
    numbered string variable {n}.

    Example:
        $GETENV 0 path
        $MSG The path is set to: %S0%
    Produces a message similar to:
        The path is set to: C:\DOS;C:\WINDOWS;C:\WINDOWS\COMMAND

$IF {n1} {comparison} {n2}
    Compares numbers n1 and n2 and sets the condition.
    Valid comparisons are: =, >, <, <=, >=, <>

    Example:
        $IF %sec% > 20
        $YES $MSG The seconds are greater than 20

    Notes:    * Does a NUMERIC comparison.
        * Strings are converted to numbers
        * There MUST be a SPACE between each parameter

$IFEQUAL {commandline}
$IFNOTEQUAL {commandline}
$IFLESS {commandline}
$IFGREATER {commandline}
$IFLE {commandline}
$IFGE {commandline}
    Runs the commandline if the condition matches. You can also
    use the shorthand equivilents: $EQ, $NE, $LT, $GT, $LE, $GE

    $LE = Less than or equal to
    $GE = Greater than or equal to


$IFEXISTS {filename}
$EXISTS {filename}
    Checks if a file exists. Sets the condition to YES if the file
    exists, or NO if it doesn't.

    Example script:
        $EXISTS c:\test.txt
        $YES $MSG The file exists.
        $NO $MSG The file does not exist.

$IFWINDOW "{title}"
    Sets the condition to YES if a window is open, or NO if it is not.

    Notes:
    * True when any window is open whose titlebar BEGINS with {title}.
    * Not case sensitive.
    * Begin the title with "*" to match string anywhere in the titlebar.
    * Title MUST be enclosed in quotes

$KEYS {keylist}
    Sends keys to the currently active window/dialog. Similar
    to the $SEND command except does not activate a window.    See
    the $SEND command for details. ALL keys including quotes if
    specified will be sent. Sets condition.

$KILL {filename}
    Deletes a file. Sets condition.

$LOAD
    Re-loads the task list file (wincron.dat). Useful if you'd
    like to update tasks while wincron is running.

    Notes:
    * Always loads even if tasklist is the same.
    * Caution: "Last run" info from current task list will be lost!

$LOADNEW
    Looks for the file "wincron.new" and if it exists replaces the
    current "wincron.dat" file and re-loads the new task list.
    Similar to $LOAD except only updates when nessesary.

    Note:
    * Caution: "Last run" info from current task list will be lost!

$LOG {string}
    Writes the string to the event log file (wincron.log). Always
    writes even if logging for the event is not enabled. Writes
    exact string, including quotes.

    Note:
    * If no string is specified then the event description will
      be written to the log (the same as if you had left the exe
      field blank).

$LOGBACK
    Backs up the log file with the current date (YYYYMMDD.log).
    The current log is NOT erased.

$MKDIR {directoryname}
    Creates (makes) a new directory. Sets condition.

$MSG {icon} {string}
    Displays the message string and waits for OK. Writes exact
    string, including quotes. To add an optional icon to the message
    include one of the following at the beginning:

        -x    Critical
        -?    Question
        -!    Exclamation
        -i    Information

    Examples:
        $MSG Time to go home!
        $MSG -x Oh no!

    Note:
    * Processing of additional tasks is halted until the OK button
      is clicked, so make sure someone is around to respond!
    * See also $MSGLOG

$MSGLOG {option} {string}
    Writes the string to the Message log file (message.log) and
    displays the messages window if not visible. The CLEAR button
    will erase all messages and start a new log file. Use this
    command when you need to display messages but do not wish to
    stop processing of additional tasks (like the $MSG command).

    If -x option is specified only the file will be updated. The
    message window will not update or appear.

    Note:
    * The Log size is unlimited, however the maximum that can be
      displayed in the window is the first 32,000 bytes.

$NEWLOG
    Saves the event log using the current date (YYYYMMDD.log) then
    clears the log.

    Notes:
    * Make sure this is only done ONCE a day or the old log will
      be overwritten!
    * A good idea is to set an event to run at 23:59 each day.

$NO {commandline}
    Executes the commandline only if previous condition was false.

$PLAY {mediafile} {OFF|NOWAIT}
    Uses ActiveMovie2 to play the specified mediafile. Supported
    formats include:
      WAV, MID, MPG, MP3, AVI, MOV, QT, RAM and others.

    Notes:
    * $PLAY waits for the file to finish playing before continuing
      unless the NOWAIT option is specified!
    * To stop whatever is currently playing use $PLAY or $PLAY OFF
    * Refer to the README file for instructions on installing
      the ActiveMovie MCI driver.

$PROMPT {promptstring}
    Displays the prompt string with YES and NO buttons. Displays
    the exact string, including quotes. The condition is set to
    YES or NO depending on the user's response.

    Note:
    * Processing of additional tasks is halted until a button is
      clicked, so make sure someone is around to respond!

$RENAME {filename} {new_filename}
    Renames the file to the new filename. Can also move files by
    specifying a different path for "new_filename". Sets condition.

    Examples:
      $RENAME TEST.TXT TEST.BAK
      $RENAME "C:\TEST 2.TXT" "C:\BACKUPS\TEST.TXT"

$RMDIR {directoryname}
    Removes a directory provided it is completely empty.
    Sets condition.

$RUN {scriptname}
    Runs a script (text file) containing WinCron, EXE, or COM
    commands. The script is executed line-by-line. Internal
    variables may be used in any line. See the SCRIPTS section in
    the main documentation file for more details.

    Note: Do not use the $RUN command inside a script!

$SAVE
    Saves the task list. The "Last run" and "Run count" are also
    saved as part of the task list.

$SEND "{Title}" {keylist}

    Activates the window or dialog box with a titlebar containing
    the specified {Title} string, then sends keys to the window.
    The title MUST be enclosed in quotes and there must be a space
    between the title and the keylist. The {keylist} is a list
    consisting of one or more standard or special keys and/or
    key-control commands. See the SENDKEYS reference file for
    {keylist} details.

    Notes:
    * If there is no exact match for {Title}, any window/dialog
       whose title string BEGINS with {Title} is activated.
    * To find windows that contain the {Title} string ANYWHERE
      in the title, start the title with a "*".

        IE: $SEND "*Netscape" %{F4}

        Will send ALT-F4 to the FIRST netscape window.

    * If no window can be activated the condition is set to NO.
    * Only works with Windows applications! Does NOT work with
      DOS commands even when run in a window.
    * Keys can't be sent to minimized windows.
    * Title MUST be enclosed in quotes
    * The {keylist} can include quotes anywhere and will be sent
      just like any normal character.

    Example:
    To calculate the square root of 69 using the standard
    Windows calculator enter the following command:
        $SEND "Calculator" {DEL}69@

    Will send the keys: DELETE,6,9, and @  to the window.
    Special keys are sent by enclosing them in braces. In this
    example the "@" symbol is the keyboard equivilent to clicking
    on the SQRT button inside the calculator.

$SETSTRING {n} {string}
    Assigns the string to the numbered string variable (0 to 9).
    The entire string including quotes if included will be assigned
    to the string variable. To use a string variable in another
    command use the form %sN% where 'N' is 0 to 9.

    Example:
        $SETSTRING 0 "This is a test"
        $MSG The string is: %s0%

    Will display:
        The string is: "This is a test"

$SKIPTO {label}
    Skips FORWARD in the script to the specified label. Labels are
    not case sensitive and must be on a line by themselves. Any
    line in a script with a ":" as the first character of the line
    is considered a label.

    Script Example:

        $IFTIMER 0
        $NO $SKIPTO NoTimer
        $MSG The timer is running
        $SKIPTO Exit
        :NoTimer
        $MSG The timer is not running
        :Exit

$START {document}
    Starts the application associated with the specified document
    and loads the document.

    IE: $START readme.txt
    - loads the readme.txt file into the application associated
      with TXT file extensions (usually notepad)

$STOP
    Aborts processing of the current script. Can be used in
    conjunction with the $YES and $NO commands or to stop scripts
    from continuing to labeled lines below.

$WAITSEC {seconds}
    Waits until the seconds value of the current time is equal to
    or past the specified value (Max 59 seconds). Could be used in
    place of $DELAY when you need to syncronize to a specific time.

$WAITWINDOW {OPEN|CLOSE} {Title} {Timeout}
    Waits for window with specified title to open or close. The
    Timeout value determines how long to wait (seconds) before
    continuing. Maximum wait is 60 seconds.

    Example: $WAITWINDOW CLOSE "Calculator" 10

$WRITE "{filename}" {string}
    Appends the string to the specified file. The filename MUST
    be enclosed in quotes and must be followed by a single space.
    The entire string, including quotes if specified, will be
    written to the file.

    Note:    A carriage return will NOT be written to the file unless
        specifically included using the %CR% or %CRLF% variable.

$YES {commandline}
    Executes the commandline only if previous condition was true.


**** Timer Commands ****

There are 10 timers, numbered 0 to 9 that you can use for general
purpose timing. Timers work using minutes only.
    * Timers can be STOPPED or ACTIVE
    * Active timers can count UP or DOWN.
    * Active timers can be COUNTING or PAUSED.

$COUNTDOWN {n} {minutes}
    Starts a countdown timer from specified minute.

$COUNTUP {n}
    Starts an up-counter at zero.

$IFZERO {n} {commandline}
    Runs the commandline if the selected timer is zero. If the
    timer is zero this command will stop the timer to ensure the
    commandline only runs once.

    Note:
    * The COUNTDOWN/COUNTUP and IFZERO commands are designed
      for simple (non-script) timer operations. For complex
      timing use the commands below.

$SETTIMER {n} {minutes}
    Sets the value of the specified timer (0-9).

$TIMER {n} {option}
    Controls the timer operation. Valid options are:
    * STARTUP    - Starts timer going up.
    * STARTDOWN    - Starts timer going down.
    * PAUSE        - Pauses the timer.
    * RESUME    - Continues the timer.
    * STOP        - Stops the timer.

    Example: $TIMER 0 STARTUP

$IFTIMER {n}
    Checks if the timer is active (timing up or down) and sets the
    condition to YES or NO.

$CHECKTIMER {n} {minutes}
    Checks the timer and sets the condition to EQUAL, LESS or
    GREATER. Use the $IFEQUAL, $IFLESS or $IFGREATER commands
    to check the result.

    NOTE:
    * Does NOT change the timer status (in comparison to $IFZERO)


Timer example
-------------

    Task 1:    DESC: Start timer 0 to count up
        EXE : $COUNTUP 0

    Task 2:    DESC: Display message based on 10 minute mark
        EXE : $RUN timer.wcs
        When: Schedule the task to run every minute

    TIMER.WCS Script:
        $IFTIMER 0            ;Is the timer active?
        $NO $STOP            ;No, stop the script
        $CHECKTIMER 0 10        ;Has 10 minutes elapsed?
        $IFLESS $MSG Wait some more...    ;LESS
        $IFEQUAL $MSG 10 minutes is up!    ;EQUAL
        $IFGREATER $MSG Overtime!    ;GREATER
        $IFGREATER $TIMER 0 STOP    ;Stop timer counting

<END>