      DFSee version 17.0 2022-10-22  (c) 1994-2022: 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, including variable and function descriptions
  Batch scripts
  REXX scripts (OS/2 only), including variable descriptions

_______________________________________________________________________________

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:
_______________________________________________________________________________
#010 Native 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.

   Note:
   Native scripting was enhanced greatly in version 9.xx with the
   introduction of TXSCRIPT control-structures and expressions
   including user and system variables.

   Another minor update was made with 11.3, adding LOOP, ENDLOOP and EXIT WHEN
_______________________________________________________________________________
#020 Batch files

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.
_______________________________________________________________________________
#030 Rexx scripts

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:
_______________________________________________________________________________
#100 Native RUN

 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
                suppressed by using the '-l-' or '-l:filename' startup switch
_______________________________________________________________________________
#110 Native script layout

Layout and control:
-------------------

A native script consists of a series of 'statements' in a
statement-list (STL), where each statement is either a single
line with comment, an assignment, a pragma, a host-command or
a control-structure like IF, WHILE and FOR ...

Code-blocks within control-structures are statement-lists too.


  ;script LAYOUT example         ;A comment line

  ;;defaultparam 1 5             ;A pragma

  IF  $1 < $_parts               ;Control statement
                                 ;with an expression
    Say $1 is OK!                ;A command to be
                                 ;executed by DFSee
  ENDIF                          ;End of the Control statement



The following control-structures and keywords are supported:

  IF  (condition)                ;Like the Perl IF, not using a
    statement-list               ;{} block  but an ENDIF keyword
  ELSEIF (condition)             ;() on conditions are optional
    statement-list               ;Any number of the ELSEIF clauses
  ELSE                           ;ELIF, ELSIF and ELSEIF accepted
    statement-list
  ENDIF


  WHILE  (condition)             ;Like Perl or 'C' but not using a
    statement-list               ;{} block  but an explicit end
  ENDWHILE                       ;() parenthesis on conditions optional


  FOR init;condition;iterator    ;often used as a 'counting' loop
    statement-list
  ENDFOR


  DO                             ;condition evaluated at the END
    statement-list
  UNTIL (condition)


  LOOP                           ;no condition at all
    statement-list",
  ENDLOOP",


  LOOP                           ;condition at arbitrary location
    statement-list               ;can be empty
    EXIT WHEN (some condition)   ;EXIT WHEN will exit the loop, when
    statement-list               ;the condition is TRUE, and commence
  ENDLOOP                        ;at the 'next statement'
  next-statement",


  WHILE  (condition)
    statements ...
    IF (some condition)
      BREAK                      ;BREAK will exit the loop, and
    ENDIF                        ;commence at 'next-statement
    statements ...
  ENDWHILE
  next-statement


  WHILE  (condition)
    statements ...
    IF (some condition)
      CONTINUE                   ;CONTINUE will 'jump' directly to
    ENDIF                        ;the loop iterator (condition)
    statements ...               ;bypassing the remainder of the
  ENDWHILE                       ;loop statement-list


  PRINT  expression              : Send the resulting string or numeric value",
                                   of the expression to the display (and log)",
                                   This will NOT modify the value of $_rc!",

  RETURN                         : Terminate the script, returncode is $_rc",
  RETURN expression              : Terminate the script, returncode is the",
                                   resulting numeric value of the expression",


_______________________________________________________________________________
#120 Native variables

Native variables
-----------------
The native scripting engine has access to many DFSee internal values so
these can be used in expressions in a script, or even from the DFSee
commandline when using the {some-native-script-expression} syntax.

Naming of user variables is free, except for names with the '$_' prefix
which are reserved for system variables (like DFSee host variables) and
  $0 .. $9 which are reserved for argument passing into scripts.

  $_rc     special host-variable, set automatically after every command
           when executed from a script (only), unlike the DFSee special
  $_retc   that is always set by DFSee after executing a command,
           so it can be used from the commandline too.

           For rc values (constant definitions), see further below.

The variables available are either scalar, meaning a single value known
within DFSee, or they are related to a Disk, Partition, Freespace area
the Sectorlist, or to all sectors on the current opened object.

In this case they are indexed arrays of values and you specify the disk,
partition, freespace, list or sector number to get the desired value.

DFSee variable names always start with "$_"

