      DFSee version 17.0 2022-10-22  (c) 1994-2022: Jan van Wijk
 =========================[ www.dfsee.com ]==========================

_______________________________________________________________________________

C O N T E N T S:
_______________________________________________________________________________

  Syntax rules            = General syntax rules for DFSee
  Option syntax           = syntax for individual options or switches
  Parameter syntax        = syntax for individual parameters or arguments
  DFSee command syntax    = Notes on DFSee command options and parameters
  General settings        = Notes on DFSee program switches and arguments
  Documentation           = Notes on how the command syntax is documented
_______________________________________________________________________________

S Y N T A X    R U L E S
_______________________________________________________________________________

The DFSee program uses the same 'parser' module to process the general
settings on the DFSee command line and to process each DFSee command
encountered in an interactive session or DFSee script.

Because of this, the syntax rules for both are very similar.
This chapter describes the rules and possibilities of the syntax.

In general, most programs require some information to specify what task
has to be done, and what data should be used for that task.
Programs that are command line based, like DFSee use command line items
to represent that information. GUI based programs would most likely use
dialog windows with entry-fields, buttons and selections lists for this.

The information for command line programs often comes in two forms:
_______________________________________________________________________________

1) OPTIONS:    Information that has a 'name' and an optional value.
               Because each option has a unique name, they can be
               identified easily and can appear in any order.

               Note:
               Options are sometimes called "switches", specifically when
               supplied to the DFSee program from the operating system.
_______________________________________________________________________________

2) PARAMETERS: Information that consists of the value itself without an
               explicit name. When more than one parameter is present,
               they need to be identified by the position they appear on
               the command line (1st parameter, 2nd parameter and so on)

               Note:
               Parameters are sometimes called "arguments", specifically when
               supplied to the DFSee program from the operating system
_______________________________________________________________________________


As a simple example, not related to DFSee at all, consider:


XCOPY  *.txt  d:\tmp  /s /r

In this command line we see five different parts:

'XCOPY'         the command
'*.txt'         the first parameter, here the source for the copy
'd:\tmp'        the second parameter, the destination
'/s'            an option for the command, here a 'subdirectory' indicator
'/r'            an option for the command, here a read-only indicator

Note that the order of the parameters IS significant (source and destination)
but the order of the options is not, '/r /s' would be fine too.

Also note that the options are preceded by a special character '/' that
makes them easy to recognize. This is often called the 'switch-character'.
On UNIX and Linux this is the '-' character and on DOS (and similar)
systems it is the '/' character and most DOS and OS/2 programs actually
accept both of them as valid.

Within DFSee, the ONLY valid option- or switch-character is the hyphen: '-'
_______________________________________________________________________________

O P T I O N   S Y N T A X
_______________________________________________________________________________

The syntax for every option (or 'switch') is:

   -name[:value[,unit]]

    -      = the mandatory switch or option character, a hyphen

    name   = name for the option, only the FIRST character is significant
             so the options '-volume:test' and '-v:test' are equivalent.

    :      = the optional separator between name and value of the option

    value  = the optional value for this option, it can take two forms:

             - a number, decimal (base Ten), hexadecimal or octal
               To force a decimal value, start it with '0n' or '0t'
               To force a hexadecimal value, start it with '0x'
               To force an octal numeric value, start it with '0o'
               The default, without any prefix, will be DECIMAL

             - a string, either a single word or multiple words
               enclosed in double-quotes

    ,      = the optional separator between value and unit

    unit   = A unit specifier like 'cylinder', 'mb' or 'sector'
             Only numeric options can take a unit specifier.
             (also see description of 'mcs-number' in DFSTERMS.TXT)

   Often options or switches are used to signal an ON/OFF or SET/UNSET
   condition (boolean value). In that case the presence of the option is
   interpreted as 'option ON' and the absence of the option as 'option OFF'
   This is equivalent to numeric value '0' meaning 'OFF' and any other
   numeric value or a string meaning 'ON'.

   There is one special form to explicitly set an option to 'OFF' that is
   useful for switches and options that have a default value of 'ON':

   -o-

   This is interpreted as 'option 'o' is explicitly set to 'OFF'

   No spaces can occur within an option, except when inside a
   double-quoted string value.

   Some examples of valid options with a short description:


   -a                             ;option 'a' is set (ON)
   -a-                            ;option 'a' is not set (OFF)
   -absolute:0                    ;option 'a' is not set (OFF)
   -abs:50                        ;option 'a' has numeric value 50
   -abs:50,c                      ;option 'a' has numeric value 50 cylinders
   -abs:0x20                      ;option 'a' has hexadecimal value 20
   -name:test                     ;option 'n' has string value "test"
   -n:"another one"               ;option 'n' has string value "another one"

