There is a very nice feature that IBM i provides which allows a program to be called from within a Save File which is not well documented. Originally we used the same functionality from Tape and Optical to allow us to run installation programs so that we could restore items to the system based on user input. However the days of Tape and Optical being used to ship products are long gone with users now preferring to use electronic methods to download the products meaning they want Save Files.
Our HA4i and JT4i products have seen intermediate updates shipped as save files for a long time because we tend to ship new features and updates as quickly as possible. Once there are sufficient updates we will roll them all into a PTF which is a cumulative collection of all of the updates we have for the product. Because these updates are not always as simple as restoring new objects we need to ship additional instructions that have to be carried out after the restore has completed to copy data into new files or copy new message ID into message files etc. This is OK as long as there are only a few operations to carry out after the restore but with more complex changes it makes sense to provide programs that automatically carry them out without the users having to get involved.
The LODRUN command is perfect for this and we have integrated the functionality into our automated update process that now ship with the products. However the documentation for the QINSTAPP program needs updating to show how you can use this functionality which is why we are creating this post. Our users no longer have long instruction list about how to install the new feature, all they need to do is run the LODRUN command against the update file.
The documentation for the QINSTAPP can be found here You will see that the example shows only a single parameter is passed to the program, it actually states that Device is the only parameter allowed! This is incorrect when *SAVF is the object that holds the saved objects. You actually need 2 parameters to be declared, the second parameter will hold the name of the save file. We opened a PMR with IBM stating the documentation is incorrect but they said its not something they can fix and we need to comment to the documentation team (which we have but not sure if that will go anywhere?). So we decided to write a Blog post to show how to implement QINSTAPP with a *SAVF.
First we need to develop the QINSTAPP program, in the example we are just going to restore the objects to the library, but you can do a lot more such as call programs that you have just restored or display menus and panel groups to collect information and then run programs to carry out some additional processes after the objects are restored. Here is the code we created for the test.
PGM PARM(&DEV &SAVF) DCL VAR(&DEV) TYPE(CHAR) LEN(10) DCL VAR(&SAVF) TYPE(CHAR) LEN(20) DCL VAR(&FILE) TYPE(*CHAR) LEN(10)CHGVAR VAR(&FILE) VALUE(%SST(&SAVF 1 10))RSTOBJ OBJ(*ALL) SAVLIB(CHLIB) DEV(*SAVF) OBJTYPE(*ALL) SAVF(&FILE) + MBROPT(*ALL) ALWOBJDIF(*ALL)MONMSG MSGID(CPF3773)ENDPGM
Its a very simple example but its showing how we use the second parameter to get the save file name so we can use it to restore the objects. You could go further and turn the save file parameter into a qualified name but for our purposes this is just fine. Once we created the program all we need to do now is save it along with the other objects from CHLIB (We are using it as the saved object library so the QINSTAPP program had to be saved from there). Our save file only had one additional object in it as its only a test. DSPSAVF shows the following content.
Display Saved Objects
Library saved . . . . . . . : CHLIB
Type Options, press Enter.
5=Display
Opt Object Type Attribute Owner Size (K) Data
ABSTIMETST *PGM CLE CHRISH 76 YES
QINSTAPP *PGM CLP CHRISH 112 YES
To test the functionality simply use the LODRUN command as follows.
LODRUN DEV(*SAVF) SAVF(LRTEST)
When we check the joblog we can see the following.
LODRUN DEV(*SAVF) SAVF(LRTEST)
1 objects restored from CHLIB to QTEMP.
2 objects restored from CHLIB to CHLIB.
The first action is the QINSTAPP program being restored to QTEMP, it is then invoked automatically and the objects are restored to CHLIB.
There are lots of uses for the LODRUN technology such as being able to restore objects to a library which is determined by the user at run time or maybe doing a check on the system for something that would determine if the objects can be safely restored etc. The possibilities are endless and its something many IBM i users never knew about! So now you do..
Chris…