The ARCHIVE Utility

The code associated with this story is available for download here.

I’m happy to present a utility I wrote that has proved to be useful to my employer. It’s called ARCHIVE, and it provides an easy way to make a backup copy of a physical file member, just in case something goes wrong during a job.

Before I present the ARCHIVE utility, let me explain why I wrote it. In a perfect world, all database files would be journaled and all database-processing programs would run under commitment control. If anything were to be found amiss–which would never happen in a perfect world–the changes would be backed out of the database, as if the program had never run. However, this is not a perfect world. Many iSeries shops run software systems that were designed before journaling was available (or at least before anybody learned how to make it work.) Retrofitting journaling and commitment control into an old application is not an easy task, nor is it as critical as most of the projects that users dream up for us to do.

It’s also good to consider that rollback is not always a viable option. Sometimes things go wrong, but no one finds out that the bad database changes took place until after other, good database changes have occurred. In such cases, the best one can often do is to list the changes that took place and reverse the database changes by hand through the application.

A common practice that I have seen and used is to copy a database file member to a backup file at a critical point in a job stream, perhaps before updates take place or the file is cleared.

CPYF FROMFILE(SOMEFILE) +
   TOFILE(SOMEFILEBK) +
   MBROPT(*REPLACE)
MONMSG MSGID(CPF2817) +
   EXEC(CLRPFM SOMEFILEBK)  /* SOMEFILE IS EMPTY */

In this example, a program runs that updates file SOMEFILE. File SOMEFILEBK contains the data of SOMEFILE as it was before the updates took place. If there are questions about the data, a user can query SOMEFILEBK.

The CPYF approach is fine, but limited in that only one backup is retained. Sometimes it is good to have the last several versions of a file. And that is why I wrote ARCHIVE. It provides an easy way to keep one or more versions of a database file.

The ARCHIVE utility consists of two objects: a command named ARCHIVE and a CL program named ARCHIVECL. The ARCHIVE command has the following parameters.

By default, you backup the first member of a file into a new member of the archive file. The last parameter tells the name of the new archive member. You can backup to a certain member. For example, you might backup to member B4ME, before month-end, during month-end processing. But if you use the default value, *GEN, the ARCHIVE utility will create a member name. It looks like garbage, but the file-member comment tells the name and library of the saved file and the date and time when it was archived.

Suppose you have a transaction file named XACTS that you want to back up during a batch run. First, create the archive file.

CRTDUPOBJ OBJ(XACTS) +
   FROMLIB(SOMELIB) +
   OBJTYPE(*FILE) +
   TOLIB(*FROMLIB) +
   NEWOBJ(XACTSARC)

Second, tell the archive file how many backups it is to hold. In this example, I assume 35 backups.

CHGPF FILE(SOMELIB/XACTSARC) MAXMBRS(35)

Last, add the archive command to your application at the appropriate place.

ARCHIVE  FILE(SOMEFILE) ARCHIVE(SOMEFILEBK)

Now when you arrive at work only to find that the nightly accounts receivable update messed up the balance that customer XYZ owes your company, you’ll be able to go through the archives for clues.