Available variables (as of version 15.0) are:

 SCALAR

    $_base                PSN for first sector of opened object
    $_batch               Boolean: script is running in batch mode
    $_cmdsep              Command separator character, default is '#'
    $_columns             Number of display columns on the screen window
    $_disk                Current disk number if one is opened, or 0
    $_disks               Number of disks attached in DFSee
    $_down                Sector number selected on <Enter> or 'd' command
    $_drive               Driveletter string for current object, like 'D:'
    $_drive               Driveletter string for current object, like 'D:'
    $_dirsep              String with directory/path separator, one character
    $_exedir              String with executable-directory (path), no separator
    $_exename             String with executable-name only
    $_fsdirty             Current opened filesystem is marked as 'dirty'
    $_fsfree              Nr of 'free sectors' in filesystem   (when known)
    $_fsmaxsize           Max size of FS in sectors for resize (when known)
    $_fsminsize           Min size of FS in sectors for resize (when known)
    $_fsys                Current filesystem name, like 'NTFS'  (mode=...)
    $_geobps              Logical geometry, bytes per sector
    $_geocyls             Logical geometry, number of cylinders
    $_geohead             Logical geometry, number of heads
    $_geosect             Logical geometry, sectors per track
    $_lines               Number of display lines on the screen window
    $_listed              Number of sectors listed in the Sectorlist
    $_lvm                 LVM information is present on at least one disk
    $_magic               DFSee version eyecatcher, use 'say {i2hex($_magic)}'
    $_object              type of the current opened DFSee object (see below)
    $_parts               Total number of partitions (on all disks)
    $_pid                 PID for current opened object, or 0
    $_platform            Operating system now running DFSee, like 'OS/2'
    $_program             Program name running the script, like 'DFSee'
    $_readonly            Boolean: Object is opened in read-only mode
    $_retc                Return-code for last executed command, 0 is OK
    $_secdesc             Current sector description like 'Master Boot Rec'
    $_sectype             Single character sector-type, like 'r' for MBR
    $_size                Size of the current object in sectors
    $_store               Store number currently active, 0..2
    $_this                Sector number for the CURRENT sector
    $_up                  Sector number for 'parent' sector; 'u' command
    $_version             DFSee version number * 100  ('1460' for 14.6)
    $_xtra                Sector number for 'related' sector; 'x' command


                          DFSee object type values:

                             0 = no object or unknown
                             1 = partitioned medium, disk
                             2 = partition on a disk
                             3 = Volume or Device
                             4 = Image File
                             5 = Freespace area
                             6 = Any object,  base != 0


 DISK-LEVEL, where 'DSK' is the DFSee disk number 1..n

    $_d_access[DSK]     Boolean: disk accessible (1) or not-accessible (0)
    $_d_cylsize[DSK]    Cylindersize of the disk in sectors
    $_d_disknr[DSK]     DFSee disk-id for this disk (same as 'DSK' :-)
    $_d_firstpart[DSK]  DFSee PID for the first partition on this disk
    $_d_flags[DSK]      Error/warning flags for the disk
    $_d_frareas[DSK]    Number of freespace areas on the disk
    $_d_frsects[DSK]    Nr of sectors in freespace areas on the disk
    $_d_geobps[DSK]     Logical geometry, bytes per sector
    $_d_geocyls[DSK]    Logical geometry, number of cylinders
    $_d_geohead[DSK]    Logical geometry, number of heads
    $_d_geosect[DSK]    Logical geometry, sectors per track
    $_d_largeflop[DSK]  Boolean: disk is a large-floppy    (no partitions)
    $_d_cryptdisk[DSK]  Boolean: disk is an encrypted disk (no partitions)
    $_d_lastpart[DSK]   DFSee PID for the last partition on this disk
    $_d_creatr[DSK]     Creator identification string, FSO or CRP pStyle
    $_d_drive[DSK]      Driveletter for the disk, when FSO or CRP pStyle
    $_d_fsform[DSK]     Filesystem format string, when FSO or CRP pStyle
    $_d_label[DSK]      Filesystem label, string, when FSO or CRP pStyle
    $_d_lvmname[DSK]    LVM identification string for this whole disk
    $_d_lvmparts[DSK]   Number of partitions that have valid LVM information
    $_d_ntsig[DSK]      Value of the (32-bit) NT/Windows disk signature
    $_d_parts[DSK]      Number of partitions on the disk
    $_d_primaries[DSK]  Number of primary partitions on the disk
    $_d_pstyle[DSK]     Partition style string for disk (MBR, GPT, CRP, FSO)
    $_d_removable[DSK]  Boolean: Disk appears to be a removable device
    $_d_size[DSK]       Disk-size for the disk logical geometry, in sectors
    $_p_unixdev[PID]    Unix devicename for the whole disk, like /dev/hda


 PARTITION-LEVEL, where 'PID' is the DFSee partition-id 1..n

    $_p_active[PID]       Boolean: Partition 'Active flag' is set (startable)
    $_p_basepsn[PID]      Sector-number for the first sector (bootsector)
    $_p_bmname[PID]       IBM bootmanager name, when using a non-LVM OS/2
    $_p_checksum[PID]     DFSee checksum for the partition bootsector
    $_p_cluster[PID]      Nr of sectors per cluster (or block) for filesystem
    $_p_creatr[PID]       Creator identification string for the filesystem
    $_p_cylsize[PID]      Cylindersize of the partition in sectors
    $_p_descr[PID]        Partition type description, like 'Inst-Fsys'
    $_p_disknr[PID]       Disk number for this partition
    $_p_diskpart[PID]     Relative partition-number on this disk
    $_p_drive[PID]        Driveletter for the partition, as known in DFSee
    $_p_flags[PID]        Error/warning flags for the partition
    $_p_fsform[PID]       Filesystem format for the partition (HPFS, FAT etc)
    $_p_geobps[PID]       Logical geometry, bytes per sector
    $_p_geocyls[PID]      Logical geometry, number of cylinders
    $_p_geohead[PID]      Logical geometry, number of heads
    $_p_geosect[PID]      Logical geometry, sectors per track
    $_p_label[PID]        Filesystem label for the partition
    $_p_lastpsn[PID]      Sector-number for the last sector in the partition
    $_p_linuxdev[PID]     Linux devicename for the partition, like /dev/hda8
    $_p_linuxnr[PID]      Linux device number for this partition
    $_p_lvminfo[PID]      Boolean: Partition has LVM information defined
    $_p_lvminstal[PID]    Boolean: Partition marked as 'installable' in LVM
    $_p_lvmletter[PID]    LVM driveletter assigned to this partition
    $_p_lvmonmenu[PID]    Boolean: Partition is on the IBM BootManager-menu
    $_p_lvmpart[PID]      LVM partition name assigned to the partition
    $_p_lvmvolume[PID]    LVM volume name assigned to the partition
    $_p_partpsn[PID]      Sector-number where the partition-table is located
    $_p_primary[PID]      Boolean: Partition is a primary
    $_p_size[PID]         Partition-size, in sectors
    $_p_tableslot[PID]    Slot-number used in the partition-table (0..3)
    $_p_type[PID]         Partition-type value, 1..255


 FREESPACE-LEVEL, where 'FID' is the DFSee freespace-id 1..n

    $_f_basepsn[FID]      Sector-number for the first sector
    $_f_cylsize[FID]      Cylindersize of the freespace area in sectors
    $_f_descr[FID]        Freespace type description, like 'FreeSpace Pri/Log'
    $_f_disknr[FID]       Disk number for this freespace area
    $_f_geobps[FID]       Logical geometry, bytes per sector
    $_f_geocyls[FID]      Logical geometry, number of cylinders
    $_f_geohead[FID]      Logical geometry, number of heads
    $_f_geosect[FID]      Logical geometry, sectors per track
    $_f_lastpsn[FID]      Sector-number for the last sector in the area
    $_f_size[FID]         Freespace area size, in sectors
    $_f_type[FID]         Freespace type value, 1..255


 SECTOR-LIST

    $_s_list[#]           Sector number at specified index in the list


 SECTOR-CONTENTS

    $_b_sector[#]         Sector contents as 512 (binary) bytes
    $_h_sector[#]         Sector contents as 512 * 2 hex digits


 Constant values defined with TxLib and DFSee:

 true                    1          Logical values
 false                   0

 rc_ok                   0          $_rc and $_retc 'OK'

 rc_file_not_found       2          Generic OS RC values
 rc_path_not_found       3
 rc_too_many_files       4
 rc_access_denied        5
 rc_invalid_handle       6
 rc_no_more_files       18
 rc_write_protect       19
 rc_not_ready           21
 rc_crc                 23
 rc_seek                25
 rc_sector_not_found    27
 rc_write_fault         29
 rc_read_fault          30
 rc_gen_failure         31
 rc_file_sharing        32
 rc_lock_violation      33
 rc_wrong_disk          34

 rc_error              200          TxLib specific RC values
 rc_invalid_file       202
 rc_invalid_path       203
 rc_access_denied      205
 rc_invalid_handle     206
 rc_invalid_data       207
 rc_alloc_error        208
 rc_syntax_error       210
 rc_invalid_drive      215
 rc_pending            217
 rc_failed             218
 rc_write_protect      219
 rc_cmd_unknown        222
 rc_no_compress        223
 rc_no_initialize      224
 rc_aborted            225
 rc_bad_option_char    226
 rc_too_many_args      227
 rc_display_change     228
 rc_app_quit           229

 rc_value_error        231          DFSee specific RC values
 rc_not_found          232
 rc_list_empty         233
 rc_no_script          234
 rc_no_device          244
 rc_psn_limit          245
 rc_st_mismatch        246
 rc_reboot_req         248
 rc_user_abort         249
 rc_no_change          250
 rc_cmd_failed         252
 rc_cmd_warning        254

_______________________________________________________________________________
#130 Native functions

Native Functions:
-----------------

 abs(num)                       : Absolute value, numeric
 b32(num)                       : Clip to 32-bit unsigned
 b2asc(str)                     : Binary string to ASCII
 b2int(str[,len])               : Binary string to reversed int
 chr(num)                       : ASCII value for number
 canceled()                     : Test for canceled last operation
 confirmed(str[,helpid])        : Confirmation Yes/No/Cancel, help
 defined(var)                   : Is variable defined
 dirselect(prompt[,path])       : Select a directory, start in path
 drivefs(drv)                   : FS-name for drive letter
 drivelabel(drv)                : Label string for drive letter
 drives([num])                  : Drive letters in string, 7=all
 drivespace(drv)                : Freespace in KiB for drive
 dump()                         : Dump variable pool contents
 exists(path)                   : File exists
 filext(path,ext)               : Set default file extension
 fileselect(prompt,[wc[,path]]) : Select existing file, wildcard/path
 filesaveas(prompt,[wc[,path]]) : Specify new or existing file
 fnbase(path)                   : Extract filename without ext
 fnfile(path)                   : Extract filename without path
 fnpath(path)                   : Extract path only, no filename
 getcwd()                       : Get current working directory
 getenv(variable)               : Get string for environment variable
 h2asc(str)                     : Get string from hex-ascii str
 h2int(str)                     : Get integer from hex-ascii str
 i2dec(num[,len])               : Convert int to decimal str
 i2hex(num[,len])               : Convert int to hexadecimal str
 index(str,sub[,pos])           : Find substring in string
 lc(str)                        : Return lowercased string
 left(str,pos[,len])            : Left adjust string, pad/clip
 length(str)                    : Get length of string
 makedir(path)                  : Create full directory path
 max(a,b,...)                   : Ret maximum of values
 min(a,b,...)                   : Ret minimum of values
 message(str[,helpid])          : Message popup, until [OK], help
 ord(str)                       : Numeric value 1st char in str
 print([str][,str]...)          : Print zero or more strings
 prompt(str)                    : Popup question, return string
 replace(str[,old[,new]])       : Replace characters in string
 sec2gib(num[,bps])             : Get GiB value for #sectors
 sec2kib(num[,bps])             : Get KiB value for #sectors
 sec2mib(num[,bps])             : Get MiB value for #sectors
 reverse(str)                   : Reverse characters in string
 right(str,num[,str])           : Right adjust string pad/clip
 rindex(str,sub[,pos])          : Reverse find substring in str
 sleep(milliseconds)            : Sleep specified nr of mulliseconds
 strip(str[,lead[,trail]])      : Strip leading/trailing string chars
 substr(str,pos[,len])          : Extract substring from string
 uc(str)                        : Return uppercased string
 undef(var)                     : Undefine (free) a variable

_______________________________________________________________________________
#140 Native operators

Native Operators
----------------

 $name[]++                  Variable, indexed and auto increment
 $other--                   Scalar variable, auto decrement

 Atom, Term                 String, number, function
                            nested-expression or ternary

 - + ! ~                    Unary operators plus/minus/not
 * / %                      Binary multiply/division/modulo
 + -                        Binary plus/minus
 x                          String replication
 .                          String concatenation

 <<  >>                     Numeric bit-shift

 == != < > <= >=            Numeric compare
 === !==                    Same value AND type
 EQ NE LT GT LE GE          String compare

 &                          Bitwise AND
 ^                          Bitwise XOR
 |                          Bitwise OR

 &&                         Logical AND        (C-style)
 ||                         Logical OR         (C-style)

 =                          Assignment
 ,                          Comma, multi-expression

 NOT                        Logical NOT        (Perl style)
 AND                        Logical AND        (Perl style)
 OR                         Logical OR         (Perl style)

_______________________________________________________________________________
#150 Native pragmas

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.
_______________________________________________________________________________
#200 REM command

 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.
_______________________________________________________________________________
#210 SAY command

 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:
_______________________________________________________________________________
#220 SLEEP command

 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.
_______________________________________________________________________________
#250 Native script example


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


;----------------- example script using control some structures and variables
;Check DFSee version and number of disks
if $_version >= 1000
  if ($_disks >= $dmin) && ($_disks <= $dmax)
    ; ... do the real work ...
  else
    confirm Need $dmin to $dmax disks, got: $_disks
  endif
else
  confirm Script needs DFSee 10.x (this is $_version)
endif
;----------------- 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:
_______________________________________________________________________________
#300 Rexx RUN

 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.
_______________________________________________________________________________
#310 COPYOUTPUT command

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

