Overview of BUTOZIP.BAT Tool -- Version 1.8

Last Updated:   8/24/21  16:37          Jeffrey Knauth           jeff@jgkhome.name

Introduction

BUTOZIP (Back Up to Zip) creates a compressed file, a zip file, containing a designated set of files you want to archive, i.e., back up. When you invoke BUTOZIP, you specify the target directory (including its drive), e.g., E:\ARCHIVE, where you want the zip file to be placed. In the following text I'll typically use "directory" in place of "folder" (the standard Windows term), but mean the same thing.

BUTOZIP uniquely names the zip file by using a sequence number (a generation number), the creation date, and a userid. A separate sequence number counter is maintained for each Windows user sharing the target directory. With this naming, new backups don't overlay previous backups in the target directory. This allows multiple generations of backups to exist in the directory and allows multiple users to share that directory. With this zip file naming convention, it is very easy to locate a specific backup. Here is how a group of such files might be named in a target directory, e.g., E:\ARCHIVE, shared by two users:

For example, Bob might execute BUTOZIP.BAT E:\ARCHIVE, where his BUTOZIP.BAT has been edited to back up these directories (and their subdirectories) and files: C:\MISCPROG, C:\USERS\BOB\WORK, C:\USERS\BOB\DOCUMENTS\LETTERS, C:\SAVE\RESUME.DOC, and D:\BOOKS\DRAFTS. This is data which Bob changes frequently and would really hate to lose. The total disk space taken up by this data is not particularly large, maybe a few hundred MB. Note that BUTOZIP is not intended to back up very large directories, such as you might have for music or photos. The result of Bob's execution of BUTOZIP is the creation of a new zip file in E:\ARCHIVE, which might be on an external hard drive or flash drive. Using the sample directory shown above, if Bob next ran BUTOZIP on 12/3/12, the new file will be named Bob_#1542__2012-12-03.zip.

To later access files that were backed up by BUTOZIP, see Accessing Files from a Backup. Essentially you just use File Explorer (previously called Windows Explorer) and some Windows built-in facilities to decompress the zip file. Standard Windows procedures can then be used to copy, print, etc., the data.

By setting up a Windows shortcut, you can make running BUTOZIP a single-click operation to archive hundreds or thousands of scattered files into a single, compressed, organized file. Run BUTOZIP as often as needed; all the zip files created (one per BUTOZIP invocation) will nicely coexist in the target directory. You can create multiple shortcuts, each going to a separate target directory, e.g., one on a hard drive and another on a flash drive. Additionally, you can have multiple copies of the BAT file, each with a different name, e.g., BU_WORK.BAT, BU_GAMES.BAT, etc., where each is edited to back up a different set of files if you want to keep the backups separate. Doing regular backups can also be automated via the Windows Task Scheduler.

To make most efficient use of the BUTOZIP, it helps if you have organized data along the lines described in Organizing Your Data To Simplify Backups (mainly just grouping the data into a few directories, but without including many extraneous files), although this organization is not required. More overview information can be found in the "Selective Backups" section of Tools for Making Backups. These references are sections of the jgkhome.name\PC_Info\PC-InetNotes.htm file.

Command Syntax

BUTOZIP is usually run from a shortcut or from the Task Scheduler (see "How To Run BUTOZIP" below). However it can also be run from a command window. Here is the basic syntax, where [...] means any parameter within a set of brackets is optional.

BUTOZIP  [target  [password]]

Preparations for Using BUTOZIP

Before starting to use BUTOZIP, you must do some setup. This has to be done only once.

XCOPY cannot copy a locked file, a file opened for exclusive use by some process. If you want to use BUTOZIP to back up such files, you should close them first. If you forget to do so, the associated XCOPY will fail and issue an error message, such as "Sharing violation". Before running BUTOZIP I sometimes forget to close Thunderbird, which has some locked files. To make the XCOPY failure reason obvious, I put logic in BUTOZIP warning me to close Thunderbird and then rerun BUTOZIP. If you have similar files, you might include and modify that code.

How To Run BUTOZIP

The BAT file can be invoked in a number of ways. Here are a few:

If the backup completes successfully, BUTOZIP will display the main report file as its final output in the command window, below all the displayed XCOPY commands. This report normally consists of a number of "xx File(s) copied" lines, one for each XCOPY you had in the BAT file, and a "******* COPY TO TARGET DIRECTORY WAS SUCCESSFUL! *******" if BUTOZIP found no errors. There will also be some lines with timestamps taken at major points in the operation, as well as a display of some key variables. If an error was detected, either Windows or BUTOZIP should report it and then abort the operation. A successful run should produce something similar to this as the final output:

======================================================================

