TAA Tools
RPLPF           REPLACE PHYSICAL FILE                  TAADBFZ

The Replace Physical  File command allows  you to make DDS  changes and
then  specify the RPLPF  command to  replace an existing  physical file
and all dependent logicals.

RPLPF will operate successfully on:

       - A physical file with a single member
       - A physical file with multiple members
       - A physical file with no members
       - A physical file with no dependent logical files
       - A physical file with dependent logical files.

The  intent of  RPLPF is to  allow you to  just change the  DDS for the
file and  then issue a  simple command.   The following  would be  used
when simple  changes occur  such adding or  dropping a  field, changing
the length  of a field, or a change to  DDS functions such as COLHDG or
TEXT (a different CPYF option is  required when the name of a field  is
changed in the DDS).

               RPLPF    FILE(FILEX) CPYF(*MAPDROP)

Any existing data  in the file is  copied (by default) to  the new file
using CPYF  with FMTOPT(*MAP *DROP).  Any  dependent logical files will
also be re-created.

No dependent  programs  are  re-created.   If  you  need  to  re-create
dependent programs, see the TAA Tool RBLDBF.

RPLPF will do the following:

  **   Extract the existing  attributes of the  file (e.g.   MAINT) and
       use them to re-create the file.

  **   Copy the existing authorities to the new file.

  **   Re-create  any  members using  their  existing attributes  (e.g.
       the SHARE parameter).

  **   Copy  (by  default)  any existing  data  from  the corresponding
       members to  the  new members  using  FMTOPT(*MAP *DROP).    This
       allows  you to  add new  fields to  the format,  change existing
       attributes,  or  delete fields  (CPYF restricts  mapping  from a
       character to decimal field or vice versa).

  **   Restart physical file journaling if needed.

  **   Restart access path journaling if needed.

  **   Determine if any  trigger programs  exist and  if so  re-specify
       them on the new file.

  **   Determine the dependent  logical files and re-create  them using
       the TAA Tool RPLLF.

To  change a  field name  requires that  the record  length of  the old
version and  the  new  version  remain  the same.    Thus  if  you  are
changing a  field  name, you  cannot add/drop  fields  or change  field
lengths  at the same  time (you  can change  DDS functions that  do not
impact  the record length such  as COLHDG or TEXT).   A typical command
would be:

               RPLPF    FILE(FILEX) CPYF(*RNMFLD)

Note that if you are changing  a field name, any use of the  same field
name in logical file DDS should also be changed before using RPLPF.

DEPLFP file in QTEMP
--------------------

For  each logical  that is  created, a  record is  added to  the DEPLFP
file in QTEMP.  If no LFs exist, the file will not exist.

The model file is TAADBFZP with a format name of LFRCD.

Command parameters                                    *CMD
------------------

   FILE          The  qualified file  name of  the physical file.   The
                 library value  defaults to  *LIBL.   *CURLIB may  also
                 be specified.

   CPYF          The type of CPYF command that should be used.

                 *MAPDROP should  be specified  when you  are adding  a
                 new  field, dropping a  field, changing  the length of
                 a field, or changing a  DDS keyword such as COLHDG  or
                 TEXT.  CPYF is used with FMTOPT(*MAP *DROP).

                 *RNMFLD  should  be  used  when  you  are  renaming  a
                 field.   When *RNMFLD is  used, the length  of the old
                 version  and the new  version must be  the same.  CPYF
                 is used  with FMTOPT(*NOCHK).   Therefore, you  cannot
                 rename  a field  and  also add/drop  fields or  change
                 lengths  at the  same time.   You can  use *RNMFLD and
                 also make  a change  to a  DDS keyword  that will  not
                 impact the  length such as COLHDG.   Note that  if you
                 use  *RNMFLD,  the  use  of  the  same field  name  in
                 dependent logical file  DDS should  be changed  before
                 using RPLPF.

                 *NO may  be specified  to not  copy any  of the  data.
                 This  will recreate  the data  base network,  but none
                 of the data will be copied.

                 *YES  is the  previous default  used and  is mapped to
                 *MAPDROP.

   DLTSPLF       Whether  the  spooled   file  created  by  the   CRTPF
                 command  should  be  deleted.   The  default  is  *YES
                 which  will cause a deletion if  the data base network
                 is  successfully  replaced.    If  the  file   is  not
                 created  successfully,  or  the member  is  not  added
                 properly,  or  any dependent  logical  files  or their
                 members  are  not  properly  re-created,  the  spooled
                 file  will still  exist.    *NO  may be  specified  to
                 always retain the spooled file.

   SRCARCLIB     Whether a  source archive may hold the  source for the
                 files  to be re-created.  The  default is *NONE.  This
                 refers  to  the  TAA  Tool  SRCARC  which  allows  the
                 removal of source from the source files.

                 If  an archive library  is named  and the  source does
                 not  exist  in the  source member  used  to originally
                 create the  object, the  source data  will attempt  to
                 be copied out  of the archive to  the original member.
                 If  successfully copied  from the archive,  the source
                 is used to create the file and then removed.

   OWNER         Who the owner of the file  should be.  The default  is
                 *CURRENT  for  the  user  of  the  command.    If  any
                 logical  files are  created, they  will also  be owned
                 by the current user.

                 *SAME  may  be  specified to  retain  the  same owner.
                 *SAME may  only  be specified  when the  current  user
                 has *ALLOBJ  special authority.  If  any logical files
                 are  created,  they  will  also  retain  their current
                 ownership.

Sequence of processing
----------------------

