home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / varset11.zip / VARSET.TXT < prev   
Text File  |  2002-06-04  |  14KB  |  448 lines
  1.     --------------------------------------------------------------------
  2.     VARSET                             Ver 1.1 (c) 2002, Horst Schaeffer
  3.     --------------------------------------------------------------------
  4.  
  5.     VARSET sets a variable to file related information. In addition some
  6.     arithmetic and string functions are offered.
  7.     Long file names are supported under Windows 9x and 2000 (NOT Win NT).
  8.  
  9.     The syntax is easy to remember.
  10.  
  11.     Example:    call var set FD=date of filename.ext
  12.  
  13.     Contents: ----------------------------------------------------------
  14.  
  15.     1.    VARSET information keywords (overview)
  16.     2.    Command modes
  17.     2.1   Automatic generation of the variable (through VAR.BAT)
  18.     2.2   Conventional handling (through temporary batch file)
  19.     2.3   Test mode
  20.     3.    Commands
  21.     3.1   Quote handling
  22.     3.2   Output options
  23.     3.3   Command keywords and details
  24.     4.1   History
  25.     4.2   Disclaimer, Copyright
  26.  
  27.     --------------------------------------------------------------------
  28.  
  29. 1.  VARSET information keywords
  30.     ---------------------------
  31.     File related:
  32.  
  33.     DATE        date stamp of given file, current date
  34.     TIME        time stamp of given file, current time
  35.     FILES       number of files (filespec with wildcards)
  36.     DIRS        number of directories (wildcards)
  37.     SIZE        size of file(s), bytes, KB or MB
  38.     LINES       number of lines (ASCII text file assumed)
  39.     VOL         volume label of drive
  40.     DRIVE       drive of filespec
  41.     -DRIVE      drive removed
  42.     NAME        name of filespec: without path, extension
  43.     EXT         extension of filespec
  44.     -EXT        extension removed
  45.     LFN         long file name with full path
  46.     SFN         short file name with full path
  47.     FULL        full file name (with path), see details
  48.  
  49.     Other functions:
  50.  
  51.     STRING(p,l)    substring (position, length)
  52.     (arithmetic)   evaluation of expression, integer only
  53.  
  54.  
  55. 2.  Command modes
  56.     -------------
  57.     Note: The environmental variable is not stored directly in the
  58.     COMMAND.COM environment, because this does not work under Windows
  59.     NT/2000. Instead, a SET instruction is generated, that is executed
  60.     by the command processor. This method should also work in future DOS
  61.     environments.
  62.  
  63.     There are three different ways to use VARSET.
  64.  
  65.  
  66. 2.1 Automatic generation of the variable (through VAR.BAT)
  67.     ------------------------------------------------------
  68.     VARSET is preferably invoked thru the batch file VAR.BAT,
  69.  
  70.     using the command:           CALL VAR SET ..
  71.     instead of the program name  VARSET ..
  72.  
  73.     Syntax:     call var set VARNAME=information OF filespec
  74.                 ------------ -------------------------------
  75.     Examples:   call var set FD=DATE of c:\util\some.txt
  76.                 call var set Q=FILES c:\folder\*.txt
  77.                 call var set LONG=LFN of filena~1
  78.                 call var set FN = -DRIVE of "%1"
  79.  
  80.     The word "of" is optional.
  81.  
  82.     If you are interested, this is how it works:
  83.  
  84.         The batch file VAR.BAT starts VARSET.COM, passing the complete
  85.         command tail.
  86.  
  87.         The program evaluates the command, and writes a SET statement
  88.         into the second line of VAR.BAT, so this instruction will be
  89.         executed automatically when VAR.BAT continues.
  90.  
  91.         VARSET detects this construct through a special code in VAR.BAT.
  92.  
  93.     Important:
  94.  
  95.     * Make sure that VAR.BAT is in the same directory with VARSET.COM.
  96.       Both should be in a directory accessed thru the PATH assignment.
  97.  
  98.     * VAR must not be used with the extension .BAT,
  99.       i.e.: CALL VAR.BAT SET ... will not work!
  100.       However, a path may be specified e.g.: CALL ..\VAR SET
  101.  
  102.     * Do not change the first line in VAR.BAT (unless you know exactly
  103.       what you are doing). The second line will always be overwritten.
  104.  
  105.     * The number of parameters that can be passed through VAR.BAT is
  106.       limited to 9. This will be no problem when you enclose long file
  107.       names in quote marks (recommended, though not mandatory).
  108.  
  109.  
  110. 2.2 Conventional handling (through temporary batch file)
  111.     ----------------------------------------------------
  112.     VARSET also supports output of the generated SET statement to STDOUT
  113.     for redirection to a temporary batch file.
  114.  
  115.     Example:    VARSET n=vol of %1 > temp.bat
  116.                 call temp.bat
  117.                 del  temp.bat
  118.  
  119.     This method is useful in case VARSET is on a read-only medium. The
  120.     "real" program name VARSET must be used. VAR.BAT is not involved.
  121.  
  122.  
  123. 2.3 Test mode
  124.     ---------
  125.     Without the VAR.BAT construct and without redirection to a file the
  126.     SET statement will be displayed on the screen (and not executed).
  127.  
  128.     Example:    VARSET N=lines of some.txt
  129.                 VARSET x=1234+33*125
  130.  
  131.  
  132. 3.  Commands
  133.     --------
  134. 3.1 Quote handling
  135.     --------------
  136.     Double quote marks (") are removed, so it makes no difference
  137.     whether you write:
  138.  
  139.                 "C:\my files\long filename.txt"
  140.     or:          C:\my files\long filename.txt
  141.  
  142.     The result is always returned without quote marks.
  143.  
  144.     Note:
  145.  
  146.     If you use quote marks, they must be balanced. Only outside strings
  147.     enclosed in quote marks options are recognized, and trailing spaces
  148.     removed.
  149.  
  150.     Valid:      C:\files\"long filename.txt" /U
  151.     Invalid:    C:\files\long filename.txt" /U
  152.  
  153.     If spaces may be included in LFN's (or arithmetic expressions),
  154.     quote marks are recommended, since the number of parameters that
  155.     can be passed through VAR.BAT is limited. A quoted string is only
  156.     a single parameter under DOS 7.+.
  157.  
  158.  
  159. 3.2 Output options
  160.     --------------
  161.     /U  /L  upper or lower case output
  162.  
  163.             Extended ASCII characters are supported for code page 437
  164.             by default. For further adaptions see supplied debug script
  165.             CASE103.PAT.
  166.  
  167.     /Rn     right align, with total length n (blank space inserted)
  168.  
  169.     /Zn     numeric output with fixed length
  170.             (same as /R, with leading zeros inserted)
  171.  
  172.     /T      numeric output with thousands separator (acc.to Country)
  173.  
  174.  
  175. 3.3 Command keywords and details
  176.     ----------------------------
  177.     Note: A syntax error will produce a message (to STDERR), and return
  178.           errorlevel 255.
  179.  
  180.     For some commands errorlevel 1 is returned as additional information,
  181.     which does not indicate an error.
  182.  
  183.     On errors (e.g. file not found) errorlevel 2 (or above) will result,
  184.     and the returned variable will be empty (except for FULL command).
  185.     See details.
  186.  
  187.     Note: the STRING command always returns the length by errorlevel.
  188.  
  189.  
  190. DATE of <filename>
  191.  
  192.     No wildcards allowed.
  193.     If no filename is specified, today's date is returned.
  194.     Date format according to country settings and with 4-digit year.
  195.  
  196.     Errorlevel 0: date returned, 2: file not found
  197.  
  198.     Examples:   call var set D=date of data\file.ext
  199.                 call var set today=date
  200.  
  201.  
  202. TIME of <filename>
  203.  
  204.     No wildcards allowed.
  205.     If no filename is specified, the current time is returned.
  206.     Time returned in 24h format, hh:mm (no seconds).
  207.  
  208.     Errorlevel 0: time returned, 2: file not found
  209.  
  210.  
  211. FILES of <filespec>
  212.  
  213.     Number of matching files (all attributes), wildcards allowed.
  214.     Errorlevel 0.
  215.  
  216.     Example:    call var set n=files *.TXT
  217.  
  218.  
  219. DIRS of <spec>
  220.  
  221.     Number of matching directories (all attributes), wildcards allowed.
  222.     Errorlevel 0.
  223.  
  224.     Note:       call var set n=dirs FOO
  225.                 returns "1" (if directory FOO exists)
  226.  
  227.                 call var set n=dirs FOO\*.*
  228.                 returns number of subdirectories under FOO
  229.  
  230.  
  231. SIZE of <filespec>
  232.  
  233.     Wildcards allowed. Size of matching files (all attributes)
  234.     added up (as by DIR command).
  235.  
  236.     Errorlevel 0: size returned, 2: no file(s) found
  237.  
  238.     Example:    call var set n=size of *.TXT
  239.  
  240.     Optionally: size(KB) or size(MB), result rounded up
  241.                 1KB=1024 bytes, 1MB=1024 KB
  242.  
  243.     Example:    call var set n=size(KB) of *.TXT
  244.  
  245.  
  246. LINES of <filespec>
  247.  
  248.     VARSET counts number of CR's. An empty file will return "0".
  249.     Errorlevel 0: number of lines returned
  250.     Errorlevel 2: file not found or wildcards were used
  251.  
  252.     Example:    find "FOO" < source.txt > temp.txt
  253.                 call var set N=lines of temp.txt
  254.                 if not (%N%)==(1) goto ERROR
  255.  
  256.  
  257. VOL of <drive>
  258.  
  259.     Returns volume label of <drive>. Only the first character is
  260.     relevant (colon is optional).
  261.     Errorlevel 0: ok, 2: invalid drive
  262.  
  263.  
  264. DRIVE of <filespec>
  265.  
  266.     Drive returned (with colon).
  267.  
  268.     If drive was included in the given filespec,
  269.     then: drive is extracted, errorlevel:0
  270.     else: the current drive is returned, errorlevel:1
  271.  
  272.  
  273. -DRIVE of <filespec>
  274.  
  275.     Drive is removed, filespec is returned as given, however without
  276.     drive letter and colon; errorlevel 0
  277.  
  278.  
  279. NAME of <filespec>
  280.  
  281.     Name of file or directory is returned without path and extension.
  282.     Errorlevel:0
  283.  
  284.     Example:    call var set FN=name of "C:\my files\some doc.txt"
  285.     returns:                 FN=some doc
  286.  
  287.  
  288. EXT of <filespec>
  289.  
  290.     Name extension of file or directory is returned (without the dot).
  291.     Errorlevel:0
  292.  
  293.  
  294. -EXT of <filespec>
  295.  
  296.     The extension is removed, rest is returned as specfied (w/o dot).
  297.     Errorlevel:0
  298.  
  299.  
  300. LFN of <filespec>
  301.  
  302.     Please note the conditions:
  303.  
  304.     If LFN's are supported, AND <filespec> exists, AND there are no
  305.     wildcards,
  306.     then: the long file name with full path is returned, errorlevel:0
  307.     else: the FULL command is executed (see below), errorlevel:1
  308.  
  309.     Notes: Errorlevel 0 means that the file or directory exists.
  310.            On errorlevel 1 this is not sure (see FULL).
  311.  
  312.            No LFN support under Windows NT/2000
  313.  
  314.  
  315. SFN of <filespec>
  316.  
  317.     Please note the conditions:
  318.  
  319.     If LFN's are supported, AND <filespec> exists, AND there are no
  320.     wildcards,
  321.     then: the short file name with full path is returned, errorlevel:0
  322.     else: the FULL command is executed (see below), errorlevel:1
  323.  
  324.     Notes: Errorlevel 0 means that the file or directory exists.
  325.            On errorlevel 1 this is not sure (see FULL).
  326.  
  327.            No LFN support under Windows NT/2000
  328.  
  329.  
  330. FULL of <filespec>
  331.  
  332.     <filespec> is completed with drive and path, if necessary.
  333.     <filespec> may not in fact exist (it is not verified). However,
  334.     if the path is to be completed, the drive must be valid.
  335.  
  336.     Errorlevel 0: ok
  337.     Errorlevel 1: same as 0, but command was invoked through LFN/SFN
  338.     Errorlevel 2: path not completed due to invalid drive
  339.                   (filespec returned unchanged!)
  340.  
  341.     Point elements in path (referring to current or higher level
  342.     directory) are resolved, as with the LFN/SFN commands.
  343.  
  344.     These examples all return the path of the current directory:
  345.  
  346.     FULL of .
  347.     FULL of file.ext\..
  348.     FULL of util\data\...
  349.  
  350.     Append "\.." to remove the file name or last subdirectory from a
  351.     given file name with path,
  352.  
  353.     for example:   call var set p=FULL of c:\some\where\file.ext\..
  354.     will return:                          c:\some\where
  355.  
  356.     Note: the FULL command ignores invalid backsteps (beyond root).
  357.  
  358.  
  359. STRING(p,l) of <string>
  360.  
  361.     Returns substring from position p (default:1) with length l (default
  362.     is rest of string).
  363.  
  364.     Note that quote marks are always removed (and do not count for
  365.     the position p).
  366.  
  367.     Example:    call var set foo=string "something" new /U
  368.     returns:                             SOMETHING NEW
  369.  
  370.     Example:    call var set foo=string(2,4) "something"
  371.     returns:                                   omet
  372.  
  373.     Be sure to use quote marks if a slash may occur within a string.
  374.  
  375.     The errorlevel is set to the length of the returned string.
  376.     Example (testing without executing SET):
  377.  
  378.                 VARSET x=string %name% >nul
  379.                 if errorlevel 9 goto TOO_LONG
  380.  
  381.  
  382. (arithmetic)
  383.  
  384.     Evaluation of expression (integers)
  385.  
  386.     No special keyword required: the rest of the line will be evaluated
  387.     (up to options). Quote marks allowed, but ignored.
  388.  
  389.     The expression is processed with precedence of */\  operators,
  390.     i.e. 2+2*5=12, and support of (nested) parentheses. The values may
  391.     be signed.
  392.  
  393.     Only integer values! Thousands separators (acc.to country settings)
  394.     are ignored. Value range: +/-2 billion (2^31-1).
  395.  
  396.     Operators: + - * / \  (backslash for remainder after division)
  397.  
  398.     Examples:   call var set COUNT=%COUNT%-1
  399.                 call var set PR=12345679*81
  400.                 call var set DIF=12-34
  401.                 call var set X=(-12*-34/(200-188))+222
  402.  
  403.     Note: Avoid spaces in expression, or enclose the expression in quote
  404.     marks (see quote handling).
  405.  
  406.     Errorlevel 0:   result is positive or zero
  407.                1:   result is negative
  408.                2:   overflow or division by 0 (result empty)
  409.                255: invalid arithmetic expression (result empty)
  410.  
  411.     Output options:
  412.  
  413.     /Rn     right align, with total length n
  414.     /Zn     fixed length n with leading zeros
  415.     /T      thousands separators inserted (acc.to Country)
  416.  
  417.     If you want to compare two values, you don't need the CALL VAR
  418.     construct:
  419.                 VARSET x=%A%-%B%
  420.                 if errorlevel 1 goto B_is_greater
  421.                 if %a%==%b% goto AB_equal
  422.  
  423.  
  424. 4.1 History
  425.     -------
  426.     Ver.1.0  Mar 2001
  427.     Ver.1.1  Jun 2002
  428.              Bugfix NAME=.. now handles multiple extensions properly
  429.  
  430.  
  431. 4.2 Disclaimer, Copyright
  432.     ---------------------
  433.     This program is distributed as "freeware", copyright reserved by the
  434.     author. There are no warranties of any kind, nor any liability by
  435.     the author. Users accept full responsibility for the use they make
  436.     of the software and for any damage caused thereby.
  437.  
  438.     Contact the author:
  439.  
  440.     Email      horst.schaeffer@gmx.net
  441.  
  442.     Homepage:
  443.  
  444.     English    http://home.nikocity.de/horst.muc/int/
  445.     German     http://home.nikocity.de/horst.muc/
  446.  
  447. *** 04 JUN 2002
  448.