API Corner: Backup APIs
November 16, 2005 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:
- Backup History
- Backup Detail
- 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.
