Join Network
Categories
APIs by Example: Restore from Application API and Exit Program
Article ID: 56846
Posted June 26th, 2008
In the preceding installment of APIs by Example ("APIs by Example: The Save to Application API and Exit Program," May 22, 2008), you learned how to save objects to a stream file by using the new Save Object to Stream File (SAVOBJSTMF) command that I presented in that article. If you have installed and tested the SAVOBJSTMF command, you are probably the happy owner of a stream file containing the save records storing the object(s) that you have saved. This is all very fine, though not very useful unless you have an option to reverse the process and restore the saved object(s) from the stream file.
To fulfill that objective, I've written the Restore Object from Stream File (RSTOBJSTMF) command, which incidentally also helps me demonstrate the use of the Restore from Application (QaneRsta) API and the related Restore from Application exit program. Understanding how the involved APIs and exit programs work and interact provides you with the option of adapting or changing the save and restore utilities I present here, to meet your own requirements.
The QaneRsta API has the following parameter list, which is identical to the Save to Application (QaneSava) API's parameter list, except for the fact that all save operation references have been replaced with restore operation references:
1 Qualified user space name Input Char(20) 2 User space format name Input Char(8) 3 Status format name Input Char(8) 4 Status information Output Char(*) 5 Length of status information Input Binary(4) 6 Error code I/O Char(*)
As I explained last time, the first parameter specifies the name and library of a user space that must contain all the control information for the restore operation. This restore control information is formatted as a data structure named SVRS0100, which includes information such as the restore command or API to be used to process the save records, as well as the restore command parameters or restore API parameter key structure. There's also a parameter called Application data, and you can use it to communicate between the program calling the QaneRsta API and the exit program called during the restore process.
The name and library of the exit program to be called during the restore process to provide the restore records is also defined by the SVRS0100 data structure. The name of the parameter structure is submitted as the second QaneRsta API parameter. Here's the IBM Info Center's description of all the information available through this parameter:
Offset Type Field
Dec Hex
0 0 BINARY(4) Length of structure
4 4 BINARY(4) Offset to restore command parameters
8 8 BINARY(4) Length of restore command parameters
12 C BINARY(4) Offset to application data
16 10 BINARY(4) Length of application data
20 14 BINARY(4) Restore command type
24 18 CHAR(10) Exit program name
34 22 CHAR(10) Exit program library
44 2C CHAR(8) Target release
CHAR(*) Restore command parameters
CHAR(*) Application data
The restore commands and APIs that the QaneRsta API supports are defined by the following list, which shows all available options at release V5R4 for the Restore command type subfield in the preceding structure:
1 Restore (RST) command 2 Restore Object (RSTOBJ) command 3 Restore Document Library Object (RSTDLO) command 4 Restore Library (RSTLIB) command 5 Restore Object (QsrRestore) API 6 Restore Object List (QSRRSTO) API 7 Restore System Information (RSTSYSINF) command
The QanaRsta API's third, fourth, and fifth parameters define the name of the status data structure, the status data structure itself, and the status data structure length, respectively. The status data structure is named SRST0100, is identical to the equivalent QaneSava parameter, and provides a communication area between the QaneRsta API and its caller. For release V5R4, the following information is accessible through the status data structure:
Offset Type Field Dec Hex 0 0 BINARY(4) Bytes returned 4 4 BINARY(4) Bytes available 8 8 BINARY(4) Transfer time 12 C BINARY(4) Transfer block size 16 10 BINARY(4) Transfer block multiplier 20 14 BINARY(4) Last block size 24 18 CHAR(10) User space library used 34 22 CHAR(2) Reserved 36 24 BINARY(4) Decimal transfer time
The final sixth parameter is the standard API error code data structure. Similar to the QaneSava API, the QaneRsta API has many restrictions, constraints, and subtleties to consider when dealing with this API. For example, you can restore objects only if these were previously saved by the QaneSava API and only if the objects were saved from the current or an earlier release of the operating system.
Additionally, because the restore command is processed from within a prestart job, you cannot rely on adopted authority to execute the specified restore command. One way to provide sufficient authority to the prestart job is to use adopted authority to swap user profiles before calling the QaneRsta API. At the end of this article, I include a link to the IBM V5R4 version of the QaneRsta API documentation. Be sure to check out all the details.
Until now, practically everything I've explained about the restore process has been a mirror image of my article that explains the QaneSava API and exit program. And, as you will see, the similarities continue when it comes to the documentation of the Restore from Application exit program.
Following a successful call to the QaneRsta API, the Restore from Application exit program is called during any of the following four operation events:
- Start of restore process. The exit program must prepare for the restore record transfer -- for example, open the stream file, in which the records are stored.
- Transfer of a block of restore records. The exit program returns a block of restore records as well as the length of the data block. This step must be repeated until all restore records have been returned.
- End of restore process. The exit program at this point must terminate the process of returning the restore records, and, for example, close the stream file.
- Abnormal end of save process. If anything goes wrong in the course of the restore process, the exit program is called one final time to allow it to perform cleanup and termination activities -- for example, close the restore records stream file.
The exit program has the following required parameter group:
1 Operation type Input Binary(4) 2 Operation status Output Binary(4) 3 Restore data Input PTR(SPP) 4 Length of restore data Input Binary(4) 5 Restore bytes written Output Binary(4) 6 Qualified user space name Input Char(20) 7 User space format name Input Char(8)
The Operation type parameter specifies which of the preceding four events caused the exit program to be called, and the exit program returns the outcome of the processing performed in the Operation status parameter, subsequently causing the restore process either to continue or terminate.
The third parameter is a space pointer to a block of restore records. This parameter is of course only used by the restore process when the operation type is 2. The Length of restore data parameter ensures that the restore process addresses only the restore data provided by the restore exit program. The sixth parameter is the qualified name of the user space specified as input to the QaneRsta API, and it thereby enables the exit program to share and exchange information with the API caller via the specified user space. The seventh parameter declares the format of the data in the user space.
Putting all this information to work provides you with the knowledge and components necessary to build the RSTOBJSTMF command, and once the command is completed, here's what you'll see when you prompt the RSTOBJSTMF command:
Restore Obj from Stream File (RSTOBJSTMF)
Type choices, press Enter.
Objects . . . . . . . . . . . . Name, generic*, *ALL
+ for more values
Library . . . . . . . . . . . . Name
Object types . . . . . . . . . . *ALL
+ for more values
Stream file . . . . . . . . . .
Additional Parameters
Option . . . . . . . . . . . . . *ALL *ALL, *NEW, *OLD, *FREE
Data base member option . . . . *MATCH *MATCH, *ALL, *NEW, *OLD
Allow object differences . . . . *NONE *NONE, *ALL, *AUTL...
+ for more values
Restore to library . . . . . . . *SAVLIB Name, *SAVLIB
Output . . . . . . . . . . . . . *NONE *NONE, *PRINT
|
The Stream file parameter specifies the path to an existing stream file containing the restore records previously obtained by the SAVOBJSTMF command or a similar facility based on the Save to Application API and exit program. As always, a help text panel group is included with the command to explain all details and parameters. Apart from the Stream file parameter, all other parameters work the same as they do in the Restore Object (RSTOBJ) command.
Please note that if you specify the OUTPUT(*PRINT) keyword for the RSTOBJSTMF command, you can locate the produced spooled file by using the command:
WRKSPLF SELECT(*CURRENT *ALL *ALL *ALL *ALL QPSRLDSP)
Because the restore process runs in a separate prestart job, the spooled file is created under the QPRTJOB special job name and is consequently not owned by the job running the RSTOBJSTMF command, thus requiring extra effort to locate the printed output.
And because both the save and restore process is performed through a prestart job when you run the SAVOBJSTMF and RSTOBJSTMF commands, you could find yourself in a situation in which you'd want to locate that job. One way to achieve that objective is to use the Display Object Description (DSPOBJD) command against the saved and restored objects to acquire the information necessary to look up the prestart job in question. For a saved or restored object, run the following command:
DSPOBJD OBJ(QGPL/ABC) OBJTYPE(*FILE) DETAIL(*FULL)
Page down until you get to the last page with the object save/restore information:
Display Object Description - Full
Library 1 of 1
Object . . . . . . . : ABC Attribute . . . . . : PF
Library . . . . . : QGPL Owner . . . . . . . : CARSTEN
Library ASP device . : *SYSBAS Library ASP group . : *SYSBAS
Type . . . . . . . . : *FILE Primary group . . . : *NONE
Save/Restore information:
Save date/time . . . . . . . . . . . : 22-06-08 10:27:02
Restore date/time . . . . . . . . . : 17-05-08 13:22:16
Save command . . . . . . . . . . . . : SAVOBJ
Device type . . . . . . . . . . . . : Save file
Save file . . . . . . . . . . . . . : QTEMP/QANE738456
|
Notice the six digits appended to the save file name QTEMP/QANEnnnnnn. This is the job number for the prestart job named QANEAGNT that performed the save or restore operation against the specified object. Using that job number as well as user profile QUSER with the Work with Job (WRKJOB) command, brings up the Work with Job panel for the save or restore job:
WRKJOB JOB(738456/QUSER/QANEAGNT)
From this panel, you can, for example, look up the job log to examine the messages issued as part of the save or restore process to verify the successful execution or investigate any problems encountered.
Previously published related articles:
APIs by Example: The Save to Application API and Exit Program (May 22, 2008)
http://systeminetwork.com/article/apis-example-save-application-api-and-exit-program
This article demonstrates the following Backup and Recovery API and Exit Program:
Restore from Application (QaneRsta) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/QaneRsta.htm
Restore from Application Exit Program:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/XANERSTA.htm
Backup and Recovery APIs V5R4:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/apis/back1.htm
You can retrieve the source code for this API example from:
http://www.pentontech.com/IBMContent/Documents/article/56846_628_RstObjStmf.zip.
Bookmark/Search this post with:
- Login to post comments
- Printer-friendly version