It's easily done by using the List Objects and Save Object List APIs.
I recently received a note from Ray J. that included the following:
"I save and restore physical files from one system to another. The libraries contain both physical and logical files. I would like to save and restore only the physical files. However, using the omit parameter on the SAVOBJ commands only allows a few hundred omits, and I have more than 300 omits and more than 1000 files. The best I have come up with so far is to display the object description of all the *FILES, run a query, and output a file containing the names of only *FILES with attribute PF. Then read that file and save each object one at a time. That seems like a lot of overhead. Any other suggestions?"
As you might guess, I do have a suggestion. As Ray correctly points out, CL command definitions have a limit as to the size of a list parameter. That limit is 300 entries, meaning you cannot use a command such as SAVOBJ and then specify more than 300 objects to omit and/or more than 300 objects to include—both of which Ray would need to exceed. The Save Object List (QSRSAVO), previously introduced in the API Corner article "Saving Individual User Profiles," does not have this specific limitation. There is naturally a limit, but within the context of Ray's note, that limit is in excess of 800,000 objects, which is more than the number of objects you can have in a library anyway. So this article will look at how to use the Save Object List API in order to save thousands of specific file objects, and nothing else, within a library.
A second part of his note discussed how to determine the names of the files with the attribute of PF (which we'll also need for the QSRSAVO API list of objects to save). His approach of using the Display Object Description (DSPOBJD) command to create an outfile containing all file objects and then querying this outfile for those files with an attribute of PF would certainly fulfill this need, but, as this is the API Corner, we'll use the List Objects API (QUSLOBJ) instead.
Below is the source for program SavPFs (Save Physical Files).
h dftactgrp(*no)
d SavPFs pr extpgm('SAVPFS')
d Lib_In 10a const
d SavF_In 10a const
d SavPFs pi
d Lib_In 10a const
d SavF_In 10a const
*******************************************************
d ChgUsrSpcA pr extpgm('QUSCUSAT')
d RtnUsrSpcLib 10a
d QualUsrSpcN 20a const
d UsrSpcAttrs 1a const options(*varsize)
d ErrCde likeds(QUSEC)
d CrtUsrSpc pr extpgm('QUSCRTUS')
d QualUsrSpcN 20a const
d XAttr 10a const
d IntSize 10i 0 const
d IntValue 1a const
d PubAut 10a const
d TxtDesc 50a const
d ReplaceOpt 10a const options(*nopass)
d ErrCde likeds(QUSEC) options(*nopass)
d Domain 10a const options(*nopass)
d TfrSize 10i 0 const options(*nopass)
d OptSpcAlgn 1a const options(*nopass)
d FinishEntry pr
d FmtSavList pr
d LstObj pr extpgm('QUSLOBJ')
d QualUsrSpcN 20a const
d Format 8a const
d QualObjs 20a const
d ObjType 10a const
d ErrCde likeds(QUSEC) options(*nopass)
d AutCtl const likeds(QUSLAC)
d options(*nopass)
d SelCtl const likeds(QUSLSC)
d options(*nopass)
d ASPCtl const likeds(QUSLASPC)
d options(*nopass)
d RtvUsrSpcPtr pr extpgm('QUSPTRUS')
d QualUsrSpcN 20a const
d UsrSpcPtr *
d ErrCde likeds(QUSEC) options(*nopass)
d SavObjLst pr extpgm('QSRSAVO')
d QualUsrSpcN 20a const
d ErrCde likeds(QUSEC)
d SndAPIMsg pr
d SndMsg pr
d MsgType 10a const
d MsgID 7a const
d MsgDta 256a const options(*varsize)
d LenMsgDta 10i 0 const
d SndPgmMsg pr extpgm('QMHSNDPM')
d MsgID 7a const
d QualMsgF 20a const
d MsgDta 256a const options(*varsize)
d LenMsgDta 10i 0 const
d MsgType 10a const
d CSE 10a const
d CSECtr 10i 0 const
d MsgKey 4a
d ErrCde likeds(QUSEC)
d LenCSE 10i 0 const options(*nopass)
d CSEQual 20a const options(*nopass)
d DspWait 10i 0 const options(*nopass)
d CSEType 10a const options(*nopass)
d CCSID 10i 0 const options(*nopass)
*******************************************************
d ObjLHdrPtr s *
d ObjLHdr ds likeds(QUSH0100)
d based(ObjLHdrPtr)
d ObjLDtlPtr s *
d ObjLDtl ds likeds(QUSL020002)
d based(ObjLDtlPtr)
d SavHdrPtr s *
d SavHdr ds likeds(QSRUS)
d based(SavHdrPtr)
d SavRcdPtr s *
d SavRcd ds likeds(QSRR)
d based(SavRcdPtr)
d ObjHdrPtr s *
d ObjHdr ds qualified
d based(ObjHdrPtr)
d Nbr 10i 0
d ObjEntryPtr s *
d ObjEntry ds qualified
d based(ObjEntryPtr)
d Name 10a
d Type 10a
d LibEntryPtr s *
d LibEntry ds qualified
d based(LibEntryPtr)
d Nbr 10i 0
d Library 10a
d DevEntryPtr s *
d DevEntry ds qualified
d based(DevEntryPtr)
d Nbr 10i 0
d Device 10a
d UsrSpcAttrs ds qualified
d NbrAttrs 10i 0 inz(1)
d AutoXtndKey 10i 0 inz(3)
d LenKeyVal 10i 0 inz(1)
d AutoXtndYes 1a inz('1')
d ErrCde ds qualified
d Hdr likeds(QUSEC)
d MsgDta 256a
*******************************************************
d AlignOn s 10i 0 inz(4)
d EntriesToSave s 10i 0
d LstObjSpc s 20a inz('PFLIST QTEMP')
d MsgKey s 4a
d MsgTxt s 256a
d RtnUsrSpcLib s 10a
d SavFEntryPtr s *
d SavFEntry s 20a based(SavFEntryPtr)
d SavLFEntryPtr s *
d SavLFEntry s 1a based(SavLFEntryPtr)
d SavObjSpc s 20a inz('SAVLIST QTEMP')
d X s 10i 0
*******************************************************
/copy qsysinc/qrpglesrc,qsr
/copy qsysinc/qrpglesrc,qusec
/copy qsysinc/qrpglesrc,qusgen
/copy qsysinc/qrpglesrc,quslobj
*******************************************************
/free
for X = 1 to ObjLHdr.QUSNbrLE;
if X = 1;
ObjLDtlPtr = ObjLHdrPtr + ObjLHdr.QUSOLD;
ObjHdrPtr = SavRcdPtr + %size(SavRcd);
ObjHdr.Nbr = 0;
else;
ObjLDtlPtr += ObjLHdr.QUSSEE;
endif;
if ObjLDtl.QUSEOA = 'PF';
if ObjHdr.Nbr = 0;
ObjEntryPtr = ObjHdrPtr + %size(ObjHdr);
else;
ObjEntryPtr += %size(ObjEntry);
endif;
ObjEntry.Name = ObjLDtl.QUSObjNU00;
ObjEntry.Type = '*FILE';
ObjHdr.Nbr += 1;
endif;
endfor;
if ObjHdr.Nbr = 0;
MsgTxt = 'No PFs found in library';
SndMsg('*COMP' :'CPF9897'
:MsgTxt :%len(%trimr(MsgTxt)));
else;
// Set Library Information
SavRcd.QSRKNbr = 1;
SavRcd.QSRDL = (%size(ObjHdr) +
(%size(ObjEntry) * ObjHdr.Nbr));
FinishEntry();
SavObjLst(SavObjSpc :ErrCde);
if ErrCde.Hdr.QUSBAvl <> 0;
MsgTxt = 'Error saving objects: ' +
ErrCde.Hdr.QUSEI;
SndMsg('*DIAG' :'CPF9897'
:MsgTxt :%len(%trimr(MsgTxt)));
SndAPIMsg();
endif;
endif;
*inlr = *on;
return;
// ***************************************************
begsr *inzsr;
QUSBPrv = 0;
ErrCde.Hdr.QUSBPrv = %size(ErrCde);
RtvUsrSpcPtr(LstObjSpc :ObjLHdrPtr :ErrCde);
select;
when ErrCde.Hdr.QUSBAvl = 0;
// All is OK
when ErrCde.Hdr.QUSEI = 'CPF9801';
// UsrSpc not found, so create it
CrtUsrSpc(LstObjSpc :'PFList' :4096
:x'00' :'*ALL' :'Used by SavPFs'
:'*YES' :QUSEC :'*DEFAULT' :0 :'1');
RtvUsrSpcPtr(LstObjSpc :ObjLHdrPtr :QUSEC);
other;
// Serious problem, so report it
MsgTxt = 'Error accessing ObjLHdrPtr: ' +
ErrCde.Hdr.QUSEI;
SndMsg('*DIAG' :'CPF9897'
:MsgTxt :%len(%trimr(MsgTxt)));
SndAPIMsg();
endsl;
LstObj(LstObjSpc :'OBJL0200'
:('*ALL ' + Lib_In) :'*FILE' :ErrCde);
select;
when ErrCde.Hdr.QUSBAvl <> 0;
MsgTxt = 'Error accessing file info: ' +
ErrCde.Hdr.QUSEI;
SndMsg('*DIAG' :'CPF9897'
:MsgTxt :%len(%trimr(MsgTxt)));
SndAPIMsg();
when ObjLHdr.QUSIS = 'P';
MsgTxt = 'Only partial file info returned';
SndMsg('*DIAG' :'CPF9897'
:MsgTxt :%len(%trimr(MsgTxt)));
when ObjLHdr.QUSNbrLE = 0;
MsgTxt = 'No files found in ' + Lib_In;
SndMsg('*ESCAPE' :'CPF9897'
:MsgTxt :%len(%trimr(MsgTxt)));
endsl;
RtvUsrSpcPtr(SavObjSpc :SavHdrPtr :ErrCde);
select;
when ErrCde.Hdr.QUSBAvl = 0;
// All is OK
when ErrCde.Hdr.QUSEI = 'CPF9801';
// UsrSpc not found, so create it
CrtUsrSpc(SavObjSpc :'SaveList' :4096
:x'00' :'*ALL' :'Used by SavPFs'
:'*YES' :QUSEC :'*DEFAULT' :0 :'1');
ChgUsrSpcA(RtnUsrSpcLib :SavObjSpc
:UsrSpcAttrs :QUSEC);
RtvUsrSpcPtr(SavObjSpc :SavHdrPtr :QUSEC);
other;
// Serious problem, so report it
MsgTxt = 'Error accessing SavHdrPtr: ' +
ErrCde.Hdr.QUSEI;
SndMsg('*DIAG' :'CPF9897'
:MsgTxt :%len(%trimr(MsgTxt)));
SndAPIMsg();
endsl;
FmtSavList();
endsr;
/end-free
*******************************************************
p FmtSavList b
d FmtSavList pi
/free
SavHdr.QSRNbrR = 0;
SavRcdPtr = SavHdrPtr + %size(SavHdr);
// Set Library Information
SavRcd.QSRKNbr = 2;
SavRcd.QSRDL = %size(LibEntry);
LibEntryPtr = SavRcdPtr + %size(SavRcd);
LibEntry.Nbr = 1;
LibEntry.Library = Lib_In;
FinishEntry();
// Set Device Information
SavRcd.QSRKNbr = 3;
SavRcd.QSRDL = %size(DevEntry);
DevEntryPtr = SavRcdPtr + %size(SavRcd);
DevEntry.Nbr = 1;
DevEntry.Device = '*SAVF';
FinishEntry();
// Set SavF Information
SavRcd.QSRKNbr = 4;
SavRcd.QSRDL = %size(SavFEntry);
SavFEntryPtr = SavRcdPtr + %size(SavRcd);
SavFEntry = SavF_In + '*LIBL';
FinishEntry();
// Set Logical File Information
SavRcd.QSRKNbr = 18;
SavRcd.QSRDL = %size(SavLFEntry);
SavLFEntryPtr = SavRcdPtr + %size(SavRcd);
SavLFEntry = '0';
FinishEntry();
/end-free
p FmtSavList e
*******************************************************
p FinishEntry b
d FinishEntry pi
/free
if %rem(SavRcd.QSRDL :AlignOn) <> 0;
SavRcd.QSRRL00 = %size(SavRcd) + SavRcd.QSRDL +
(AlignOn - %rem(SavRcd.QSRDL :AlignOn));
else;
SavRcd.QSRRL00 = %size(SavRcd) + SavRcd.QSRDL;
endif;
SavHdr.QSRNbrR += 1;
SavRcdPtr += SavRcd.QSRRL00;
/end-free
p FinishEntry e
*******************************************************
p SndMsg b
d SndMsg pi
d MsgType 10a const
d MsgID 7a const
d MsgDta 256a const options(*varsize)
d LenMsgDta 10i 0 const
/free
SndPgmMsg(MsgID :'QCPFMSG *LIBL' :MsgDta :LenMsgDta
:MsgType :'*PGMBDY' :1 :MsgKey :QUSEC);
/end-free
p SndMsg e
*******************************************************
p SndAPIMsg b
d SndAPIMsg pi
d LenMsgDta s 10i 0
/free
select;
when ErrCde.Hdr.QUSBAvl <= 16;
LenMsgDta = 0;
when ErrCde.Hdr.QUSBAvl > %size(ErrCde);
LenMsgDta = %size(ErrCde.MsgDta);
other;
LenMsgDta = ErrCde.Hdr.QUSBAvl - %size(ErrCde.Hdr);
endsl;
SndPgmMsg(ErrCde.Hdr.QUSEI :'QCPFMSG *LIBL'
:ErrCde.MsgDta :LenMsgDta
:'*ESCAPE' :'*PGMBDY' :1 :MsgKey :QUSEC);
/end-free
p SndAPIMsg e
The SavPFs program defines two input parameters:
- Lib_In identifies the library from which physical files are to be saved.
- SavF_In identifies the save file to save the physical files to. Note that the caller of SavPFs is responsible for creating this save file and for making sure the library containing the save file is in an appropriate position within the jobs library list.
Upon entry to SavPFs, the *inzsr subroutine is run to set the environment for the main processing of the program. In the *inzsr we:
- Initialize the Bytes provided field of the QUSEC error code structure to 0. The QUSEC error code structure is used on API calls when the program has no error recovery in place (it must be a really bizarre error), so an exception will be sent to the caller.
- Initialize the Bytes provided field of the ErrCde error code structure to 272, the size of the ErrCde structure. The ErrCde error code structure is used on API calls when some form of error recovery is in place.
- Attempt to access the user space QTEMP/PFLIST using the ErrCde error code structure. If this is the initial call of SavPFs in the job, the user space will not exist, so it's created.
- Call the List Objects (QUSLOBJ) API asking that a list of *ALL *FILE objects in the library identified by Lib_In be returned in the user space QTEMP/PFLIST using format OBJL0200. Format OBJL0200 is one of seven formats supported by the QUSLOBJ API and is the fastest of the formats that returns the extended attribute of the object being returned. The extended attribute is where we can determine if the *FILE is a PF, LF, PRTF, DSPF, etc. Recall that Ray is only interested in PFs. A few checks are then made on this returned list of *FILE objects. They are:
- Was there an error in returning the list? If so, a *DIAG message is sent, followed by an *ESCAPE message identifying the error.
- Was only a partial list of *FILE objects returned? If so, a *DIAG message is sent and the program continues. I have to admit that this is one place where the DSPOBJD approach suggested by Ray does have a slight advantage. The DSPOBJD outfile can return as many *FILE objects as might be found in the library. The QUSLOBJ API, on the other hand, can return only the number of *FILE objects that will fit in one user space and, unlike many List APIs, does not support a continuation capability to get the "next" set of objects. This effectively limits QUSLOBJ to returning, when format OBJL0200 is used, around 150,000 *FILE entries. If you have a library with more than 150,000 *FILEs and want to use an API to access all of them, please send me a note. That would give me a wonderful opportunity to write about the Open List of Objects API (QGYOLOBJ), which does not have this limitation.
- Were no *FILE objects found in the library? If so, an *ESCAPE message is sent as there is nothing to save
- Attempt to access the user space QTEMP/SAVLIST using the ErrCde error code structure. If this is the initial call of SavPFs in the job, the user space will not exist, so it's created and then changed to be auto-extendable. This user space is actually used as an input to the QSRSAVO API providing the list of physical files to be saved. As we don't, at this time, know how many physical files there might be in the library, making the user space auto-extendable allows us to later write as many file entries as we may need without having to worry about running out of room (and not having to pre-allocate a user space of maximum size when we don't need a user space that large).
- Call the procedure FmtSavList() to format various controls related to the running of the QSRSAVO API.
The FmtSavList() procedure stores QSRSAVO-related control information into the user space QTEMP/SAVLIST. The majority of the work being done (the setting of library, device, and save file information, calling the FinishEntry() procedure, etc.) was covered in the previous article "Saving Individual User Profiles" and will not be covered again at this time.
The one new item in FmtSavList(), relative to the earlier article, is the use of key 18: Save access paths. This key controls whether or not logical file access paths that are dependent on the physical files being saved are also saved. There are three possible values:
- '0'—The logical file access paths are not saved.
- '1'—The physical file and all eligible logical file access paths over it are saved.
- '2'—The system value QSAVACCPTH determines whether to save the logical file access paths over the physical file being saved.
The default value for key 18 is '2'—use the system value QSAVACCPTH. As the IBM-provided default for this system value is *YES and Ray indicated he did not want to save the logical files, SavPFs explicitly uses key 18 and sets the value to '0', indicating that logical file access paths are not to be saved.
Having set key 18, procedure FmtSavList() returns to the *inzsr subroutine which, in turn, gives control to the mainline of SavPFs. The mainline processing is to process all *FILE entries returned by the QUSLOBJ API (called earlier in the *inzsr subroutine) within a FOR loop. If the *FILE entry contains an extended attribute of 'PF', then the file name is added to the list of files to be saved by the QSRSAVO API (along with the object type of *FILE). If the *FILE entry contains any other extended attribute value, then the entry is bypassed and the next *FILE entry examined. The field ObjHdr.Nbr, a part of the control information associated with key 1 (covered in the previous API Corner article), is used to hold the current number of physical files that have been added to the QSRSAVO list of files to be saved.
When the FOR loop is exited, SavPFs determines if any physical files were found in the list of *FILEs. If not (ObjHdr.Nbr is still 0), then a *COMP message is sent indicating that no files were found and SavPFs ends.
If any physical files were found, then the remainder of the key 1 control record is set. This involves setting the key value of 1 to the save control and determining the final size of the list. This final size includes the size of the number of files to be saved field (ObjHdr.Nbr) and the actual size of the *FILE list (which is determined by multiplying the number of files to be saved by the size of each file entry). This size of each file entry is 20 bytes: 10 bytes for the object name, 10 bytes for the object type.
FinishEntry() is then called to, well, finish the key 1 record processing and the QSRSAVO API is called, passing all of the control information in the QTEMP/SAVLIST user space. When the API returns, a check is made to determine if the save operation was successful. If not, a *DIAG message is sent followed by an *ESCAPE message further identifying the error.
Assuming that you have stored the above program source in source file QRPGLESRC and that the library containing QRPGLESRC is in your current library list, then you can create the SavPFs program with the following command.
CrtBndRPG Pgm(SavPFs)
To save all of the physical files in library SOMELIB, you can now use the following commands to create a *SAVF and save those files.
CrtSavF File(SavePFs)
Call Pgm(SavPFs) Parm(SomeLib SavePFs)
As usual, if you have any API questions, send them to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll see what I can do about answering your burning questions in future columns.
LATEST COMMENTS
MC Press Online