* C:\DOC\NETUPD.DOC **** 11 JULY 96 *** 16.32 ***************; G W Robinson


                   R A L   I B M   P C   U S E R   G U I D E
                   -----------------------------------------

                            NETUPD network updating
                            -----------------------



      1. Introduction
      ===============

      NETUPD is a DOS front end to drive the RAL UPDATE command which
      simplifies the backing up of files to a network server.  An
      Environment variable is used to define where the backup is to be
      copied and NETUPD can then be used to create a replica of all or
      part of the PC filestore under this directory. NETUPD also has
      facilities to generate a cycle of backups based on either the
      day, the week number in the year or the month and facilities to
      customise the backing up of different directories. It can also be
      run via a Windows front end WNETUPD.

      NETUPD.EXE, NETUPD.PIF, WNETUPD.EXE, WNETUPD.HLP, UPDATE.EXE and
      CHKCHAR6.EXE must all be in a directory on the PATH and C:\BIN is
      recommended at RAL.  UPDATE must be v2.4 or later since this adds
      new facilities and fixes a problem in accessing network drives.

      The current release of NETUPD is 1.2 and of WNETUPD is 2.2.
      Differences from previous versions are detailed in section 11.


      2. Simple Usage - Backup
      ========================

      Decide where you wish to backup your C: drive, eg: e:\back, then
      SET the Environment variable NETUPD$C to this value eg:

        SET NETUPD$C=e:\back

      Then SET the UPDATE parameter settings via NETUPD$PAR.  The
      following are recommended:

        SET NETUPD$PAR=/abjkrstw

      This will create a read only copy of the files without the archive
      bit set and will only report those files that are copied to the
      backup.  Note the /j tells UPDATE to ignore differences in the
      directory creation dates since these cannot be set on the copy on
      a networked disc.  Option /s can be repeated if no reporting of
      updates is required.  The SET commands should ideally be done in
      your AUTOEXEC.BAT.  Note that apart from testing as detailed next
      this is all that is required to run NETUPD via its Windows front
      end WNETUPD.

      Now CHDIR to the directory you wish to backup and type:

        netupd

      This will execute the necessary UPDATE commands to create a replica
      of the part of the filestore tree you are in and will copy the
      contents of the current directory and all those below to it.  It is
      recommended that this is tried in the first instance on a small
      directory just in case something goes wrong.

      To be more selective about what is backed up use either a file
      definition eg:

        netupd *.doc

      to just backup files ending in DOC or add the /p option to prompt
      for each file to be updated eg:

        netupd /p

      More sophisticated mechanisms to achieve selection are described
      later.

      To backup the whole filestore you can use NETUPD in the C:\
      directory but be warned this can take some while.

      To have multiple copies of your backups you can either change the
      setting of NETUPD$C or it can be overridden by giving a second
      parameter to the NETUPD call eg:

      netupd *.* e:\back2

      Alternatively the cycling facilities defined below can be used.

      For machines with more than one fixed disc the parameter NETUPD$D
      should be used for the D: drive etc.



      3. Simple Usage - Restore
      =========================

      Since the backup directory has a replica of the PC filestore then
      you can simply copy the backup to the C:  drive when required.  It
      is probably safer to use NETUPD or UPDATE for this since they will
      indicate whether the backup copies are the same or different.
      Adding the /o option (which will also force prompting) will permit
      backup copies to overwrite newer versions.

      To use NETUPD the NETUPD$C variable must be pointing to the correct
      backup area.  You can either CHDIR to the backup directory or if
      you are in the direcory you wish to restore to then just type:

        netupd /\

      which will change you to its backup directory if it exists.  Then
      type NETUPD as before.  This will UPDATE the copies to the correct
      place on the C drive.  It is perhaps wise to put the /p option on
      just in case and then respond ~p when you are satisified everything
      is ok.

      Note that after a NETUPD /\ command the current network directory
      (eg E:) is the backup of the current C: directory.  Thus moving
      files between the two is achieved by simply specifying the drive
      letter.  For example to copy a file from the backup could be done
      by the command:

        copy e:filename.ext c:



      4. Program Specification
      ========================

      NETUPD format is:

       netupd FromFilePath ToDirPath &IniFile #dcn ~FromFile @Commands /options

      All parameters are optional.  If none are given and the current
      directory is on the C:  drive then all files in it are updated to
      an identical directory structure under the directory defined by the
      NETUPD$C Environment variable which usually points to a network
      drive.

      If the current directory is under the directory defined by NETUPD$C
      then the UPDATE is done to the equivalent C:  directory.  A second
      disc D:  would update to the directory defined by NETUPD$D.

      FromFilePath overrides the directory and/or files to be updated and
      can contain * or ?. More than one selection may be specified
      separated by a + sign with no intervening spaces provided the
      files/directories specified are in the current directory.

      ToDirPath overrides the directory defined by NETUPD$C.

      &IniFile is a file which contains NETUPD parameters which are
      either global to all calls or specific to the directory being
      backed up.  A specification is given in a following section.

      The remaining parameters may be in any order and may be supplied
      via the Environment variable NETUPD$PAR, on the NETUPD command or
      via the IniFile defined by the &IniFile parameter and they are
      processed in that order.  If a combination is used then the
      parameters act as if they had all been specified on the NETUPD
      command line except for &IniFile and #dcn where the NETUPD
      parameter takes precedence over one defined via NETUPD$PAR.  A #dcn
      in an &IniFile also takes precedence over one defined via
      NETUPD$PAR but is overridden by one on the NETUPD call.  Warning
      messages when this occurs are given unless the /ss option is
      active.

      #dcn defines extensions to the backup directory name in order to
      achieve a cycle of backups.  A specification is given in a
      following section.

      The remaining parameters are added to the UPDATE command(s)
      generated by NETUPD. They are:

        ~FromFile (repeatable) defines filenames and directories that are
                  to be ignored. Note that ! can be used in place of ~.

        @Commands defines a file that can contain Update and other DOS
                  commands but note that no mapping to the NETUPD$C
                  directory is done.

      The following options modify the action taken by NETUPD and UPDATE.
      Note that the normal action of UPDATE is to make a copy of a
      file in the ToDirPath directory if one does not exist or is older
      than the original.

         a  unset archive bit on file being copied from
         aa only update if archive bit set and then unset it
         b  dont set archive (backup) bit on file being updated to
         d  directory - update directory as well as contents
         e  only update to files that already exist
         f  only update files
         h  display this help information
         i  inspect the contents of each file and see if same
         j  ignore creation date/time differences on directories
         k  cache disc i/o
         l  do not create filestore structure on copy
         n  do not actually update any files (for testing)
         o  update old to new files - ie reverse normal update process
         p  prompt for permission to update
         r  update read only file to read only copy without prompting
         s  list only those files being updated or unusually different
         t  tree - update files from lower directories as well
         u  update (ie copy) all files
         v  verify any file updated
         w  set read only (write protect) on files being updated
         x  give a more? prompt and pause when update completed
         z  delete file if no copy found (use with care)
         ?  display this help information
         ~  negate meaning of next option
         !  negate meaning of next option
         :xy substitute all instances of character x in filenames by y in
             updated file name
         \  dont update but change to the backup directory

      Notes
      -----

      1.  The file USERUTIL.DOC documents the RAL utilities and this
      includes details of an earlier version of UPDATE. The subsequent
      changes are menitioned in this document.

      2.  Associated with each file is its last written date and time
      plus some file attributes. The attributes include a read only bit,
      which when set means the file cannot be written to, and an achive
      bit which is normally set each time a file is written to.

      3.  Certain characters which are legal in PC filenames are not
      acceptable to network filestores based on other computers.  An
      example is the tilde character (~) which is illegal in the sixth
      character of a filename (eg.  myfil~v1.c) on a Unix system
      because this clashes with the mechanism used to map long filenames
      in the Unix filestore.  Thus filenames of this form, such as the
      Amipro style files, cannot be backed up.  To overcome this UPDATE
      has the /:xy option which allows the user to specify that
      character x in a filename will be changed to y in the name of the
      backup copy.  Obviously the replacement character used must be
      acceptable to the network filestore and ideally illegal in a PC
      filename so there is no chance of confusion.  Possible characters
      would be =, ; and +.  However for Unix filestores these are also
      unacceptable so rarely used characters such as those with ASCII
      values greater than 127 are the best bet.  These are obtained by
      holding down the Alt key and typing a decimal number of the Keypad
      number keys, such as 246, then releasing the Alt key which for 246
      gives a  (divide sign).

      The utility CHKCHAR6 is provided to check filenames for a ~
      (tilde) as the sixth character or any other character which may be
      used as a substitute.

      Windows NT users should note that if such a character is defined
      via the Environment variable NETUPD$PAR then this MUST be done via
      the SYSTEM entry in the Control Panel.  Doing this via other NT
      mechanisms for setting Environment variables (AUTOEXEC.BAT amd
      AUTOEXEC.NT) will usually give a different character.  Note also
      that the divide sign was chosen because it will work on both
      Windows 3.1 and Windows NT.  The previously recommended value of
      Alt 247 (double tilde) does not work under NT as it uses a
      different code page (850) from Windows 3.1 which at RAL is 437.

      4.  This software cannot backup long filenames such as are
      generated by Windows NT and Windows 95.  In this case the 8.3
      format substitute name generated by these systems will be used.
      Hence any restoration of a file from a backup will not reinstate
      its long filename but will use the 8.3 form instead.  Note that
      the ~ used by Windows in generating the 8.3 form is made the
      seventh character of the filename so does not give problems with a
      UNIX filestore as detailed in the previous note.

      5.  When NETUPD is used to UPDATE from C:\ the swopfiles for
      Windows 3.1 (386spart.par) and Windows NT (pagefile.sys) are not
      backed up as they are very large files and contain nothing of
      value.

      6.  When NETUPD is used to update from a network drive back to say
      the C:  drive then if the /w and /r options are set they are
      negated.  Thus the copy on the network drive can be made read only
      but this is not transferred back to the copy on the C:  drive.
      Similarily the /:xy character substituions are also reversed so
      that files are restored back to their original PC names.


      5. Examples
      ===========

      The following assume that Environment variables have been SET, probably
      in AUTOEXEC.BAT as:

         set NETUPD$C=e:\back       define backup directory for drive C:
         set NETUPD$PAR=/abjkrstw   define options for the UPDATE command

         netupd             If on drive C:  update all files in the
                            current directory to equivalent directory on
                            E:\BACK and create any new directories as
                            needed.  If current directory is C:\MYFILES
                            the files updated to directory
                            E:\BACK\MYFILES.  If current directory is
                            C:\MYFILES\DEV the files updated to directory
                            E:\BACK\MYFILES\DEV.  This achieves a
                            backup.  If current directory on drive E:
                            under the BACK directory (eg.
                            E:\BACK\MYFILES) then update to equivalent
                            directory on C:  (eg.  C:\MYFILES).  This can
                            restore files.  Option /o will be needed to
                            replace newer versions by the backup copy.

         netupd *.*         As first example

         netupd *.doc       As first example but only files ending in .DOC

         netupd *.doc+*.txt+*.ps  As first example but only files ending
                            in .DOC, .TXT and .PS

         netupd /p          As first example but prompt before updating

         netupd /o          As first example but give option to copy an
                            older file over a newer one.  Prompting will
                            be forced

         netupd ~*.tmp      As first example but omit files ending in TMP

         netupd c:\myfiles  Backup from directory C:\MYFILES

         netupd /l          As first example but dont create directory
                            structure. Copy files into E:\BACK.

         netupd *.* e:\newback  Backup to E:\NEWBACK instead of default
                            defined by NETUP$C.  To restore either SET
                            NETUPD$C to the new value and use NETUPD from
                            the backup copy of the directory or simply
                            COPY, XCOPY or UPDATE (safer especially if /p
                            prompt option used) from the backup to the
                            original directory.

         netupd /\          Change to backup directory (eg.
                            E:\BACK\MYFILES). Repeating will change
      back.


      6. #dcn Backup Cycle Parameter
      ==============================

      This parameter gives an automatic mechanism to change the name of
      the backup directory based on a chosen cycle.  This can be either
      the day of the week, the week number in the year, or the month of
      the year.  It uses no special files to keep track of the cycle but
      relies soley on the current date as defined by the PC so this must
      be correct.  The length of the cycle may be reduced from its normal
      maximum, eg cycling over three days rather than seven, and more
      than one cycle can be used.  A separator character can also be
      defined to help in the naming system.  A #dcn parameter on the
      NETUPD call takes precedence over one in an &IniFile which in turn
      takes precedence over one supplied via the NETUPD$PAR Environment
      variable. A ~# or !# parameter at a higher precedence nullifies the
      effect of a #dcn parameter.

      Definition
      ----------
      #dcn defines extensions to the backup directory name as follows:

        d is an optional character from one of ., -, _ or \.
        c is a character which  defines the cycle interval;
          d = day (su,mo,tu,we,th,fr,sa - commences Sunday)
          w = week (w01,w02,W03 etc - commences first Sunday in Jan)
          m = month (jan,feb,mar etc)
        n is an optional number giving the cycle maximum

      Examples
      --------
      The following show the directory name generated from a NETUPD$C
      variable of e:\back with various # parameters:

        #d    Gives a different directory for each weekday viz:
                e:\backsu (on Sunday), e:\backmo (on Monday),
                e:\backtu (on Tuesday), e:\backwe (on Wednesday), etc

        #.d3  Gives a different directory for every three weekdays viz:
                e:\back.su (on Sunday, Wednesday and Saturday)
                e:\back.mo (on Monday and Thursday)
                e:\back.tu (on Tuesday and Friday)

        #\w4  Gives a different directory for every four weeks viz:
                e:\back\w01 (on week 1, 5, 9, 13 etc in the year)
                e:\back\w02 (on week 2, 6, 10, 14 etc in the year)
                e:\back\w03 (on week 3, 7, 11, 15 etc in the year)
                e:\back\w04 (on week 4, 8, 12, 16 etc in the year)

        #_m   Gives a different directory for every month viz:
                e:\back_jan (in January), e:\back_feb (in February) etc

        #\w-d Gives a different directory for every day of the year viz:
                e:\back\w01-su (on Sunday of week 1)
                e:\back\w01-mo (on Monday of week 1)
                e:\back\w01-tu (on Tuesday of week 1)
                etc
                e:\back\w02-su (on Sunday of week 2)
                etc


      7. &IniFile Parameter File Specification
      ========================================

      This parameter defines a file which contains parameters for NETUPD.
      An &IniFile parameter on the NETUPD call takes precedence over one
      supplied via the NETUPD$PAR Environment variable.  A ~& or !&
      parameter at a higher precedence nullifies the effect of a &iniFile
      parameter.

      The IniFile can contain two sections along with comments.  The
      latter must be on a separate line starting with /*.  One section
      defines NETUPD parameters that apply to all backups and can be used
      instead of/as well as the NETUPD$PAR Environment variable or the
      NETUPD call.  This section commences with the line [global_par] and
      the parameters may be spread over one or more lines eg:

        [global_par]
        /abjkrstw  /:~
        ~*.tmp

      The second section contains parameters which are to apply only when
      NETUPD is run in that directory or one below it.  It commences with
      the line [match_dir_par] and each line commences with a directory
      path and is followed by the NETUPD parameters that are to apply.
      For example:

        [match_dir_par]
        c:\dev\  #.d /a
        c:\mail\ #.d /a
        c:\winword\ #.d /a ~~*.wfw

      which gives parameters to be applied to all NETUPD calls in
      C:\DEV, C:\MAIL and C:\WINWORD and directories below them. Note
      they do not apply to NETUPD calls in directories above them, C:\ in
      this example, which subsequently UPDATE that directory.


      8. Advanced Usage
      =================

      One of the aims of NETUPD was to make the system versatile yet
      simple to use.  In the main a single command should achieve all
      that is required and its actions should depend on the the context
      it is given in.  This could either be NETUPD or one or more BAT
      files which call NETUPD with different parameters to suit different
      situations such as a weekly full backup or a daily incremental
      backup.  The following illustrates some of the ways this may be
      achieved.

      The example initially assumes a user who wishes to back up his
      entire PC filestore and also to take occasional backups of a day's
      changes to directories whose files change frequently.  The latter
      would include C:\DEV where all development is done, C:\MAIL where
      e-mail is kept and C:\WINWORD where all wordprocessing files are
      kept. In addition all files ending in .TMP are to be omitted and
      the ~ (tilde) character in any filename is to be changed to 
      (divide sign) to avoid problems with the Unix filestore being
      used for the backup.

      The Environment variable NETUPD$C would still be as the Simple
      Usage example:

         set NETUPD$C=e:\back

      but the NETUPD$PAR variable is now:

         set NETUPD$PAR=/abjkrsw /:~ ~*.tmp &c:\etc\netupd.ini

      The file C:\ETC\NETUPD.INI would be created containing:

        [global_par]
        /t
        [match_dir_par]
        c:\dev\  #.d /a
        c:\mail\ #.d /a
        c:\winword\ #.d /a ~~*.wfw

      Note that /t option (to UPDATE down the filestore tree) has been
      moved to the [global_par] section from NETUPD$PAR to illustrate a
      technique which is explained below.  The [match_dir_par] section
      indicates that for the three directory names only files that have
      been changed (the /a adds to the /a in NETUPD$PAR to become /aa)
      are to be backed up and that a different directory is to be used
      each day.  In addition in the C:\WINWORD directory any files
      commencing ~ and ending in .WFW are to be ignored (these are the
      Word for Windows temporary files).

      With these settings the behaviour is very similar to the Simple
      Usage.  Changing directory to C:\ and typing NETUPD would backup
      the entire filestore to the directory E:\BACK and this can take
      quite a while.  Subsequent NETUPD calls in C:\ would backup any
      changed or new files thus overwriting any previous version and this
      could be done once a week.  The same would apply to NETUPD called
      from any directory except the three specified in NETUPD.INI.  For
      these, and these only, the backup would be to a different directory
      each day of the week:  C:\BACK.SU on Sunday, C:\BACK.MO on Monday
      etc and in each case only those files which had changed would be
      backed up and the files would not be overwritten until a week
      later.  In this manner the user has created a main backup plus
      incremental backups for his frequently changing directories.

      One anomoly in this example is the C:\ directory itself where if it
      was wished to backup a file in the C:\ directory without the rest
      of the filestore tree beneath it you would have to type:

        netupd /~t

      which would reverse the /t option and prevent UPDATE going down
      the tree. Alternatively you could type:

        netupd ~&

      which would negate the effect of the & parameter supplied via
      NETUPD$PAR since the one on the NETUPD call takes precedence.
      Hence this would not include the /t in the [global_par] section and
      this was the reason for putting it there.

      Either method could also be used in any other directory where the
      user did not wish to backup the directories below.

      Another potential confusion is the action of the following command
      which does a CHDIR to the backup directory associated with the
      current directory:

        netupd /\

      For all directories except the three in the [match_dir_par] section
      this would change to the backup directory under E:\BACK.  For the
      [match_dir_par] three this would change to backup directory under
      E:\BACK.MO on Monday, E:\BACK.TU on Tuesday etc.  To get to the
      full backup directory you would again have to negate the &
      parameter supplied via NETUPD$PAR by the command:

        netupd /\ ~&

      A final development of this example would be the need to take a
      complete backup of all, or probably more realistically, a part of
      the filestore at regular intervals, say monthly, without
      overwriting an earlier copy.  This could either be done by a BAT
      file with a series of NETUPD calls such as:

        netupd c:\dev #.m
        netupd c:\mail #.m
        netupd c:\winword #.m

      where the directories to be backed up were specified by name. Thus
      in January the backup would be to E:\BACK.JAN, in February to
      E:\BACK.FEB etc.

      Alternatively the BAT file could backup starting from C:\ and
      specify those directories that were not to be backed up thus
      ensuring any new directories were automatically included.  As this
      would probably be a long list and would not fit on a command line
      an &IniFile is probably the best way to do thus.  So the BAT file
      would contain a command of the form:

        netupd c:\ #.m &c:\etc\netupd.mon

      and C:\ETC\NETUPD.MON could contain:

        [global_par]
        ~*.tmp
        ~c:\dos
        ~c:\bin
        ~c:\bat
        ~c:\windows
        ~c:\tmp
        etc


      9. Running Under Windows
      ========================

      NETUPD can be run via a Windows fron end WNETUP.  To do this
      WNETUPD.EXE, WNETUPD.HLP and NETUPD.PIF should be in the same
      directory as NETUPD.EXE and UPDATE.EXE.  This must be on the PATH
      and C:\BIN is recommended at RAL.  WNETUPD.EXE should be added as
      a new program item to any suitable program group with a working
      directory of C:\.  The HELP button gives details of how it may be
      used.  It assumes NETUPD has been already installed and
      configured.  Note the NETUPD.PIF file adds the /x option so that
      the results of the update can be viewed before the DOS box NETUPD
      is run in closes.

      Alternatively you can use NETUPD in a Windows DOS session and use
      it as detailed above.  You can also use File Manager and select
      the directory you wish to backup.  Then choose RUN...  from the
      FILE menu, type NETUPD.PIF in the Command Line:  box and press
      Enter or push the OK button.


      10. Known Bugs/Features
      =======================

      10.1 British Summer Time/Daylight Saving Time
      ---------------------------------------------

      There are problems whenever the clocks change to or from British
      Summer Time/Daylight Saving Time.  The first problem is that the
      PC and the NFS server may not change on the same date.  RAL PC
      Support produce a utility to change the PC setting once the UK
      dates are announced since they do not conform to any formula.

      Also, for reasons which are not understood, the clock change
      causes the time stamp of files held on most NFS servers to shift
      by one hour.  Hence when viewed from the PC they are either one
      hour older or one hour newer than the version on the PC.  The
      former causes all files to be backed up again.  The latter just
      reports that all the copies are newer and the only solution is to
      run NETUPD with the /o option to cause it to backup over what
      appear to be newer versions.  Unfortunately you are then required
      to reply y to make each copy.  This can be switched off by
      replying !p but be warned that this then copies all files across
      and overwrites any genuine newer version.  Note giving the reply g
      when prompted about the copy will give the timestamp details of
      the file and its backup copy.

      10.2 Long Filenames
      -------------------

      This software cannot backup long filenames such as are generated
      by Windows NT and Windows 95.  In this case the 8.3 format
      substitute name generated by these systems will be used.  Hence
      any restoration of a file from a backup will not reinstate its
      long filename but will use the 8.3 form instead.


      11. Differences in NETUPD versions
      ==================================

      11.1 NETUPD
      -----------

      11.1.1 Version 1.0
      ++++++++++++++++++

      First release.

      11.1.2 Version 1.1
      ++++++++++++++++++

      Options /x and /l added.

      Problems with BST/DST time stamp noted.

      Lack of support for Windows NT and 95 long filenames noted.

      Backup examples changed to use drive E: instead of D:.


      11.2 WNETUPD
      ------------

      11.2.1 Version 2.2
      ++++++++++++++++++

      First general release.

      12. Support
      ===========

      NETUPD and UPDATE are made available at no charge and with no
      warrenty. The author and his employers accept no responsibility
      for any damage done by this software and it is run solely at the
      users own risk.

      To obtain support users should seek help from their normal support
      sources.

      Academic user support organisations may seek help from RAL but the
      latter will only be given on a 'best endeavours' basis.

      There is no support for other organisations other than by private
      arrangement with the author.

      Updates of the software may be obtained by anonymous FTP from
      FTP.CC.RL.AC.UK (currently 130.246.12.16).  It is held in a self
      extracting binary file NETUPDxx.EXE (xx being version number
      without a point - currently 11) in directory
      /pub/pcsupp/dos/netupd.  Executing the file will produce the
      program and documentation.

      Bug reports or problems should be reported, ideally by email, to
      Graham Robinson:

      E-mail: Graham.Robinson@rl.ac.uk  G W Robinson
      Tel UK:    01235 44 5636          Rutherford Appleton Laboratory
      Int'l : +44 1235 44 5636          Chilton, Didcot
      Fax   :    01235 44 5281          Oxon, OX11 0QX, UK

