    ===========================================================================
    ===========================================================================
    ============================                  =============================
    ============================                  =============================
    ============================      DOSVAR      =============================
    ============================                  =============================
    ============================                  =============================
    ===========================================================================
    ===========================================================================





         ---------------------------------------------------------------
         DOSVAR -- A Utility to Manipulate Strings in Batch (.BAT) Files
         ---------------------------------------------------------------
         DOSVAR is a program that will modify variables in a batch file.
         It supports substrings, justification, zero-stripping and other
         useful functions.
         ---------------------------------------------------------------



                       DOSVAR is Copyright (C) 1994, 1998


                                       by


          Pinnacle Software, CP 386 Mount Royal, Quebec, Canada H3P 3C6

                                                                      



    ===========================================================================
                               Installing DOSVAR
    ===========================================================================


    If you are simply experimenting with DOSVAR, you can do so in the current
    directory, using the START.BAT program to demonstrate the techniques.  For
    daily use, the DOSVAR.EXE program and the associated files (such as
    START.BAT) should be placed in a directory in your system's PATH.  For an
    explanation of the system PATH, see your operating system manual.


    ===========================================================================
                                How DOSVAR Works
    ===========================================================================


    DOSVAR creates a batch file named SETVAR.BAT, which does the actual setting
    of the variable.  To use DOSVAR, include it in a batch file, with the
    appropriate parameters, followed by a CALL to the batch file SETVAR.BAT.
    For example:

    @ECHO OFF
    DOSVAR /vABCDEFG /nMYVAR /jR /o10 /c$
    CALL SETVAR.BAT
    ECHO Expected result: $$$ABCDEFG
    ECHO Actual result:   %MYVAR%
    SET MYVAR=

    The last line of the batch file sets the variable MYVAR to a null value,
    which removes it from your system's "environment space".  Since the
    environment space is quite limited, you should take care to eliminate
    variables when you are finished when them.

    In most cases you will not be manipulating a literal string (as in the
    previous example).  Rather, you will be manipulating a system environment
    variable or a batch parameter variable, as in these examples:

    @ECHO OFF
    REM Demonstration using a system environment variable
    DOSVAR /v%COMSPEC% /sL /i2 /nCSD
    CALL SETVAR.BAT
    ECHO The COMSPEC drive is %CSD%
    SET CSD=

    @ECHO OFF
    REM Demonstration using a batch parameter variable
    IF NOT (%1) == () GOTO OKAY
    ECHO Please specify a parameter when running this batch file
    GOTO QUIT
    :OKAY
    DOSVAR /v%1 /nXX /jR /o10 /c$
    CALL SETVAR.BAT
    ECHO The right-justified version of %1 is %XX%
    SET XX=
    :QUIT

    For further details about batch and environment variables, refer to a
    DOS manual's batch programming section.  As regards environment variables,
    refer also to your DOS manual's explanation of the SET command.


    ===========================================================================
                                     Syntax
    ===========================================================================

    
    NOTE:  For a convenient summary of DOSVAR's syntax, type the following
           command at the DOS prompt:  DOSVAR /?
                       

    The format of DOSVAR is:

    DOSVAR /v<data> [settings]

    The /v parameter specifies the data to be manipulated.  This can be a
    literal string (example: /vABCDE), a batch file variable (example: /v%1)
    or a system environment variable (example: /V%PATH%).

    The optional settings are as follows:

    SETTING     DESCRIPTION                       DEFAULT VALUE
    ----------  --------------------------------  ---------------------------
    /n<var>     Name of variable to be SET        X
    /z<Y or N>  Pre-strip leading 0's from input  No, don't pre-strip 0's
    /s<action>  Substring [N]one/[L]eft/[R]ight   None (use entire string)
    /i<length>  Substring length (/sL or /sR)     8
    /j<action>  Justify [N]one/[L]eft/[R]ight     None (do not justify)
    /o<length>  Justify length (/jL or /jR)       8
    /c<char>    Character with which to justify   Space
    /b<path>    Path for SETVAR.BAT               Same as DOSVAR.EXE

    The SETVAR.BAT file is usually placed in the same directory as the DOSVAR
    program (DOSVAR.EXE), but you can change its location with the /b para-
    meter.  Here is an example:

    DOSVAR /v%COMSPEC% /sL /i2 /bC:\MYPATH

    This would place SETVAR.BAT in the C:\MYPATH directory.

    You can also specify \b@ to indicate "current directory", as in this
    example:

    DOSVAR /v%COMSPEC% /sL /i2 /b@

    This would place SETVAR.BAT in the current logged directory.

    You can check on the success or failure of DOSVAR with the IF ERRORLEVEL
    facility of batch files.  DOSVAR returns 0 if it worked, or 255 if it
    failed (or if the help screen was called up).  Because of the way that
    the IF ERRORLEVEL statement works, you should check for a 255 rather than
    a zero, since IF ERRORLEVEL 0 is ALWAYS true.

    In day-to-day usage, DOSVAR should never return an errorlevel of 255.