_______________________________________________________________________________

P A R A M E T E R   S Y N T A X
_______________________________________________________________________________

The syntax for parameters is quite simple, a parameter is a single word,
or multiple words enclosed in double quotes.
_______________________________________________________________________________

D F S E E   C O M M A N D   S Y N T A X
_______________________________________________________________________________

DFSee commands consist of the command word followed by any number
of options and parameters. As said before the parameters need to be
in the right order (for this command) but the options may appear at
any position after the command word, which is always the FIRST word.

Options can even appear between parameters, this is called a FREE-FORM
syntax. However the place an option is seen has NO influence on the
meaning or the scope of that option.

Some examples of valid commands with options and parameters are:

PART -q  3                        ;select partition 3 quietly
PART 3  -q                        ;select partition 3 quietly

CR  log hpfs  -size:100 -e        ;create logical 100Mb HPFS at end
CR  log -e -size:100  hpfs        ;create logical 100Mb HPFS at end

Note on the 'CR' example that the order of the options changed, but
the parameters 'log' and 'hpfs' are in the same order.


When using options in DFSee, you don't always NEED parameters, they serve
the same purpose. It is often for convenience and backward compatibility
that positional parameters are supported on some commands.

As an example, see the description of the "CR" command (or CREATE) in
DFSFDISK.TXT. There you will see a full list of parameters (old style)
and options (new style) for the same information to be used.

Options are more readable and flexible than positional parameters
so I try to use them for as many commands as possible.


_______________________________________________________________________________

Multi-commands
_______________________________________________________________________________

DFSee allows multiple commands to be combined onto a single command line.
This can be very useful in scripts (see DFSDISK.CMD or DFSDISK.BAT).

The syntax for such multi-commands is:

        command-1#command-2#command-3 ...#command-n

Each command must contain a command word, and can contain options and
parameters as described above.

_______________________________________________________________________________

G E N E R A L   S E T T I N G S
_______________________________________________________________________________

The executable 'DFSee' program itself can receive information from
the operating system command line too. DFSee uses this to allow some
general settings to be made, and to pass commands to be executed.

Because the 'parameters' passed to the DFSee EXE are 'DFSee commands'
there might be confusion about some options, are they 'general' ones
for the executable, or 'specific' to the command specified ?

To solve this potential dilemma, all options that appear before the
first parameter (a DFSee command) are considered as general settings
or 'switches'. All options AFTER it are options for the command.

An example to illustrate this is:

        DFSOS2.EXE  -w- -Q  part -t- -m

Here the first parameter is the command 'part' and the options
that appear before it: '-w- -Q' are switches for the executable
while 't' -m' are two options for the 'part' command.


Available switches are listed with: "DFSOS2.EXE  -?"


Note: Substitute DFSDOS.EXE or DFSWIN.EXE for DOS or Windows-NT respectively.

_______________________________________________________________________________

D O C U M E N T A T I O N
_______________________________________________________________________________

About the sections you see in the documentation files (like DFSCMDS.TXT),
they usually start with a single line as a summary for the command, and then

Purpose:        Short description about the 'why' ...
Parameters:     Description of the parameter(s)
Options:        Description of the options
Output:         Description of what kind of output goes to the screen
Examples:       Example command lines with this command
Remarks:        Any additional remarks on the command or its usage


Not all commands have (or need) all these sections and since documenation is
written over time, it is not 100% consistent either, but I try to clean it up
whenever I make changes to it.

_______________________________________________________________________________


 ----------------------------[ www.dfsee.com ]-------------------------------