In order  to  replace a  physical  file  with dependent  logicals,  the
following sequence of events occurs:

  **   The file  is accessed to determine  that it is a  physical file,
       the DDS exists, and the file is not is use.

  **   The  DDS for  the existing file  is used  to recreate a  file of
       the same name in QTEMP.   The same file name cannot exist  prior
       in  QTEMP.    If  the  file  cannot   be  created,  the  program
       abnormally  terminates and  the  existing data  base  network is
       still intact.  The file will not exist in QTEMP.

  **   If  the file  is created  successfully, the  authorizations from
       the existing file are  copied to the new file and  journaling is
       restarted if needed.

  **   If  the physical  file  is keyed,  a  sub program  is called  to
       determine   if  the  access   path  of  the   existing  file  is
       journaled.  If so, access path journaling is restarted.

  **   The member  list for  the  existing file  is accessed  and  each
       member  is  re-created  using the  attributes  of  the  existing
       member.

       The members  are accessed using DSPFD *MBRLIST.   This causes an
       alphabetical sequence of  member names  to be name  and the  new
       members  are  created in  that  order.    This may  not  be  the
       sequence of the existing file.

  **   If  records exist in  the old  member and if  CPYF(*MAPDROP) was
       specified,  the  old member  data is  copied  to the  new member
       with FMTOPT(*MAP *DROP).   If  CPYF(*RNMFLD) was specified,  the
       old member data is copied using FMTOPT(*NOCHK).

  **   Any dependent logical files are determined.

  **   The old  physical file is  renamed to TAATMPRPL in  the existing
       library.   The file  name TAATMPRPL  must not exist  in the same
       library.  Any  dependent logical files  now point to  TAATMPRPL.
       This allows the  TAA Tool RPLLF to  be used where the  old files
       still  exist  and the  new  files  will be  built  over  the new
       physical file.

  **   The new file  in QTEMP  is moved to  the original  library.   No
       logical files exist over the new file at this point.

  **   Any dependent  logical files are  re-created using the  TAA Tool
       RPLLF.

  **   If a  logical file cannot  be re-created over  the new physical,
       at attempt will be made to delete the file.

  **   When  all logical  files have  been processed  and there  are no
       more  dependent  files  based  on  the  TAATMPRPL   file.    The
       TAATMPRPL file is deleted.

  **   If  no errors  occurred in  either  the create  of the  physical
       file,  the adding of  physical members, the  creation of logical
       files, and the adding of  logical members, the spooled file  for
       the CRTPF command is deleted if DLTSPLF(*YES) was specified.

Recovery
--------

In most  cases, the  RPLPF command  will complete  normally.   However,
there  are several  reasons a  failure may  occur and  you may  need to
recover.

  **   If the new physical  file cannot be created  in QTEMP, the  data
       base network will still be intact.

  **   The  new  physical  file will  be  created  in  QTEMP,  but  the
       program may  not be able to  continue past that point.   The old
       physical  still  exists  at  that  time  and  you  will  need to
       determine the problem and then delete the QTEMP version.

  **   If the physical  file can be  re-created and the members  added,
       the old physical  file will be renamed to  TAATMPRPL and the new
       file is moved from QTEMP.

       If  dependent logical files  exist, there is  a possibility that
       they cannot be  replaced and therefore  the TAATMPRPL file  will
       still  exist  (It  cannot  be deleted  because  dependent  files
       still  exist  over it).   For  example,  this would  occur  if a
       logical file was in use, the  user was not authorized to  delete
       the file, no source exists, etc.

An escape  message will describe  the problem.   You should use  DSPDBR
against  the TAATMPRPL  file to  determine  what logicals  still exist.
These  should be  manually deleted  along with  TAATMPRPL.   You should
then manually  re-create any  of the logical  files that  could not  be
replaced.  The new physical file will be correct at that point.

Restrictions
------------

The physical file cannot be replaced if it is in use.

Once   the  command   begins,  you   should  let   it   finish  without
interrupting  it (e.g.   System Request -  ENDRQS) to  allow the proper
cleanup.

You should not use RPLPF more than  once at the same time for the  same
library.    This  is  due  to the  renaming  convention  used  for  the
TAATMPRPL file name.

If  multiple  members exist,  the  sequence in  which  the  members are
added to the new file may differ.

Prerequisites
-------------

The following TAA Tools must be on your system:

     ALCTMPMBR    Allocate temporary member
     ALCDBF       Allocate data base file
     CHKAPOST     Check apostrophes
     EDTVAR       Edit variable
     RPLLF        Replace logical file
     RTVDBFA      Retrieve data base file attributes
     RTVPFA       Retrieve physical file attributes
     SNDCOMPMSG   Send completion message
     SNDESCMSG    Send escape message
     SNDSTSMSG    Send status message
     SRCARC       Source archive

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   RPLPF         *CMD                   TAADBFZ       QATTCMD
   TAADBFZC      *PGM       CLP         TAADBFZC      QATTCL
   TAADBFZC2     *PGM       CLP         TAADBFZC2     QATTCL
   TAADBFZC3     *PGM       CLP         TAADBFZC3     QATTCL
   TAADBFZC4     *PGM       CLP         TAADBFZC4     QATTCL
   TAADBFZC5     *PGM       CLP         TAADBFZC5     QATTCL
Structure
---------

RPLPF
   TAADBFZC     CPP and main processing program
                   Does CRTPF
      TAADBFZC2      Does RPLLF for each dependent file
        TAADBFZR2      Writes records to DEPLFP in QTEMP
      TAADBFZC3      Checks access path journaling
      TAADBFZC4      Checks authority to dependent LFs
      TAADBFZC5      Re-specifies any trigger programs
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top