OS/2 Shareware BBS: 6 File/06-File.zip/dfsee510.zip/dfscript.txt

Text File | 2003-01-14 | 14KB | 351 lines

  Display File Systems; version 5.08 01-01-2003  (c) 1994-2003; Jan van Wijk
 ----------------------------[ www.dfsee.com ]-------------------------------


C O N T E N T S:
================

  Summary of scripting  = how to use scripting with DFSee
  Native scripts
  Batch scripts
  REXX scripts (OS/2 only)


S U M M A R Y   O F   S C R I P T I N G:
========================================

Scripting is a way to automate functions, in this case DFSee actions.

For DFSee there are now three ways to use scripting:


1) New in version 4.16: DFSee NATIVE scripting

   Here DFSee commands can be placed in a simple text-file and will be
   executed one by one.  This is the first implementation of the native
   script-engine that only supports a simple list of commands.
   The intention is to expand the capabilities of this script-engine
   with conditional constructs like IF and WHILE and more ...

   A NATIVE script for DFSee is executed from the DFSee commandline using
   the RUN command with the scriptname as a parameter. DFSee will select
   the NATIVE engine automatically based on the contents of the script.

   Native scripting can be very usefull for recovery scenario's where
   multiple partitions need to be recreated and for other repetive tasks
   like analysing an HPFS partition.



2) The classic way, using batch-files (.BAT or .CMD)

   In this case DFSee commands are executed by calling a DFSee executable
   for every DFSee (multi) command.

   Normal batch-logic like "if errorlevel ..." can be used to control the
   flow in the script.

   One disadvantage to this method is that there is just the returncode from
   a DFSee call to be used in subsequent operations.
   All DFSee commands that depend on each other need to be in a single
   multi-command to work as expected. This could be a problem as a result of
   the limited length of the (DOS) commandline.

   Another point is that the DFSee executable will be reloaded for each
   command executed, this can be real slow when working from diskettes.

   An example of such a script is the DFSUNFD.BAT and DFSUNFD.CMD that
   collects information needed for partition recovery.



3) For OS/2 only: the more comfortable way, using REXX as a script engine.

   Here the DFSee commands are executed by REXX using a 'subcommand-handler'
   in the DFSee executable. All commands are automatically routed there.
   Commands can also be sent to the shell (cmd.exe) by using 'ADDRESS CMD'.

   The REXX subcommand-handler in DFSee makes the most important internal
   DFSee variables available as REXX variables too, so it is much easier
   to interact with DFSee and use results from previous commands.

   A NATIVE script for DFSee is executed from the DFSee commandline using
   the RUN command with the scriptname as a parameter. DFSee will select
   either REXX or the NATIVE engine by checking the contents of the script,
   all REXX scripts need to start with the '/*' symbol in the first line.
   This is consistent with the behaviour of CMD.EXE on OS/2 platforms.

   An example of a DFSee REXX script is DFSINFO.CMD that collects
   information on all your disks and partitions in a (large) logfile.


N A T I V E   S C R I P T S:
============================

 RUN macro [args] = Run a DFSee macro in native format (list of commands)

 Purpose:       Execute a NATIVE DFSee script with multiple commands

 Parameters:    macro       The name of the macro-file, when no extention is
                            given a '.DFS' extention will be appended.

                args        Arguments to be passed as parameters to the macro
                            upto 9 arguments can be specified and can be used
                            anywhere in the script as '$1' to '$9' while $0
                            is the scriptname (without file extension)
                            Arguments can be enclosed in single- or double-quotes
                            to allow embedded spaces or special characters

 Options:       -v          verbose, show details about running the script
                -p-         no prompting and command-echo by the command handler
                -p:1        echo command by handler, but no prompting afterwards
                -p:2        no echo by handler, but prompting afterwards
                -p:3        echo before, and prompt after executing (default)
                -E:i        ignore errors, continue execution when RC is not 0
                -E:q        quit on any errors, exit  (default when in batch mode)
                -E:c        confirm by user on errors (default when interactive)
                -s          single-step, confirm each line before executing it
                -q          quit DFSee after executing the script


 Output:        SCRIPT progress when running in verbose mode, confirmation
                dialogs on errors, and regular output from executed commands

 Remarks:       All lines in the script that do NOT start with a ';' in the
                first column, are sent to the command-handler inside DFSee
                to be executed as a command. These commands can be multiple
                commands as usual (using '#' separators) and can also contain
                additional comment at the end of the command using ';' as a
                start-comment symbol.

                When using the -E:confirm or E:quit types of error handling,
                every returncode from a command that is not 0 will cause
                either the confirmation dialog, or terminate the script.

                The return-code (RC) for the whole script will be that of the
                last command that is executed in the script itself.

                Native scripts can RUN other scripts (nesting) but are limited
                to about 10 levels of nesting.


Native Pragmas:
---------------
The initial behaviour of the native script interpreter can be set with some
options of the run command. However, some of them can be changed by the
script itself using 'pragma' statements.

A pragma always starts with the ';;' sequence at the beginning of a line.



;;defaultparam  p  value

This will give a default 'value' to the parameter 'p' where p is 0..9
The default value is only effective if no value has been passed as
an argument to the macro.

One example of usage is to supply a default disk-number or partition
while allowing to specify a different value when needed.



The following pragmas alter the behaviour of the script interpreter
from within the script as initialy set by the corresponding options
on the RUN statement or from the builtin defaults.