BUTOZIP version 1.8 report on Tue  8/24/2021
----------------------------------------------------------  6:00:00.17
21 File(s) copied
310 File(s) copied
1525 File(s) copied
181 File(s) copied
144 File(s) copied
4 File(s) copied
1 File(s) copied
2 File(s) copied
1 File(s) copied
198 File(s) copied
----------------------------------------------------------  6:00:14.93
Target directory for zip file:  X:\BACKUPS     Backup: #2771

*******  COPY TO TARGET DIRECTORY WAS SUCCESSFUL!  *******

   C:\BUTOZIP_TEMP\Jeff_#2771__2021-08-24.zip  to  X:\BACKUPS

----------------------------------------------------------  6:00:35.07
Zip file size: 107,341,354    )))))))  104,826 KB  (((((((
----------------------------------------------------------  6:00:36.42

Notes

CAUTION: If the BAT file cannot complete successfully, e.g., if there is not enough space on the destination medium to hold the zip file, BUTOZIP will abort, either automatically or as a result of your response to a prompt. Then you must do a manual cleanup of the work directory and the target directory. (You can just delete the whole work directory after looking at the contents; it will be rebuilt the next time BUTOZIP is run.) The TDIR subdirectory and zip file in the work directory can be very large and serve no purpose after the BAT file exits. It is not good to leave them around if the BAT file did not erase them.

NOTE: Color capability has now been added to BUTOZIP, e.g., to display a different background color in the command window if an error has been detected vs. if BUTOZIP completed successfully. If you don't like the colors used, you can change the @COLOR commands when you edit the BAT file.

Internal Variables of BUTOZIP.BAT

The following table lists some key variables used by BUTOZIP. You probably will not need to change any of them. (As noted above, the main tailoring you must do to BUTOZIP.BAT is setting up the XCOPY commands.) This table shows you the main components used to construct the zip file name. Knowing the name structure will help you use the backups most effectively. Details are in the How It Works section below.

internal variable default value
(from butozip.bat)		 purpose
ZIP C:\JGK\7ZIP\7ZA.EXE ZIP specifies the location and name of the 7-Zip command line program, 7za.exe. This program can be downloaded from here. For example it is in the "7-Zip Command Line Version" zip file. (The 32-bit program works fine on both 32-bit and 64-bit PCs.) Unzip the file, placing the contents into the directory named by the front part of the ZIP variable, e.g., in the C:\JGK\7ZIP directory in this case. If you want to use a different name for this directory, you can do so; be sure to modify this SET variable to match.
BUTARGET D:\BACKUPS You intend for the zip file created by BUTOZIP to end up in a specific target directory. The BUTARGET variable names the default target directory. If this default target location is not what you want, you can override it by invoking BUTOZIP.BAT with a parameter, e.g., BUTOZIP.BAT  F:\DAILYBACKUPS. In any event, the chosen target directory must already exist before BUTOZIP.BAT is run.
BUWORK C:\BUTOZIP_TEMP BUWORK specifies the name of a hard drive directory that can be used as a work area. It should be on a hard drive for speed. The user running BUTOZIP must have full access to the directory contents (read/write/create/erase). This is where the zip file will be built initially before it is moved to its final destination. The BAT file creates this directory if it does not already exist. If the default of C:\BUTOZIP_TEMP is not appropriate for your PC, modify the SET to specify another location.
UNAME %USERNAME% The %USERNAME% setting for UNAME will resolve to the name of the user running BUTOZIP. That is, it is the user name for the Windows PC account under which the BAT file is run. If multiple users share the PC, using different accounts, they can all make backups in the same target directory. A user name will be made part of each zip file's name, allowing each file to be associated with the proper user.
BUPWD (null, i.e., no password) If specified, the password must be the second command parameter, i.e., a drive must be specified as the first parameter. The password is passed to 7-Zip to encrypt the zip file and must be acceptable to 7-Zip. If no password is specified, the zip file is not encrypted.

XCOPY

XCOPY commands specify the names of the directories and files to be archived, as well as the names to be given to the copied data. Options can be used to say whether a whole directory tree should be copied (/S) and whether hidden files (/H) and empty directories (/E) are to be copied. Output messages are directed to a report file. The /Q option suppresses some unneeded XCOPY messages.

The general command format is:   XCOPY   from-data   to-data   options  >>  report-file   2>&1

CAUTION:  If any directory or file names (including parts of the TDIR directory name described below) contain blanks (spaces), be sure to surround the full names with quotes in the XCOPYs. That is the standard Windows requirement for such names when used in a command. For example:

   XCOPY  "C:\LONG  SPACED  NAME\*.*"   "%TDIR%\MISC\*.*"   /S  /H  /Q  >>  %BUREPORT%  2>&1

CAUTION: If you want to back up files or directories found in your home directory, which is often something like C:\Users\username, be aware that the "username" there is not necessarily the normal username found via %USERNAME%. Nowadays Windows install can create that home directory using the first few characters of the email address used for the Microsoft account of the installer. To access the home directory, use %USERPROFILE% to find its name; it might yield something like C:\Users\jgkna, while the actual username is Jeff. See examples in the sample BUTOZIP.

Examples

BUTOZIP

An unencrypted zip file is created in D:\BACKUPS, the default directory.

BUTOZIP  F:\FINANCIALS

An unencrypted zip file is created in F:\FINANCIALS.

BUTOZIP  E:\DRAFTS  tyb4u3ldwrRH

An encrypted zip file is created in E:\DRAFTS using tyb4u3ldwrRH as the password.

BUTOZIP  D:\BACKUPS  qlGy59apx

An encrypted zip file is created in D:\BACKUPS using qlGy59apx as the password. Even though D:\BACKUPS is the default directory, it still must be specified since the password must be the second parameter.

How It Works

Here is the basic logic flow. The most important actions are echoed to the display while the BAT file is running.

  1. First some housekeeping is done:
    • Get the password from the command (second parameter) and save it in BUPWD. It may be null.
    • Check that the work directory exists as specified by BUWORK. If it does not exist, create it. Ensure the user running BUTOZIP has the proper access authority for the work directory.
    • Check that the 7-Zip program exists as specified by ZIP.
    • If BUTOZIP was invoked with a directory parameter, set the BUTARGET variable with this data; otherwise use the default value coded in the BAT file for this variable. Now check that the target directory exists as specified by BUTARGET. Ensure the user running the BAT has the proper access authority for the target directory.
    • Each user has his/her own generation count file, whose name includes the user name from UNAME. If the user's count file does not exist in the target directory, create it there with the count initialized to 0. Whether the file previously existed or not, now add 1 to the count in that file.
  2. BUTOZIP then creates a TDIR (Target Directory) variable. This is the name of a temporary work subdirectory that will be used to collect copies of the data to be archived. It is also much of the name of the zip file to be created, to provide uniqueness for that name. Here is an example of what the TDIR value might be and where the name parts come from:
       TDIR = C:\BUTOZIP_TEMP\Jeff_#1537__2012-11-29, where
    • C:\BUTOZIP_TEMP is the value of the BUWORK variable.
    • Jeff is the value of the UNAME variable.
    • 1537 is from the Jeff user's generation count file.
    • 2012-11-29 is the current date, obtained from Windows.
    • The other characters (#, _, \) are constants.
  3. XCOPY commands then copy the directories and files to be archived into the work subdirectory named by TDIR. The "copy to" directory structure and the names of the directories in it need not match those of the source. When you set up the XCOPY commands, the "copy to" directory names can be changed to make the archive structure simpler than that of the source, if desired.
  4. The 7-Zip program (specified by the ZIP variable) is then invoked to create a TDIR.zip file from the contents of the work subdirectory named by TDIR. If there was a non-null password saved in BUPWD, then 7-Zip is invoked a second time, this time to encrypt the TDIR.zip file using the password. This also hides the names of the backed-up files, not just their data, from anyone not knowing the password. If there is no password, TDIR.zip is left unencrypted. In either case, the final result is a TDIR.zip file.
  5. The zip file is then copied to the target directory (named by the BUTARGET variable). In the example above, the zip file would be named:   Jeff_#1537__2012-11-29.zip.
  6. If the copy was done successfully, the larger contents of the work directory are erased, leaving only a couple of small report files.
  7. Finally, the main report file is displayed.

Accessing Files from a Backup

At some point after you have created a backup zip file, you may want to recover files from it. The 7-Zip tool has facilities to do this, which won't be covered here. However Windows has built-in facilities that can do the job. You can do some simple doubleclicking (multiple times) to get to the files in Windows "compressed folder" mode. There you can view the files, but there are limited things you can do with them in that mode, e.g., not all programs will execute properly. Note you can copy a file or files from the "compressed folder" to a normal folder, which will not have the "compressed folder" restrictions.

Alternatively, you can do some mouse right-clicking on the zip file and select "Extract All" from the menu (maybe multiple times") to completely unzip the files into a standard folder (directory) of your choosing. There things act more normally.

If you specified a password to encrypt the zip file, along the way you will be prompted to enter the password. Also, if you used encryption, there will be an additional doubleclick required because the original data was zipped twice, once to create the original zip file and then again to encrypt that file.

In more detail, to unzip an encrypted zip file into a "compressed folder":

If the zip file had not been encrypted, no password prompt occurs and there is one fewer doubleclicks required. In general, just keep doubleclicking until the backed-up files are displayed in the "compressed folder".

Doing an extract to a normal directory (folder) is similar. Just keep right-clicking and selecting "Extract All" on the output until "Extract All" is no longer in the right-click menu. Then you can instead doubleclick that final directory to see the backed-up files in a normal directory. If encryption had been done on the original zip file, you will be prompted for a password after selecting the first "Extract All".

History of Changes

Here are the main changes to date for the BUTOZIP.BAT file and this Overview file.

Home