Script Usage

Configuration information is passed to these scripts via environment variables. I recommend setting up the environment in one configuration script which then the runs PerforceBackupProcedureLibrary.bat or PerforceBackupProcedureLibrary. Advantages of this approach are:

The scripts are simpler because no command line parsing is necessary
The configuration information is contained in a file which can be under version control (more easily than command line arguments used in a Microsoft Windows Scheduled Task or Unix crontab entry, for example).
The script logic is kept separate from the configurable information.

The items that must be set in the configuration file are:

backupDirectory — where to put the backup files
backupType — normal (full) or incremental
includeStyleSheet — include XSLT style sheet link in XML output
logDirectory — where the script results are written
runCommands — whether to run the commands or run just to test the script
serverShortName — Used in file and directory names to uniquely identify the Perforce server being backed up
workspace — a Perforce client workspace, this is made the current directory before running Perforce client commands: info, set, verify, admin checkpoint and depots. If you do not use a Perforce configuration file (i.e. P4CONFIG is not set), this doesn't need to be a real client workspace. In that case, you can just set workspace to your home directory.

These values must be set if you are going to generate an RSS feed. If you do not wish to generate an RSS feed, remove from the configuration script the line which runs PerforceBackupProcedureRSS.

rssFeedFile — name of rss feed file that will be generated
rssLink — URI to location of backup logs and RSS feed on your intranet
rssManagingEditor — email address of RSS feed managing editor
rssWebMaster — email address of RSS feed web master

You can also use this configuration file to setup any other environment information such as your PATH and Perforce environment variables.

I've provided template versions of these configuration scripts for you to use. They are named MyServerPerforceBackupProcedure.bat and MyServerPerforceBackupProcedure. Copy the appropriate one of these and replace “MyServer” with the value of the serverShortName variable. This will help keep things organized.

The template configuration scripts provided vary the backupType by the day of the week. You can modify this to fit your needs. See Possible Modifications for more information on changes you might want to make.

Script Output

Log file names include the serverShortName (set in the configuration script) and the checkpoint number to aid in traceability. The following items correspond to checkpoint.23.gz.

Exemplics.23.BackupProcedure.xml — the backup procedure results
Exemplics.23.Backup.txt — the backup program output
Exemplics.23.Restore — the test restore directory
Exemplics.23.Verify.txt — the p4 verify output
Exemplics.23.bks — Microsoft Windows only, contains the list of files and folders to be backup up

The *.*.BackupProcedure.xml files contain the ShortServerName and CheckpointNumber as attributes of the root node (BackupProcedure). No information is lost if these files are renamed although it might be easier to interoperate with other scripts if you do not rename the files.

The follow list shows what the backup directory would look like if it contained Microsoft Windows backup files.

Exemplics.21.normal.bkf
Exemplics.22.incremental.bkf
Exemplics.23.incremental.bkf

The follow list shows what the backup directory would look like if it contained Unix backup files.

Exemplics.21.normal.tgz
Exemplics.22.incremental.tgz
Exemplics.23.incremental.tgz
Exemplics.snar — snapshot file used by tar to create incremental backups, not needed during restore

Viewing Results as HTML

Copy PerforceBackupProcedureHTML.xsl and PerforceBackupProcedure.css to your log directory. The backup procedure scripts have been modified so that this style sheet can be linked directly from the XML results file. Modify your configuration file to set includeStyleSheet to a non-empty value. When you view the XML file in your browser, the transform will automatically be applied. If you want to view the raw XML source, choose the “View Source” menu item from the appropriate browser menu.

You can also generate the HTML using an external processor such as msxsl or xsltproc. In this case, you will need to navigate to the generated HTML file in your browser.

msxsl MyServer.54.BackupProcedure.xml PerforceBackupProcedureHTML.xsl –o MyServer.54.BackupProcedure.htm

xsltproc –o MyServer.54.BackupProcedure.html PerforceBackupProcedureHTML.xsl MyServer.54.BackupProcedure.xml

Compatibility

Linking the style sheet directly from the XML results file works fine for recent versions of Internet Explorer, Safari, Opera and Chrome but Firefox does not properly render the HTML. The generated HTML contains calls to JavaScript functions and the Firefox generates a new document for the document.write() calls instead of using the generated HTML document. The workaround for this is to apply the transformation using an external program such as msxsl or xsltproc as previously described. Firefox has no problem when the HTML is generated this way.