;;verbose         [off]    set verbose mode on or off         (see -v)
;;prompt      [0|1|2|3]    set prompting and command-echo     (see -p)
;;error         [i|c|q]    set error handling for RC not 0    (see -e)
;;singlestep      [off]    single-step, confirm each line     (see -s)




Special Commands:
-----------------
Some commands have been added to DFSee to allow better scripting, they
are also available from the normal commandline.


 REM [anything]   = Do not do anything (but echo the command :-)

 Purpose:       Allow REMark lines in a script, like in batch-files

 Parameters:    any     optional   Anything you like

 Output:        None

 Remarks:       Yes please! That is the whole purpose of the thing.



 SAY    [text]    = Display text to the DFSee display and logfile

 Purpose:       Give messages to user and logfile from the script

 Parameters:    text    optional   A line of text to display and log

 Output:        The specfied text or an empty line when not specified.

 Remarks:



 SLEEP  [secs]    = Sleep for the specified number of seconds

 Purpose:       Hold processing for the specified time, for instance to
                allow a user to read some output

 Options:       -q                 Do not give a status message

 Parameters:    secs    optional   Number of seconds, default is 1 second

 Output:        A message indicating DFSee is sleeping (if no '-q' option)

 Remarks:       On OS/2 and Win-NT this is a non-blocking wait, so the system
                keeps responding normally :-)  On DOS it is a busy-wait.



Example native script
---------------------

This is a simple script that uses some specific DFSee HPFS commands
to analyse the current or a specified partition.
(script is included in the distribution as 'dohpfs.dfs')

;------------------ start script
;basic analysis for a HPFS partition
;;defaultparam 1 .
say Start analysis for partition $1
part $1
fs  hpfs                        ;force HPFS mode
d
d                               ;display next default sector
d
11                              ;display spareblock
d
d
alloc                           ;display allocation map
check
slt                             ;perform check and show SLT
findroot 12                     ;find the root directory
;----------------- end script

The next is a simple script to play with, and get used to the RUN options.
With the script in a file 'say.dfs', run it in a few different ways:

 run say
 run -s  say
 run -v  say "parameter one"
 run -p- say "parameter one"
 run -p- say one two three
 run -p- -v  say
 run -p- -v  say 1 2 3 "sleep 5"

;------------------ start script
;;defaultparam 2 THIS IS PARAMETER TWO
say line 1
say line 2
say $1 $2 $3
$4
say last line
;----------------- end script

Note: The run commands above are available as another script: 'runsay.dfs'
      which is part of the distribution together with 'say.dfs' itself.


B A T C H    S C R I P T S:
===========================

There is really nothing special about batch scripts using DFSee.
One thing to be aware of is that the renage of return-codes is
limited to 65535 (16 bits numbers) on the DOS platform.

This could lead to problems if the DFSee 'query' command is
not used carefully for instance to check disk sizes ...

Also the length of the commandline on DOS is limited to just
over a 100 characters on DOS. (OS/2 and NT more than 2000)



R E X X   S C R I P T S:
========================

scripts for OS/2 only:

 RUN macro [args] = Run a DFSee macro in a REXX file

 Purpose:       Execute a REXX script using the 'DFS' environment

 Parameters:    mf      mandatory  Macro file specification

                arg     optional   Arguments to the REXX macro

 Output:        Any output from the REXX macro including (OS/2) commands
                executed from the macro.

 Remarks:       The RUN command recognizes REXX scripts by contents, the
                first two characters must be '/*' which is a REXX comment.
                Other files will be handled as NATIVE DFSee script files.

                DFS commands can be issued from within the macro, this
                is the default environment (Address DFS).
                Commands for CMD.EXE must be addressed using 'Address Cmd'

                The following REXX variables will be available after
                each executed DFS command from a macro:

                rc            The returncode from the DFS command

                dfs_disknr    Physical disk number currently open
                dfs_partid    Partition-id for selection with "part"
                dfs_drive     The opened drive letter, including a colon.
                dfs_afsys     The attached filesystem, like "HPFS" or "FAT"
                dfs_sect      The last retrieved sector(s), binary buffer
                dfs_type      Type of last retrieved sector, this is a string
                              starting with the type-character (see 'F' cmd)
                              followed by a textual description.

                dfs_this      SN of the last retrieved sector
                dfs_down      SN of most likely sector to retrieve now
                dfs_up        SN of sector up in hierarchy
                dfs_next      SN of next in sequence
                dfs_prev      SN of previous in sequence
                dfs_down      SN of up in hierarchy

                dfs_number    The number of disks or partitions resolved,
                              from the commands "disk" and "part 0" or
                              "part" respectively.

                dfs_sn.0      Number of sector-numbers in the SN stem variable
                dfs_sn.n      nth sector-number in the SN stem variable, coming
                              from DFS output for directories and allocation.
                              They correspond to the '.NNNNN' command

                              Note: SN's are in an 8-digit Hexadecimal format


                REXX is dynamically loaded, when the run-command is executed
                It requires REXX.DLL and REXXAPI.DLL in the libpath.



 COPYOUTPUT [stem-name]      Copy output from last-command to REXX stem-var

 Purpose:       Allow output to be captured and processed from REXX

 Parameters:    stem    optional   name of stem variable, ending in a '.'
                        default:   "dfs_output."

 Output:        none

 Remarks:       The <stem>.0 will hold the number of lines
                <stem>.1 through <stem>.n the actual cmd-output

                ==> This command is temporarily disabled to avoid a trap