API Corner: Backup APIs

by Shannon O'Donnell

The code for this article is available for download.

In this issue of API Corner, I am going to show you how to use some of the Backup APIs, which you can then use to programmatically determine when certain objects, such as libraries and files, were last backed up. Specifically, I will cover the Backup History, Backup Detail, and the Backup Schedule APIs.

The Backup APIs

The Backup and Recovery APIs make working with backup information much easier than trying to use *OUTFILES from such IBM commands as DSPOBJD (Display Object Description). When you use the backup APIs, you can do away with all that *OUTFILE nonsense and in the process gain much tighter control over your system.

For this article, I've created a menu program, BACKUPMC1, which has three options:

1. Backup History
2. Backup Detail
3. Backup Schedule

The Backup History option uses the QEZRTBKH (Retrieve Backup History) API to retrieve information about the status and history of the entire system.

The Backup Detail option uses the QEZRTBKD (Retrieve Backup Detail) API to retrieve information about a specific library or QDLS Folder.

The Backup Schedule API uses the QEZRTBKS (Retrieve Backup Schedule) API to retrieve the system backup schedule.

QEZRTBKH

Your programs can use the Retrieve Backup History API can be used by your program to retrieve the system backup history. Of course, you can also use the DSPBCKSTS (Display Backup Status) command to push this same information to the screen or to a printer file, but that is not very useful if you need to have your program make some decisions about what to do about something based on when the system was last backed up. The much better alternative is to use the QEZRTBKH API.

The sample program included with this article that uses this API is named BACKUPR2. To use the QEZRTBKH API you only need to pass it a receiver variable to store the backup history in, a variable that defines the length of the receiver variable, the format name of the API and the standard Error Data Structure I've been using in all the other programs in the API Corner series.

* Retrieve Backup History
C                   Call      'QEZRTBKH'
C                   Parm      *Blanks       RcvrVar
C                   Parm      261           RcvrVarLen
C                   Parm      'RBKH0100'    Format
C                   Parm                    dsEc
 *

The format of the returned information is determined by the format you choose for this API. The RBKH0100 Format will return the least amount of information, while the RBKH0200 Format will return more. For our purposes, we will use the RBKH0100 Format:

D RBKH0100        DS
D  BytAvl                       10i 0
D  BytRtn                       10i 0
D  LDatAULib                     7a
D  LTimAULib                     6a
D  TapSetAULib                   4a
D  LDatAULibC                    7a
D  LTimAULibC                    6a
D  TapSetAULibC                  4a
D  LDatLbLst                     7a
D  LTimLbLst                     6a
D  TapSetLbLst                   4a
D  LDatLbLstC                    7a
D  LTimLbLstC                    6a
D  TapSetLbLstC                  4a
D  LDatFlr                       7a
D  LTimFlr                       6a
D  TapSetFlr                     4a
D  LDatFlrC                      7a
D  LTimFlrC                      6a
D  TapSetFlrC                    4a
D  LDatFlrLs                     7a
D  LTimFlrLs                     6a
D  TapSetFlrLs                   4a
D  LDatSecDta                    7a
D  LTimSecDta                    6a
D  TapSetSecDta                  4a
D  LDatCfgDta                    7a
D  LTimCfgDta                    6a
D  TapSetCfgDta                  4a
D  LDatCalDta                    7a
D  LTimCalDta                    6a
D  TapSetCalDta                  4a
D  LDatMalDta                    7a
D  LTimMalDta                    6a
D  TapSetMalDta                  4a
D  LDatUsrDir                    7a
D  LTimUsrDir                    6a
D  TapSetUsrDir                  4a
D  LDatUsrDirC                   7a
D  LTimUsrDirC                   6a
D  TapSetUsrDirC                 4a
D  Rsvd21                       21a

There is a lot of information in the format, but most of it repeats, which makes it a lot easier to work with. When you call the API, the backup history will be returned into the receiver variable. You can use this returned information in whatever way best fits your needs, such as kicking off another system backup only when a certain amount of time has passed since the last backup. The rest of the sample program is fairly straightforward, pushing the returned information to the display screen.

QEZRTBKD

Use the Retrieve Backup Detail API to retrieve the system backup history. This API is similar to the information you can get by using the DSPOBJD, DSPFD, DSPLIB commands, but again, it is much easier to use data returned from the API directly into your RPG program than it is to try to read it off of a printed report or an *OUTFILE.

The sample program included with this article that uses this API is named BACKUPR1. To use the QEZRTBKD API, pass a receiver variable to store the backup history in, a variable that defines the length of the receiver variable, the name of the object you want to check the backup history of, the length of that object name, the format name of the API, the type of object you want to check and the standard Error Data Structure.

C                   Call      'QEZRTBKD'
C                   Parm      *Blanks       RcvrVar
C                   Parm      84            RcvrVarLen
C                   Parm      InObj         Objname
C                   Parm      LenObjName    ObjNameLen
C                   Parm      'RBKD0100'    Format
C                   Parm                    ObjType
C                   Parm                    dsEc

Since there is only a single format available for this API, you don't need to decide which one to use. Here is the layout for the returned for format RBKD0100:

D RBKD0100        DS
D  BytAvl                       10i 0
D  BytRtn                       10i 0
D  LstSavDat                     7a
D  LstSavTim                     6a
D  ObjDesc                      50a
D  ChgSncLstBk                   1a

The information returned is fairly minimal, but again, if you need to make a decision in a program based on some backup information, then it's very nice and convenient to be able to retrieve that data into a variable in your RPG program.

QEZRTBKS

The Retrieve Backup Schedule API can be used by your program to retrieve the system backup schedule. The information returned in this API is exactly the same as the information you can get by using the Change Backup Schedule option from the system BACKUP (Go Backup) menu. Again, however, it is much more convenient to be able to retrieve this information into a program variable than it is to try to parse it from a display screen.

The sample program included with this article that uses this API is named BACKUPR3. To use the QEZRTBKS API, you need to pass it a receiver variable to store the backup history in, a variable that defines the length of the receiver variable, the format name of the API, and the standard Error Data Structure.

* Retrieve Backup History
                   Call      'QEZRTBKS'
                   Parm      *Blanks       RcvrVar
                   Parm      261           RcvrVarLen
                   Parm      'RBKS0100'    Format
                   Parm                    dsEc

Since there is only a single format available for this API, you don't need to decide which one to use. Here is the layout for the returned for format RBKS0100:

D RBKS0100        DS
D  BytAvl                       10i 0
D  BytRtn                       10i 0
D  RHOUR                        10i 0
D  ROCCUR                       10i 0
D  RRUN                          1a
D  RSUN                          1a
D  RSUNT                         6a
D  RMON                          1a
D  RMONT                         6a
D  RTUE                          1a
D  RTUET                         6a
D  RWED                          1a
D  RWEDT                         6a
D  RTHU                          1a
D  RTHUT                         6a
D  RFRI                          1a
D  RFRIT                         6a
D  RSAT                          1a
D  RSATT                         6a

You can use the returned information from this API along with the QEZCHBKS (Change Backup Schedule) API to programmatically change the system backup schedule based on some user defined criteria.

Backup Information at Your Fingertips!

The Backup APIs discussed in this article and included as downloadable code are only the tip of the iceberg as far as Backup and Recovery APIs go. There is a veritable cornucopia stuffed with Backup and Recovery functions that you can use from within your applications, which until now you probably thought were only available by using IBM-supplied commands. Check out the online IBM Information Center for more details.