TAA Tools
DTAARAARC       DATA AREA ARCHIVE                      TAAARAR

The Data  Area Archive tool  provides online  save files for  specified
data  areas.   Multiple versions  may exist  for each  data area.   The
DTAARAARC  tool is  not intended to  replace normal  backup, but rather
to allow a quick  review of a previous value.   A typical use would  be
to restore  the object to a different  library to allow a  review.  You
can  also restore  from the  online save files.   Several  commands are
provided.

The data  areas are  backed up  to save  files in  a specified  library
along with control information.

Several commands exist:

      - CRTARAARC     Create Data Area Archive
      - DLTARAARC     Delete Data Area Archive
      - WRKARAARC     Work Data Area Archive
      - STRARAARC     Start Data Area Archive
      - ADDARAARC     Add Data Area Archive
      - ADDARAARC2    Add Data Area Archive 2
      - DSPARAARC     Display Data Area Archive
      - RTVARAARC     Retrieve Data Area Archive

You can have multiple data archives, but only one per library.

Test driving the DTAARAARC tool
-------------------------------

A library  will be  used to  contain both  the DTAARAARC control  files
and the save files.  A unique library is preferred.

  **   Create the Data Archive control files with the command:

             CRTARAARC    ARAARCLIB(xxx)

  **   If  the library  specified is  not on the  library list,  add it
       with ADDLIBLE.

  **   Enter the command  that will  allow you  to define  one or  more
       data areas that will be used.

             WRKARAARC

       When the display appears,  use F6 to enter a data  area name and
       library.   A  unique 2  character ID  must  be assigned  to each
       data  area to allow a naming  convention for the save files (see
       the  section  on 'Save  file  naming  convention'.    The  first
       character  must be A-Z.   The  second character  must be  A-Z or
       0-9.

       Specify  a 2 for 'Max version to  keep' and take the default for
       'Save by STRARAARC  *ALL'.   To understand  the parameters,  see
       the help  text or the  parameter descriptions for  the ADDARAARC
       command in this documentation.

  **   Return  to a command  entry display  and start the  archive save
       process with STRARAARC.

             STRARAARC

       The command determines the data  areas you have requested to  be
       archived.

       All  saves specify  UPDHST(*NO) meaning  the  the objects  being
       saved are not marked as saved.

       Assuming  you  specified  a  2  for  max  versions,  do  another
       STRARAARC to create another save file for each data area.

             STRARAARC

  **   Work with the data areas that were identified:

             WRKARAARC

       The last save date for each data area is identified.

       Options  2 and  5 allow  a change  or display  of the  data area
       record.    Options  6  and  7  allow  a  display   of  the  data
       attributes and the data area value.

       Use  Option 8  (Dsp Vers)  to  display the  save file  versions.
       You  should  see 2  save files  as  two STRARAARC  commands were
       used and 2 versions were requested  to be kept.  The first  save
       uses an 'A'  as the last character  of the save file  name.  You
       can  have up to  26 versions per  day (see the  later discussion
       of the 'Save file naming convention').

       Use option  9  from the  display  of the  saved  file  versions.
       This prompts for the  RSTOBJ command.  The basic  parameters are
       protected and  the restore library defaults to  QTEMP.  If QTEMP
       is  used, a restore occurs followed  by DSPDTAARA to display the
       value from QTEMP.  Take  the defaults and restore to QTEMP.   If
       this  is  the value  that  should  be  restored, there  are  two
       methods of doing so:

         --   Return  to  a command  entry  line and  use  CPYDTAARA to
              replace the data area value.

         --   Use option 9  again and  specify the  library to  restore
              to with the RSTOBJ prompt.

  **   Return to  a command  entry display and  display the  data areas
       being archived:

             DSPARAARC

       A  listing  would  be displayed  of  all  the  data areas  being
       archived.

  **   Enter the STRARAARC command again:

             STRARAARC

  **   When the maximum  number of versions  is exceeded (after  saving
       to the  current save  file), the  STRARAARC command deletes  the
       excess versions.  The listing describes the number deleted.

  **   There  are two additional  methods of  adding data areas  to the
       data area archive.

         --   ADDARAARC adds a single data area.

         --   ADDARAARC2  adds one  or more  data areas.   For example,
              you can  add all or  generic data  areas from a  specific
              library.   ADDARAARC2  finds the  last ID  that  was used
              and  automatically  assigns the  next  2  letters (second
              character  could be  a  number)  as  the  new  ID.    The
              internal tool  RTVNXTID is used to  assign the IDs.   For
              a  complete understanding of the  technique used, see the
              RTVNXTID tool.

              If an existing  data area is  already being archived,  it
              is  bypassed   (a   message  occurs)   and  the   command
              continues.

  **   If  you have completed  the test, you  can delete the  data area
       record  and  any  associated  versions  for  any  data  area  by
       entering:

             WRKARAARC

       and then  using Option 4.   Both  the data  area record and  any
       associated save file versions will be deleted.

  **   If  you no  longer need  the  DTAARAARC control  files and  have
       *ALLOBJ special authority, enter:

             DLTARAARC    ARAARCLIB(xxx)

Deleting old versions
---------------------

The  STRARAARC command will cleanup excess  save file versions based on
the 'maximum versions to keep'  parameter entered when a new data  area
is added to the archive.  You may change this value at any time.

You may  also want to  delete a save file  version manually.   This can
be  done from WRKARAARC by  using Option 8 (Display  versions) and then
Option 4 from the list of versions for a data area.

If you no longer want  a data area to be  saved by STRARAARC, Option  4
from the  WRKARAARC display will  delete the data  area record and  any
save file versions for the data area.

Save file naming convention
---------------------------

Each data area  to be saved by the DTAARAARC  tool, requires a unique 2
character  ID be assigned.   The save  file name is  10 characters made
up of:

        2  Unique ID
        7  CYYMMDD
        1  A letter A-Z

The first or  only save  file created for  a data area  on a given  day
will have  a last  letter of 'A'.   There is  a maximum of  26 versions
for each data area to be saved on a given day.

If  the  number  is  exceeded, STRSPLARC  will  describe  the  error if
SPLFILE(*YES)  is specified.    If  SPLFILE(*NO)  is  used,  an  escape
message will occur.

Security considerations
-----------------------

  **   CRTARAARC.   The command  defaults to  allow *USE  of the  files
       that are  created.  Only a user  with *CHANGE authority can add,
       change, or delete the data in the ARAARCP file.

  **   WRKARAARC.  The  user must  have *USE authority  to the  ARAARCP
       file to use the display options.

       Option  8=Display  versions requires  authorization  to  display
       the save files.

       To add,  change, or delete  a record requires  *CHANGE authority
       to the ARAARCP file.

  **   STRARAARC.   The  user must  have *SAVSYS  special authority and
       *CHANGE authority to the ARAARCP file.

  **   ADDARAARC.    The  user  must  have  *CHANGE  authority  to  the
       ARAARCP file.

  **   ADDARAARC2.    The  user  must  have *CHANGE  authority  to  the
       ARAARCP file.

  **   DSPARAARC.   The  user must have  *USE authority  to the ARAARCP
       file.

  **   RTVARAARC.  The  user must  have *USE authority  to the  ARAARCP
       file.

DLTARAARC escape messages you can monitor for
----------------------------------------------

      TAA9891    Not all save files could be deleted.

Escape messages from based on functions will be re-sent.

STRARAARC escape messages you can monitor for
----------------------------------------------

      TAA9892    The specifically named data area is not in ARAARCP

Escape messages from based on functions will be re-sent.

RTVARAARC escape messages you can monitor for
----------------------------------------------

      TAA9892    The specifically named data area is not in ARAARCP

Escape messages from based on functions will be re-sent.

ADDARAARC escape messages you can monitor for
----------------------------------------------

      TAA9893    The ID already exists
      TAA9894    The data area record already exists

Escape messages from based on functions will be re-sent.

ADDARAARC2 escape messages you can monitor for
-----------------------------------------------

      TAA9893    The ID already exists

Escape messages from based on functions will be re-sent.

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

   ARAARCLIB     The library  to contain  the Data  Area Archive  files
                 and  save files.   A physical  file (ARAARCP)  and two
                 logical files (ARAARCL and  ARAARCM) will be  created.

   SRCLIB        The  source  library  to  use  for  the  QATTDDS  file
                 source.  The default is *TAAARC.

                 A specific  user library may be named,  but the source
                 file name must be QATTDDS.

   AUT           The authority to the ARAARCP physical file.

                 *USE is the default.

                 *CHANGE or *EXCLUDE may be specified.


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

   ARAARCLIB     The  library  that  contains  the  Data  Area  Archive
                 files and  save files.   The  physical file  (ARAARCP)
                 and two  logical files  (ARAARCL and ARAARCM)  will be
                 deleted  along with any save  files that were created.

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

   ARAARCLIB     The  library  that  contains  the  Data  Area  Archive
                 files and save files.

                 The default is  *LIBL.  A specific  library or *CURLIB
                 may also be entered.


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

   DTAARA        The qualified name of the data area to be saved.

                 The  default is  *ALL/*ALL for all  data areas  in the
                 ARAARCP  file   that  specify   *YES  for   'Save   by
                 STRARAARC *ALL'.

                 A specific  data area  may be  named to be  saved.   A
                 library  name is  required.   Both  the data  area and
                 library  portion default to  *ALL.  You  may save *ALL
                 data  areas from  a  specific  library or  a  specific
                 data area name that exists in multiple libraries.

   SPLFILE       A *YES/*NO  parameter for whether a  spooled file will
                 be output with a summary of the results.

                 *YES  is the default to create  the spooled file.  One
                 line is output for each data area.

                 *NO may be  specified to bypass the  output.  *NO  may
                 be desirable if  a specific data area  is being saved.

   ARAARCLIB     The  library  that  contains  the  Data  Area  Archive
                 files and save files.

                 The default is *LIBL.   A specific library or  *CURLIB
                 may also be entered.


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

   DTAARA        The qualified  name  of the  data area  to be  entered
                 into the ARAARCP file.

                 The  library  name  defaults  to  *LIBL.   A  specific
                 library  or  the  special value  *CURLIB  may  also be
                 entered.

   ID            The unique 2 character  ID assigned to the data  area.
                 The  first   character  must  be  A-Z.     The  second
                 character must be A-Z or 0-9.

   SAVBYALL      A  *YES/*NO   parameter  for  whether  the  data  area
                 should be  saved  if  STRARAARC  DTAARA(*ALL/*ALL)  is
                 specified.

                 *YES  is the  default meaning  the data  area will  be
                 saved    if   DTAARA(*ALL/*ALL)   is    specified   on
                 STRARAARC.

                 *NO may be specified so  that the data area will  only
                 be  saved  if   the  DTAARA  parameter   on  STRARAARC
                 specifies the data area name.

   MAXVER        The  number of versions  to be  kept.  The  default is
                 1.  A number may be entered between 1 and 60.

   ARAARCLIB     The  library  that  contains  the  Data  Area  Archive
                 files and save files.

                 The default is *LIBL.   A specific library  or *CURLIB
                 may also be entered.


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

   DTAARA        The  qualified name  of the  data area  to  be entered
                 into  the ARAARCP  file.   A specific name,  a generic
                 name, or *ALL may be entered.

                 The library name must be specified.

   SAVBYALL      A  *YES/*NO  parameter  for  whether  the  data   area
                 should  be  saved if  STRARAARC  DTAARA(*ALL/*ALL)  is
                 specified.

                 *YES  is the  default meaning  the  data area  will be
                 saved   if   DTAARA(*ALL/*ALL)    is   specified    on
                 STRARAARC.

                 *NO may be specified  so that the data area  will only
                 be  saved   if  the  DTAARA   parameter  on  STRARAARC
                 specified matches the data area name.

   MAXVER        The  number of  versions to be  kept.   The default is
                 1.  A number may be entered between 1 and 60.

   ARAARCLIB     The  library  that  contains  the  Data  Area  Archive
                 files and save files.

                 The default  is *LIBL.  A specific  library or *CURLIB
                 may also be entered.


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

   ARAARCLIB     The  library  that  contains  the  Data  Area  Archive
                 files and save files.

                 The default is *LIBL.   A specific library or  *CURLIB
                 may also be entered.

   OUTPUT        How  to output  the  results.   *  is  the default  to
                 display  the spooled  file if  the command  is entered
                 interactively.  The spooled  file is deleted after  it
                 is displayed.

                 If  the command  is  entered  in  batch or  *PRINT  is
                 specified,  the spooled file  is output  and retained.


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

   DTAARA        The  data area  and library  name where  the data area
                 exists that is being archived.

                 The library name is required.

   RTNARCLIB     The  library  where  the  data  area  archive  exists.
                 This  is an optional  parameter that  if used  must be
                 specified as *CHAR LEN(10).

   ID            The  2 character ID  assigned to the data  area.  This
                 is  an  optional  parameter  that  if  used   must  be
                 specified as *CHAR LEN(2).

   SAVBYALL      A *YES/*NO  return value for  if the data  area should
                 be   saved   when   STRARAARC   DTAARA(*ALL/*ALL)   is
                 specified.   This is  an  optional parameter  that  if
                 used must be specified as *CHAR LEN(4).

   MAXVER        The maximum  number of  versions to  be kept on  line.
                 This  is an optional  parameter that  if used  must be
                 specified as *DEC LEN(3 0).

   CURVER        The  current number  of versions  kept on  line.  This
                 is  an  optional  parameter  that  if  used   must  be
                 specified as *DEC LEN(3 0).

   LSTSAVDAT     The  last save date  when STRARAARC  was used  to save
                 the  data area.   The format  is CYYMMDD.   This is an
                 optional parameter that if  used must be specified  as
                 *CHAR LEN(7).

   LSTSAVVER     The  last save  file  name  associated with  the  data
                 area.   This  is an  optional  parameter that  if used
                 must be specified as *CHAR LEN(10).

   ARAARCLIB     The  library  that  contains  the  Data  Area  Archive
                 files and save files.

                 The default is  *LIBL.  A specific library  or *CURLIB
                 may also be entered.


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

Because of the  ID naming restrictions, you can have  a maximum of 26 x
36 or 936 data areas in a data area archive.

Up  to 26 versions per  day per data area may  be saved with STRARAARC.

A maximum of 60 versions may be kept per data area.

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

The following TAA Tools must be on your system:

     CHGOBJD2        Change object description 2
     CHKACTOBJ       Check active object
     CHKALLOBJ       Check *ALLOBJ special authority
     CHKNAM          Check name
     CHKOBJ3         Check object 3
     CHKSAVSYS       Check *SAVSYS special authority
     CHKTAAOWN       Check TAA owner
     CPYTAADDS       Copy TAA DDS
     DSPDTAARAD      Display data area description
     EDTVAR          Edit variable
     RSNLSTMSG       Resend last message
     RTVDAT          Retrieve date
     RTVOBJD2        Retrieve object description 2
     RTVOBJLST       Retrieve object list
     RTVNXTID        Retrieve next ID
     RTVSYSVAL3      Retrieve system value 3
     SNDCOMPMSG      Send completion message
     SNDDIAGMSG      Send diagnostic message
     SNDESCINF       Send escape information
     SNDESCMSG       Send escape message
     SNDSTSMSG       Send status message
     UPDPFILE        Update PFILE keyword

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

None, the tool is ready to use.

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

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

   CRTARAARC     *CMD                   TAAARAR       QATTCMD
   DLTARAARC     *CMD                   TAAARAR2      QATTCMD
   WRKARAARC     *CMD                   TAAARAR3      QATTCMD
   STRARAARC     *CMD                   TAAARAR4      QATTCMD
   ADDARAARC     *CMD                   TAAARAR5      QATTCMD
   DSPARAARC     *CMD                   TAAARAR6      QATTCMD
   RTVARAARC     *CMD                   TAAARAR7      QATTCMD
   ADDARAARC2    *CMD                   TAAARAR8      QATTCMD
   TAAARARC      *PGM       CLP         TAAARARC      QATTCL
   TAAARARC2     *PGM       CLP         TAAARARC2     QATTCL
   TAAARARC3     *PGM       CLP         TAAARARC3     QATTCL
   TAAARARC4     *PGM       CLP         TAAARARC4     QATTCL
   TAAARARC5     *PGM       CLP         TAAARARC5     QATTCL
   TAAARARC6     *PGM       CLP         TAAARARC6     QATTCL
   TAAARARC7     *PGM       CLP         TAAARARC7     QATTCL
   TAAARARC8     *PGM       CLP         TAAARARC8     QATTCL
   TAAARARC23    *PGM       CLP         TAAARARC23    QATTCL
   TAAARARC24    *PGM       CLP         TAAARARC24    QATTCL
   TAAARARC25    *PGM       CLP         TAAARARC25    QATTCL
   TAAARARC26    *PGM       CLP         TAAARARC26    QATTCL
   TAAARARC27    *PGM       CLP         TAAARARC27    QATTCL
   TAAARARR3     *PGM       RPG         TAAARARR3     QATTRPG
   TAAARARR4     *PGM       RPG         TAAARARR4     QATTRPG
   TAAARARR5     *PGM       RPG         TAAARARR5     QATTRPG
   TAAARARR6     *PGM       RPG         TAAARARR6     QATTRPG
   TAAARARR7     *PGM       RPG         TAAARARR7     QATTRPG
   TAAARARR22    *PGM       RPG         TAAARARR22    QATTRPG
   TAAARARR24    *PGM       RPG         TAAARARR24    QATTRPG
   TAAARARP      *FILE      PF          TAAARARP      QATTDDS
   TAAARARL      *FILE      PF          TAAARARL      QATTDDS
   TAAARARM      *FILE      PF          TAAARARM      QATTDDS
   TAAARARD      *FILE      DSPF        TAAARARD      QATTDDS
   TAAARARE      *FILE      DSPF        TAAARARE      QATTDDS

Structure
---------

CRTARAARC   Cmd
   TAAARARC   CL pgm

DLTARAARC   Cmd
   TAAARARC2  CL pgm

WRKARAARC   Cmd
   TAAARARC3  CL pgm
      TAAARARR3   RPG pgm
        TAAARARD    Display file
        TAAARARC23  CL pgm for CHKOBJ and RTVOBJD
        TAAARARC24  CL pgm using RTVOBJLST
        TAAARARC26  CL pgm to delete save files
        TAAARARR24   RPG pgm to display versions
          TAAARARE    Display file
          TAAARARC27   CL pgm to restore and DSPDTAARA

STRARAARC   Cmd
   TAAARARC4  CL pgm
      TAAARARC24  CL pgm using RTVOBJLST
      TAAARARC25  CL pgm does CHGOBJD2 using adopt
      TAAARARR4  RPG pgm to update save information

ADDARAARC   Cmd
   TAAARARC5  CL pgm
     TAAARARR5  RPG pgm to add to file

DSPARAARC   Cmd
   TAAARARC6  CL pgm
     TAAARARR6  RPG pgm to print

RTVARAARC   Cmd
   TAAARARC7  CL pgm
     TAAARARR7  RPG pgm

ADDARAARC2  Cmd
   TAAARARC8  CL pgm
     TAAARARR5  RPG pgm - ADDARAARC Pgm
					

Added to TAA Productivity tools July 15, 2010


Home Page Up to Top