      DFSee version 9.09 24-05-2008  (c) 1994-2008: 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 from version 4.16 onwards: 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 command line using
   the RUN command with the script filename as a parameter. DFSee will select
   the NATIVE engine automatically based on the contents of the script.

   Native scripting can be very useful for recovery scenarios where
   multiple partitions need to be recreated and for other repetitive 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 commands like "if errorlevel ..." can be used to
   control the flow in the script.

   One disadvantage to this method is that there is just the return code 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) command line.

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

   An example of such a script is the DFSDISK.BAT and DFSDISK.CMD which
   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 command line using
   the RUN command with the script filename 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 extension is
                            given a '.DFS' extension will be appended.

                args        Arguments to be passed as parameters to the macro.
                            Up to 9 arguments can be specified and can be used
                            anywhere in the script as '$1' to '$9' while $0
                            is the script filename (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 or 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 return code 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.

                To pass arguments to a script that has embedded spaces, it is
                required to use the ESCAPE character '\' and quotes together:
                (using quotes only will NOT work on most operating systems)

                   dfsos2 run testarg a b c d e "\'f g h i j\'" k l
                   dfsos2 run testarg a b c d e \"'f g h i j'\" k l
                   dfsos2 run testarg a b c d e \'f g h i j\' k l

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

                The initial prompt for a logfile at startup (dfswork) can be
                surpressed by using the '-l-' or '-l:filename' startup switch
_______________________________________________________________________________

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.



;;setparam  p  value
;;setparam  p  ? prompt-text

This will give a new 'value' to the parameter 'p' where p is 0..9
It will replace the value currently assigned, either as an argument
to the macro, through a 'defaultparam' pragma, or a previous setparam.

When the 'value' starts with a question-mark and a space, the following
text will be considered to be a prompt-text and the real value will be
retrieved from the user, using a prompting mechanism, usually a popup.

The setparam is a means to use the arguments as simple variables,
quite useful in scripts where some values/parameters are to be
determined on run-time (by the user, reading from the screen :-)


The following pragmas alter the behaviour of the script interpreter
from within the script as initially set by the corresponding options
on the RUN statement or from the built-in 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 command line.
_______________________________________________________________________________

 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 an 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


Another example, using the SETPARAM pragma to query some info.
It also shows how to get automatic prompting for arguments
when running the script from a menu (first two lines)
(script is included in the distribution as 'ntfsshow.dfs')

;------------------ start script
; Display NTFS information related to RESIZING the filesystem, for testing
; ~ param1 = [partition nr]~ param2 = [bitmap-sectors]~
;
;;error ignore
;;defaultparam 1 1
;;defaultparam 2 8
part $1
0
d
d
alloc
check
slt * 0 *
mft 0
mft 2
d
mft 3
mft 8
t H
mft 6
;;setparam 2 ? Specify $Bitmap sectors to display (listed in ALLOC, 2 * #KiB)
t H
d
H . $2 S
;----------------- 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 range 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 command line is limited to just
over 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 content. 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 return code 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 sector down in hierarchy

                dfs_number    This is set by several commands to return
                              one value that might be of interest:

                              disk / walk    : The number of disks
                              part (display) : The number of partitions
                              slt / check    : The number of errors
                              find  (single) : Position within sector

                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: SNs 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 command output

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

