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:

1. 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.
2. 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.
3. 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.
4. 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:
   1. Was there an error in returning the list? If so, a *DIAG message is sent, followed by an *ESCAPE message identifying the error.
   2. 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.
   3. Were no *FILE objects found in the library? If so, an *ESCAPE message is sent as there is nothing to save
5. 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).
6. 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.