TAA Tools
SRCARC          SOURCE ARCHIVE                         TAASMAA

The Source  Archive  function provides  the ability  to capture  source
versions  and  store  them in  an  archive  for  backup, retrieval  and
history.

The  UPDSRCARC  command  may be  used  to  capture any  new  or changed
members into the  archive as separate versions.   The source is  placed
in  a  compressed  format  which  can  account  for  significant  space
savings.    Once  the source  is  in the  archive,  seldom  used source
members can  be  optionally removed.   If  needed  again, they  can  be
displayed or 'copied out' of the archive.

The  MTNSRCARC  command  provides  a cleanup  function  to  delete  old
archive  versions.   It  also provides  an option  to  remove unchanged
source members to assist in keeping  the actual source files small.   A
second   command   (MTNSRCARC2)   provides   an   alternate   form   of
maintenance.

The WRKSRCARC  command displays the versions in  a subfile and provides
options  to  change control  information,  delete the  version, display
the source,  print the  source, or 'copy  out' the  source.   Selection
criteria exists to allow you to minimize paging thru the archive.

The source  archive (made up of  2 physical files) should  be backed up
regularly.   If this  is done,  there is no  need to  backup the source
files as the archive  contains the same information.   Because the  two
archive files  contain only single  members, the save/restore  time can
be  significantly  faster than  backing  up  large multi-member  source
files.  See the section on 'Backup'.

Anytime source is  archived, compression  occurs.   Anytime an  archive
version is 'copied out', decompression occurs.

Only  one archive  can  exist  in a  library.   Multiple  archives  can
exist.   A single  archive can  be used  to store source  from multiple
source files and multiple libraries.

Advantages
----------

  **   Any  changed source  members can be  captured one  or more times
       per day  and  stored in  the  archive.   This allows  backup  to
       occur  at any  time of  day regardless  of whether  a programmer
       has the source member open for update.

  **   Old  versions are kept on  line.  If a  prior version is needed,
       it can normally be 'copied  out' of the archive without doing  a
       restore.

  **   The  source is  stored in  a compressed  format in  a data  base
       file.   If only a single version is  kept, the amount of storage
       required can  be significantly  reduced.   If only  the  current
       versions are in the  archive, the space saving varies  but would
       typically be  25 - 30% of  the original source file  space.  See
       the section on 'Compression samples'.

  **   Because   the  source  is   stored  in  a   single  member,  the
       save/restore performance  for saving all  source is much  faster
       than saving  the corresponding members.   Journaling the archive
       files  can  produce a  faster backup  solution  than the  use of
       SAVCHGOBJ  for  source  files.    If  you  are  backing  up  the
       archive, you do  not need to backup  the source files.   See the
       section on 'Backup'.

  **   Because  the   archive  header  records  contain   most  of  the
       information found in the  member level control block,  functions
       that  search for  various  selection  criteria run  much  faster
       against  the  archive  than against  the  source  members.   For
       example,  you  can  quickly  access  all  members  of  a certain
       source type that have changed  since a date.  Compare  this type
       of  request versus  doing a  similar  function such  as the  TAA
       tool  PRTSRCSUM which must  build an outfile of  all the members
       and then search the outfile.

  **   Scanning the  archive source  is much  faster  than the  similar
       functions  of  FNDSTRPDM  or  the TAA  tool  SCNSRC.    See  the
       SCNSRCARC command discussion.

  **   Since the  source is in the archive,  it makes it very difficult
       to lose the source  for any member.   It takes  an overt act  to
       remove  the current  version from  the  archive.   If  you do  a
       special  save of  the archive  at 6  month intervals  and retain
       the  backup  for a  few years,  it is  highly unlikely  that you
       will every lose any source.

Disadvantages
-------------

  **   The archive is only  effective if you regularly archive  new and
       changed source members.

  **   It  takes  system  resources  to archive  changed  versions  and
       maintain  the archive.    If you  can run  these functions  at a
       slack time of day, the impact can be minimal.

  **   The archive takes  disk space.   This disadvantage can  normally
       be overcome  if you let  the maintenance function  remove source
       members  that have  not changed  recently.   The space  taken by
       the archive with  a reasonable  number of  versions is  probably
       less than keeping all the source as source members.

  **   If  you remove  the  source members,  you  must 'copy  out'  the
       current  version in order  to display  or work with  the source.
       Some  applications require  that the  source be  online in order
       to operate successfully.

Files
-----

The physical files are:

             SRCARHP                      SRCARDP

          **************               **************
          *            *               *            *
          *   Header   *               *   Detail   *
          *            *               *            *
          **************               **************

            One record                   N records
              per version                  per version

            Key - Library                Key - Internal
                  File                           Seq nbr
                  Member
                  Version                500 byte area
                                          per record for
            Includes internal             compressed source
                 Seq nbr
              (unique per version)

A logical file SRCARHL also  exists and is built over the  SRCARHP file
to  assist in  the assignment  of internal  sequence numbers.   Another
logical file SRCARHM exists for processing in arrival sequence.

The  files are built with the CRTSRCARC  command.  The SRCARHM file was
added at  a later release.   If  it does  not exist  when WRKSRCARC  is
used, it is created automatically.

Command summary
---------------

   CRTSRCARC     Creates  the archive  files  in  a specified  library.
                 There  is no  corresponding delete  command.   See the
                 section on 'Deleting a source archive'.

   UPDSRCARC     Updates the archive with  new or changed members  from
                 one or  more  source files.   A  single member  option
                 also exists.

   MTNSRCARC     Maintains the  archive.  Provides a  cleanup method of
                 deleting  old  versions  based  on  a  number  of days
                 and/or a  maximum  count to  be  kept.   A  reorganize
                 option  exists to  cleanup the  deleted record  space.
                 An  option also  exists to  remove old  source members
                 that have not been changed in N days.

   MTNSRCARC2    Maintains the archive.   Provides a cleanup method  of
                 deleting  old  versions  if  the  current  version  is
                 older  than a  specified number of  days or  a maximum
                 number  of  old   versions  has  been   reached.     A
                 reorganize  option  exists  to   cleanup  the  deleted
                 record  space.    The  old  source  member  are  never
                 removed.

   WRKSRCARC     Displays  the  source archive  versions in  a subfile.
                 Options  are  provided   to  change  certain   control
                 information  in  the  archive header  record,  display
                 the  header  record,  display  the  source,  print the
                 source,  'copy  out'   the  source,   or  delete   the
                 version.     Selection  options  exist  to   fill  the
                 subfile.

   PRTSRCARC     Prints  the source archive versions  with either total
                 (per   file)   or   detail   (per   version)   output.
                 Different selection options  are supported.   There is
                 a  simple method  of printing  all those  members that
                 have changed since a specific date.

   SCNSRCARC     Scan  the  source  archive  for a  string.    The scan
                 command performs  the  same function  on the  archived
                 source  as  the  FNDSTRPDM  command or  the  TAA  tool
                 SCNSRC  do on source  members.  It allows  a string to
                 be specified  to  scan the  archive  data.   Only  the
                 current versions  are scanned.   You  may qualify  the
                 scan  to  a particular  file  and/or source  type.   A
                 report is printed  identifying the  members that  have
                 at least one use of the string.

   DSPSRCARCM    Displays  the source  from an  archived  member.   The
                 source  is 'copied  out'  to a  temporary  source file
                 and  displayed  using SEU.    The command  can  be run
                 from an option on the WRKSRCARC subfile display.

   CPYSRCARCM    'Copies out' of the  archive to a source member  for a
                 single member,  generic members or all  members.  This
                 is  used for retrieving the  archived source.  Generic
                 or all  member  support  is  limited  to  the  current
                 version.    The command  can  also  be entered  as  an
                 option from the WRKSRCARC subfile display.

   SYNSRCARCM    Synchronize  the archive  to the source  file members.
                 This is used  in a disaster  recovery situation or  in
                 any situation where  the source file has  been changed
                 so that  all of the members appear  to be changed when
                 in  reality  the archive  is  more current.    See the
                 discussion on disaster recovery.

   DLTSRCARCM    Deletes a version,  a version and all  older versions,
                 all non-minimum  required versions or  all versions of
                 a  member.  Generic member names  or all members for a
                 specified library/file may  be deleted.   If a  single
                 version  is  deleted,  it  can   only  be  the  oldest
                 version known  to the archive.   DLTSRCARCM can be run
                 from an option on the WRKSRCARC subfile display.

   RTVSRCARCD    Retrieve a source  archive member  description.   This
                 allows  a   CL   program  to   retrieve  the   current
                 attributes of any version in the archive.

   CMPSRCARCM    Compares  two  versions  of  the  same member  in  the
                 archive,  a range  of versions  (one spooled  file per
                 comparison), or  the actual  source  member against  a
                 version  in  the archive.    Special  values exist  to
                 assist   in  specifying  the   versions/member  to  be
                 compared.

   RCLSRCARCM    Reclaim a  version.    This command  is  intended  for
                 damage  conditions where  the header  does not  exist,
                 not  all  of  the  detail  records  exist,  etc.    It
                 'copies out' what  it can.   This should  not be  used
                 unless CPYSRCARCM is unsuccessful.

   CHKSRCARC     Checks  the  source  archive version  to  see  if  the
                 source  member still exists.   A listing  is produced.

Typical strategies
------------------

Typical strategies include:

  **   Use  the archive as  the backup means  and remove source members
       that have  not  been  changed recently.    This means  that  the
       source  files contain  only members  that have  been  changed in
       the  last N  days.  The  archive is  used as  the repository for
       source and for backup.   The source members  need not be  backed
       up.

  **   Same  as previous  except the  source members  are not  removed.
       They  do not  have  to be  backed up.   The  archive  provides a
       faster method of  backup and also  provides online versions  and
       history.   The advantages  of searching  the archive for  member
       level information or scanning the source still exist.

  **   Use  the  archive  to compress  a  set  of  seldom used  source.
       Assume  you have a set of  source (many source members) that you
       rarely need to  display or modify.   The source can be  archived
       and then the source members can be removed from the system.

  **   Use the  archive to distribute source.   Since the  archive is a
       data  base file, it can  move thru networks or  be held on media
       in  a  form  that  is  release  independent   (data  interchange
       format).   The compression  function is  usually more  efficient
       in  terms of  reducing space requirements  than the  SAV command
       compression   option   because   member   control   blocks   and
       save/restore information  do not  exist.   The archive  programs
       must be  on the receiving system  in order to 'copy  out' all of
       the members.

In  the  cases  where  the  archive  is  being  used  to  capture daily
changes, the typical approach would be:

  **   Use UPDSRCARC  one or  more times per  day.   This will  capture
       any new  or changed members.   Running UPDSRCARC  multiple times
       per  day  can  be an  advantage  in that  it  provides  the most
       current copy of what programmers  worked on (the last time  they
       ended SEU).   If they  need to retrieve  a prior version,  it is
       probably  online  and probably  more current  than  last night's
       backup.  There would normally be  no need to restore to  provide
       recovery.

  **   Backup the archive daily (two files).

  **   Use MTNSRCARC  on a periodic  basis (weekly  or monthly).   This
       will  cleanup  the   archive  files  (remove  excess  versions).
       Running  MTNSRCARC  weekly  does  not  imply  that  you  need to
       delete versions  that are  older than  one  week.   You can  set
       your own  retention period.   MTNSRCARC also defaults  to delete
       source  members that are archived and  have not been changed for
       60 days.   The  MTNSRCARC2 command  could be  used  in place  of
       MTNSRCARC.  See the section on 'Retention strategy'.

Life cycle of a source member
-----------------------------

Assume you  are running UPDSRCARC nightly  and MTNSRCARC at  month end.
The following describes what would happen in a typical case.

A programmer  is developing a source member  and has made changes every
day for  15 days  and then  the program  goes into  production.   Since
UPDSRCARC  is run  once  a  day, there  would  be  15 versions  in  the
archive.   If  MTNSRCARC is  run (using  the 10  default of  10 maximum
versions)  at the  end of  the month, it  would reduce  the versions to
10.  When MTNSRCARC is run  3 months from now (using the default  of 60
days), all but the current version would be deleted.

The default  for MTNSRCARC  is to remove  any source members  that have
not   changed  in  60  days.     Therefore,  the  source  member  would
eventually be  removed  automatically  and  only  the  current  version
would remain in the archive.

Five months later, the  programmer needs to make a  change.  The source
member  no  longer exists,  so  he  does a  'copy  out'  and takes  the
default to specify the current version.

       CPYSRCARCM    ARCMBR(mmmm) ARCFILE(llll/ffff)

The programmer makes  the change  and puts  it into  production.   That
night, UPDSRCARC would produce a new version.

Two  days  later,  it  is  realized  that   the  change  has  caused  a
regression.   The programmer wants to immediately get  back to the good
version.    If he  knows  the version  ID,  he can  use  the CPYSRCARCM
command directly.   Typically  he would  not  know the  version ID  and
therefore he would specify:

       WRKSRCARC     ARCFILE(llll/ffff) ARCMBR(mmmm)

The current  version would be displayed at  the top of a  subfile.  F11
would  be used to display all versions.   The programmer then positions
to the  version he  wants and  specifies the  'copy out'  option.   The
command  prompt appears  and  the source  is then  'copied  out'.   The
programmer  recompiles the source  and the  former version is  put back
into production.

The programmer makes  no other changes  during the day  so the  nightly
UPDSRCARC captures a changed  version which is really a  former version
(no  attempt  is  made  by  the  archive  to  minimize  the  number  of
duplicate versions).

The  programmer now makes the proper  change and UPDSRCARC picks up the
new version.

After 60 days, MTNSRCARC  would delete all but the current  version and
remove the source member again.

Getting started
---------------

You need to set a strategy for:

  **   How many archives you will have.

  **   What source files will be archived to each archive.

  **   How  you will  backup the  archive  files and  whether you  will
       backup the source files.  See the section on 'Backup'.

  **   What  security  control  you  need for  the  archive.    See the
       section on 'Security'.

  **   How often  you will  run the  UPDSRCARC command  to archive  new
       versions and what parameters you will specify.

  **   How often  you will  run the  MTNSRCARC command  to cleanup  old
       versions  and  what  parameters  you  will  specify.    See  the
       section on 'Retention strategy'.

Typically, you would  start out  doing something simple  until you  get
familiar with working with  the source archive.  If  you are interested
in testing the function, see the section on 'Testing'.

The CRTSRCARC  command is required to create an  archive in a specified
library.

Use  the UPDSRCARC command  and specify the source  files that you want
archived.  The first  use of this command  on a source file will  cause
all  existing members  to be  archived.   Subsequent  use will  archive
only  new or changed  versions.  The  normal use of  UPDSRCARC would be
in a  CL program  so that  you could  achieve  consistent results  each
time it is executed.

Compression samples
-------------------

The following  describes the  compression results on  a version  of the
QATT  source files.  All  source files were  92 bytes in  length.  This
data was produced on about V2R2.   The compressed size is the total  of
the  3  files that  make  up  a  source archive.    INCLUDE(*NONE)  was
specified  on UPDSRCARC.   Only a single  version exists.   The percent
column describes the percentage of the original size.

             ------- Source files --------       -- Source archive ---
             ----- Non - compressed ------       ---- Compressed -----
 File       Mbrs   Records  Avg        Size          Size       Percent
 ----       ----   -------  ---   ---------     ---------       -------

 QATTINFO    234    39,048  166   5,796,864     2,015,232         35 %
 QATTCMD     278     7,679   27   3,709,952       536,566         14 %
 QATTCL      385    55,611  144   8,881,664     2,613,760         29 %
 QATTDDS     124     6,033   48   1,715,200       340,480         20 %
 QATTRPG     192    27,969  146   4,455,424     1,204,736         27 %

    Total  1,213   136,340  112  24,559,104     6,710,774         27 %

The percentage will vary depending on such things as:

  **   The  average number  of records.   Small source  members such as
       the CMD type compress  better because the member  control blocks
       account for a larger percentage of the total file size.

  **   The amount  of text or documentation  in the source.   This does
       not compress well.

The  following describes  a comparison  made of  the same  source files
when SAVOBJ was  used with DTACPR(*YES)  to a save  file.  The  percent
column describes the percentage of the DTACPR(*YES) size.

             ------- Source files --------       -- Source archive ---
              On line       SAVOBJ
 File          size       DTACPR(*YES)           Size       Percent
 ----        ---------    ------------      ---------       -------

 QATTINFO    5,796,864       2,136,544       2,015,232         94 %
 QATTCMD     3,709,952         809,440         536,566         66 %
 QATTCL      8,881,664       3,152,352       2,613,760         83 %
 QATTDDS     1,715,200         530,912         340,480         64 %
 QATTRPG     4,455,424       1,382,880       1,204,736         87 %

    Total   24,559,104       8,012,128       6,710,774         84 %

The following  describes the  compression results on  a version  of the
QATT  source  files at  release  V3R6.   The  RISC  release  requires a
larger size disk page.  All source  files were 92 bytes in length  with
the exception  of QATTRPG  which is 112.   The  compressed size  is the
total of  the 4 files  that make up  a source archive.   INCLUDE(*NONE)
was  specified  on  UPDSRCARC.   Only  a  single version  exists.   The
percent column describes the percentage of the original size.

             ------- Source files --------       -- Source archive ---
             ----- Non - compressed ------       ---- Compressed -----
 File       Mbrs   Records  Avg        Size          Size       Percent
 ----       ----   -------  ---   ---------     ---------       -------

 QATTINFO    510    89,622   176 15,122,432     4,091,904         27 %
 QATTCMD     645    20,419    32 10,665,984     1,380,352         13 %
 QATTCL      797   127,954   161 20,844,544     5,771,264         28 %
 QATTDDS     237    46,384   196  7,290,880     1,814,528         25 %
 QATTRPG     350   115,377   330 17,235,968     4,558,848         26 %

    Total  2,539   399,756   157 71,199,808    17,616,896         25 %

The chart shows that it  may be desirable in some applications  to ship
an archive  rather than  shipping a saved  source file or  a compressed
source  file.    This  will  reduce  media  use  and  provide a  faster
restore.   If  the  source  is  needed in  regular  source  files,  the
overhead of creating  members and 'copying out' the source  can be done
at a later time.

The percentage will vary for the same reasons stated previously.

Individual member control
-------------------------

The  UPDSRCARC command normally operates  on one or  more source files.
An individual member may also  be specified.  This  could be used if  a
programmer  or application  wanted  to  immediately archive  a  changed
member.

For  example, it  is normal for  a programmer  to go  thru a  series of
SEU,  compilation and debug  steps as he  develops a program.   At some
point, a  reasonable  version may  be  reached that  he  would like  to
archive before he makes significant additional changes.

MTNSRCARC  does  the  cleanup  function,  but  will  never  delete  the
current  version.   DLTSRCARCM can  be used to  delete old  versions or
all versions.

Most of  the individual  version functions  can be  specified from  the
WRKSRCARC subfile display.

Re-use of a member name
-----------------------

The UPDSRCARC command captures new or changed members.

If the  member name does not  exist in the  archive for the file  it is
found in, it is considered a new member.

If the  archive member exists, the create date  of the source member is
checked to ensure  that it is  the same as  the original member  stored
in the  archive.  If the  dates differ, it  could be that  a programmer
has re-used a name for a different purpose.

By default,  this member will  be rejected and  a new version  will not
be  created.    The  report  created  by  UPDSRCARC  will  describe the
condition.

There are two methods of allowing the member to be accepted:

  **   A field in  the archive  header (SHALWD) can  be changed.   This
       value  will be  reset when  the new  version is  archived.   For
       more  details,  see  the  section  on  'Archive  header  control
       information'.

  **   The UPDSRCARC  command supports  the CHKCRTDAT  parameter.   The
       command can be  used for either a single member  or all members.

If  the original source  member has been  removed and then  copied back
to the  original source  file (using  CPYSRCARCM), the  create date  of
the new member is updated in the archive header.

Note that the  create date checking is for  the date only and  does not
include the  time.  If a  source member is added,  archived and removed
in  the same day,  the same member  name being added  again on the same
day would not be considered an error.

Version identification
----------------------

The key to  each version in the  archive header file (SRCARHP)  is made
up of:

       Source library
       Source file
       Source member
       Version ID

The  version identification  is in  the form  of CYYMMDDnn.    The date
(with  century) is used and  nn is a consecutive  number beginning with
00 for each  day.  If  you only use  UPDSRCARC once  per day, you  will
only see version IDs that end with 00.

A maximum of  100 versions per day per  source member can be kept.   An
error  occurs on  UPDSRCARC if  you  attempt to  archive more  than the
maximum.  There  is an internal  key assigned to  each version that  is
unique per  archive.   This internal  key allows access  to the  detail
file.   The internal  key is an  11 digit  number which allows  for 100
billion  versions.  If  you made 1000  new versions a  day, the archive
would last for 10,000 days.

If the  maximum is reached,  you must  reload the archive.   You  would
copy out all  of the current versions, clear the  archive files and use
UPDSRCARC again.

Archive header record
---------------------

The  archive header  record  contains fields  that identify  the member
such as:

       Member name and source type
       Source file and library
       Version ID
       Current version code (Y or N)
       Text description
       Number of records
       Source member create date
       Source member change date and time
       Date the version was replaced by a more current version

When a 'copy out' occurs  (CPYSRCARCM), history information is  updated
if UPDHST(*YES) is specified.  The update includes such things as:

       Copy out date and time
       User who did the copy
       Member, file and library copied to
       Number of times a 'copy out' has occurred

There  are other  fields in  the  archive header  record which  provide
control  information.   They  can be  changed  using an  option  on the
WRKSRCARC  subfile  display.     This  allows   you  to  provide   more
information about the member  and to override the options  and defaults
of the archive commands.  These include:

  **   Source owner - Documentation only

  **   Application area - Documentation only

  **   Allow  different create date  - Y/N value  - See the  section on
       'Re-use of a member name'

  **   Allow  source member  to be  removed - Y/N  value -  The N value
       will override the  MTNSRCARC function.   This could be used  for
       source that  you rarely change, but frequently  copy or display.

  **   Minimum  versions  to  retain.   The  default  is  1.    A value
       greater than 1 will  be the minimum kept  regardless of what  is
       specified using MTNSRCARC or DLTSRCARCM.

See  the  section on  'Archive  header  control information'  for  more
details and  how to enter the data.  You can  only make a change to the
current version.   Any  new  versions automatically  pick up  the  same
data  from the  current  version (except  for  the 'allow  diff  create
date' field).

Querying the archive files
--------------------------

Two basic functions are provided:

  **   PRTSRCARC  performs a basic  printing function of  either totals
       (by  file)  or detail  (by  version).   Selection  options exist
       such as  a simple method  of determining  all members that  have
       changed since a specific date.

  **   SCNSRCARC does  a scan  function against the  compressed source.

You  can  query  or write  programs  to read  the  archive  header file
(SRCARHP).  It is an externally described file.

For  example,  if  you  have  entered  the  optional  'application'  or
'owner'  fields, you  can sort  the data  by application  or owner  and
report  on changes, source  in existence etc.   Normally you  will only
want to work with the current versions (SHVERC = Y).

An example of  a CL  program processing the  SRCARHP file  is shown  in
the section on 'Recovery'.

The detail file  (SRCARDP) has the  compressed source and  is therefore
difficult  to program  against.   See the  section on  the 'Compression
Algorithm'.

Change date for UPDSRCARC
-------------------------

The  Update command adds a new version if  the member does not exist or
the  change date  and  time of  the  member  differs from  the  current
version in the archive.

There  are two  change  dates associated  with  a source  member.   The
'source last change date' is set by SEU.  This date is not used.

The  system change date for  each member is set  whenever the member is
closed after  an update operation.   The  change date  also changes  if
other operations  at the file level  impact the members.   For example,
if you  grant authority to a  source file, all the  member change dates
will change.  This will cause all  the members to be archived as a  new
version even  though the  data has not  changed.   A restore  will also
change  the change  date.   The special  command SYNSRCARCM  can assist
you in synchronizing the source archive to the actual source.

Commands
--------

CRTSRCARC (Create Source Archive) command             *CMD
-----------------------------------------

The  CRTSRCARC  command  creates  the  archive  files  in  a  specified
library.   The files  SRCARHP, SRCARDP,  SRCARHL, and  SRCARHM will  be
created.

There is  no corresponding DLT command.   See the  section on 'Deleting
a source archive'.

Other  objects can be  in the same  library as an archive.   The source
files being archived do not have to be in the same library.

A typical command would be:

        CRTSRCARC     SRCARCLIB(llll)

   SRCARCLIB     The  library  where  the   archive  files  should   be
                 created.

UPDSRCARC (Update Source Archive) command             *CMD
-----------------------------------------

The UPDSRCARC  command is  intended to  be run  one or  more times  per
day.   Any  new members  (meaning  unknown to  the archive)  or changed
members (based on the  member change date and  time) will be  archived.
The first time  a source file is  specified, all members in  the source
file  will be archived.   Subsequent use  of UPDSRCARC archives  new or
changed members.

UPDSRCARC should be submitted to batch.

One  or more  source files from  multiple libraries may  be archived to
the same  archive.   However,  each use  of the  UPDSRCARC command  can
specify only one library for the source files.

A printed report is output describing the totals by source file.

Note  that UPDSRCARC  only adds  to  the archive.   No  cleanup of  old
versions occurs with UPDSRCARC.

An  option is provided  to let you  capture the  sequence number and/or
the change date which is part of each source record.

Only one user at  a time may  use UPDSRCARC on  the same archive.   The
command  cannot be  used  when  MTNSRCARC is  in  process  on the  same
archive.

There  is no enforced link  between a source  file and an  archive.  It
is possible to archive the same  source file to different archives  and
there are valid reasons for  this.  A member stored in  an archive does
not have to be 'copied out' to its original source file.

Once you  set your strategy, you should run  the UPDSRCARC command in a
CL program for consistent execution.

A typical command would be:

       UPDSRCARC     SRCFILE(QCLSRC QDDSSRC QRPGSRC ...)
                       SRCLIB(llll)

   SRCFILE       Up  to  300 source  file names  to  be archived.   All
                 files must be in the  same library for each use  of an
                 UPDSRCARC  command.   The  special  value *ALL  allows
                 all source files in a library to be archived.

   SRCLIB        The library where the source files are located.

   MBR           The  member name to be archived.   *ALL is the default
                 meaning all members in the  source files named.  If  a
                 single  member is  named,  only a  single source  file
                 may be named.

   SRCARCLIB     The  library  containing  the  source  archive  files.
                 The default is *LIBL.

   INCLUDE       Whether to  include  the sequence  number  and  change
                 date fields from  the individual source records.   The
                 default  is *NONE meaning  they will not  be included.
                 *SEQNBR   may   be  specified   meaning   include  the
                 sequence  number in  the  archived version.    *CHGDAT
                 specifies  to   include  the   change  date.     *BOTH
                 specifies to include both values.

                 Note:  If  you  are  archiving  S/38  Text  Management
                 members  which  contain  highlighting  or  underscore,
                 you must include  at least the sequence  number.  Text
                 management  keeps   a  second  record  with  the  same
                 sequence   number   which    contains   the    special
                 characters  needed.     The  second  record   is  only
                 recognized properly  if it contains  the same sequence
                 number.

                 If  the change  date is  not included  in the archived
                 version, a  'copy  out'  will generate  zeros  in  the
                 field.   If  the sequence  number is  not  included in
                 the  archived  version,  a  'copy  out'  will generate
                 consecutive numbers (1.00,  2.00 etc.)  in the  field.

                 Each time  a version  is archived,  the INCLUDE  value
                 from   UPDSRCARC  is  captured.     Therefore,  it  is
                 possible for  the  same  member  to  be  'copied  out'
                 differently   depending  on   how   the  version   was
                 archived.

   CHKCRTDAT     A  *YES/*NO value  that  defaults to  *YES  meaning to
                 ensure  the  create date  in  the archive  matches the
                 create date of the  member.  If *YES is  specified and
                 a  mismatch occurs, an  error will  be reported  and a
                 new  version  will not  be created.    If you  want to
                 archive the  mismatch, *NO  must be  specified or  you
                 can change the  archive header record SHALWD  field to
                 Y.

                 A  good use of  the *NO option  is if you  must change
                 your library  structure  or restore  source  that  has
                 already been archived,  but the source members  do not
                 exist  in the source  file.   This will  cause massive
                 changes  to  the  create  dates  and  many  errors  if
                 CHKCRTDAT(*YES) is specified.

                 Only  the create  date  (not  the  time)  is  used  to
                 perform the check.

MTNSRCARC (Maintain Source Archive) command           *CMD
-------------------------------------------

MTNSRCARC performs  cleanup on both  the source archive and  the source
members.   It would be normal to  delete several archive versions based
on the  command  parameters  and fields  in  the archive  header.    By
default, any  members which have  not been changed  in 60 days  will be
removed from the source files.

MTNSRCARC should be submitted to batch.

The  current   version  in  the  archive  will   never  be  deleted  by
MTNSRCARC.

Be sure  you  understand the  section  on 'Retention  strategy'  before
entering the command.

The MTNSRCARC  command is  intended to be  run weekly  or monthly.   It
can be run  daily if you have excess  machine cycles and are interested
in keeping disk space used at a minimum.

Because  the  archive files  will  normally have  many  deleted records
after MTNSRCARC  is in process,  a command option  allows the files  to
be reorganized to reclaim the deleted record space.

A  report is  output describing  versions which  have been  deleted and
the source members which have been removed.

Only  one user  at a time  may specify  MTNSRCARC on  the same archive.
MTNSRCARC requires an *EXCL lock on the two archive files.

A typical command would be:

        MTNSRCARC

Note that the  typical command uses  the defaults.   Be sure to  review
the section on 'Retention strategy'.

   VERDAYS       The  number  of  days  to  keep  old  versions.    The
                 default  is  60.   *MAX  may be  specified.    See the
                 section on 'Retention strategy'

   MAXVERS       The maximum number  of versions  to keep  for any  one
                 member.  *MAX  may be specified.   See the  section on
                 'Retention strategy'.

   SRCDAYS       The number  of days to keep  unchanged source members.
                 The  default is  60.  *MAX  may be specified.   If the
                 member has  not been  changed in  the days  specified,
                 it would  be removed.   See the section  on 'Retention
                 strategy'.   The  USECHK parameter can  also influence
                 the removing of members.

   USECHK        A  *YES/*NO  value  that   defaults  to  *NO.     *YES
                 specifies to  use the  most current  date between  the
                 last  'use  date'  or  the  last  'change  date'  when
                 comparing  against   the  date   generated  from   the
                 SRCDAYS parameter.

   PRTDLT        A *YES/*NO  value that defaults  to *YES  which causes
                 one  line  of  print  for  every version  deleted  and
                 every  member  removed.   An entry  of *NO  avoids the
                 detail lines and provides totals only.

   SRCFILE       The qualified source file  name in the archive.   Both
                 the file  and the library default to  *ALL meaning all
                 files in the archive will be processed.

                 Either  value may be  a specific name.   If a specific
                 file or library  is named,  all versions not  matching
                 the names are bypassed.

                 The purpose  of a  specific name  is to  allow you  to
                 have  different  retention criteria  depending  on the
                 source  file  or  library.    If  this  is  done,  you
                 probably want  a  CL program  with multiple  MTNSRCARC
                 commands (one  per source file or  source file library
                 to  be  maintained).   Only  the  last  command should
                 specify RGZPFM(*YES).

   SRCARCLIB     The  library  containing  the  source  archive  files.
                 The default is *LIBL.

   RGZPFM        A  *YES/*NO  value that  defaults  to  *YES.   A  *YES
                 value  will cause both  the SRCARHP  and SRCARDP files
                 to  be  reorganized.    This  will  eliminate  deleted
                 record space after deleting excess versions.

MTNSRCARC2 (Maintain Source Archive) command 2        *CMD
----------------------------------------------

MTNSRCARC2  offers an  alternative  approach to  removing members  from
the  archive.  MTNSRCARC2 performs  cleanup on only  the source archive
(source members  are never  removed).   It would  be normal  to  delete
several archive  versions based  on the  command parameters and  fields
in  the archive  header.   MTNSRCARC2  removes any  old  source archive
versions  if the  current version is  older than a  specified number of
days or the  maximum number of versions  (as specified on the  command)
has been reached.

For example, assume  that you have a single version of  a member and it
is  1 year  old.   If you  change the  member, a  new version  would be
entered into the archive by the  UPDSRCARC command.  You may choose  to
retain any  old versions  for some  period of  time based  on the  fact
that the  current version has been recently  changed.  When the current
version has  aged,  it is  safe  to remove  any  prior versions.    The
default for MTNSRCARC2 is  60 days of aging.  Once  the current version
is 60 days old, running MTNSRCARC2 will remove all older versions.

MTNSRCARC2 should be submitted to batch.

The  current   version  in  the  archive  will   never  be  deleted  by
MTNSRCARC.   nor will any  versions that are less  than or equal to the
minimum number of versions requested.

Be sure  you  understand the  section  on 'Retention  strategy'  before
entering the command.

The MTNSRCARC  command is  intended to  be run weekly  or monthly.   It
can  be run daily if you have  excess machine cycles and are interested
in keeping disk space used at a minimum.

Because the  archive  files will  normally  have many  deleted  records
after MTNSRCARC2  is in process, a  command option allows the  files to
be reorganized to reclaim the deleted record space.

A  report is  output describing  versions which  have been  deleted and
the source members which have been removed.

Only one user  at a time  may specify MTNSRCARC2 on  the same  archive.
MTNSRCARC2 requires an *EXCL lock on the two archive files.

A typical command would be:

        MTNSRCARC2

Note that  the typical command  uses the defaults.   Be sure  to review
the section on 'Retention strategy'.

   MAXVERS       The maximum  number of versions to keep.   The default
                 is  10  meaning if  there are  more than  10 versions,
                 the excess  will  be deleted  regardless  of when  the
                 current version  was changed.  *MAX may  be entered to
                 cause  deletions  only  on the  basis  of  the AGEDAYS
                 parameter.

                 The minimum  number of  versions as  specified in  the
                 archive member  header takes  precedence over  MAXVERS
                 for any member.

   AGEDAYS       If  the current  version is older  than the  number of
                 days  specified,  any   remaining  versions  will   be
                 deleted.   The  default is  60.   See  the section  on
                 'Retention strategy'

   PRTDLT        A  *YES/*NO value that  defaults to *YES  which causes
                 one  line  of  print  for  every  version  deleted and
                 every member  removed.   An  entry of  *NO avoids  the
                 detail lines and provides totals only.

   SRCFILE       The qualified  source file name in the  archive.  Both
                 the  file and the library default  to *ALL meaning all
                 files in the archive will be processed.

                 Either value may  be a specific name.   If a  specific
                 file or  library is  named, all versions  not matching
                 the names are bypassed.

                 The  purpose of  a specific  name is  to allow  you to
                 have different  retention  criteria depending  on  the
                 source  file  or  library.    If  this  is  done,  you
                 probably  want a  CL program  with  multiple MTNSRCARC
                 commands  (one per source file  or source file library
                 to  be maintained).    Only  the last  command  should
                 specify RGZPFM(*YES).

   SRCARCLIB     The  library  containing  the  source  archive  files.
                 The default is *LIBL.

   RGZPFM        A  *YES/*NO  value  that defaults  to  *YES.    A *YES
                 value will cause  both the  SRCARHP and SRCARDP  files
                 to  be  reorganized.    This  will  eliminate  deleted
                 record space after deleting excess versions.

WRKSRCARC (Work Source Archive) command               *CMD
---------------------------------------

WRKSRCARC  provides the  working display  for archived  source.   A sub
file is used with one line per version.

The archive is kept in the sequence of:

       Source library
         Source file
           Source member
             Version ID (descending sequence - therefore the current
               version is always first)

WRKSRCARC supports two forms of selection and both can be combined:

  **   A starting  location  within  the  archive.    The  ARCFILE  and
       ARCMBR parameters  can  be used  as a  start  position to  start
       reading the  archive header records into the  subfile.  The same
       fields  exist  at  the  top  of  the  display  to  allow  you to
       randomly position  within the  archive.   The entries  act as  a
       'set  lower limit'.   If the  first record  read does  not match
       the  request  on  the  command or  the  top  of  the  display, a
       warning message appears on the display.

  **   Selection fields allow you to  fill the subfile with records  of
       a specific  source type, those that  match a scan of  the member
       name, those  that match the scan of  the member text description
       or those with  a version greater  than or equal  to a  specified
       date.   This allows a  variety of  combinations to be  specified
       such as:

          All RPG members that have been changed since 0901231.

          All CL members that have UPD anywhere in the member name.

          All CBL members that have MAINTAIN in the member text.

The two  forms of selection  can be combined.   For example,  you could
request  a starting  location and  then search  for all members  with a
value in the member name.   Specifying a starting value for  the search
improves the performance.

The display  appears in one of  two modes - 'current  versions' or 'all
versions'.   'Current  versions'  appears first.   F11  can be  used to
toggle between the two modes.

The subfile  is  filled  one  page  at a  time.    Multiple  files  and
libraries may appear on the same page.

Options on the display allow:

  2    Change  the header.   Allows  you to  modify the  fields in  the
       header  that allow  additional documentation  and control.   See
       the section on 'Archive header control information'.

  4    Delete.   Prompts for  the  DLTSRCARCM command.   You  can  only
       delete  a single  version  or  all  versions with  this  option.
       Because  the  versions are  considered  in a  chain,  deleting a
       single  version is only  valid if it  is the last  version for a
       member.  You  can only delete all  versions when the display  is
       the 'current version' mode.

  5    Display  the header.   Displays  all the  fields in  the archive
       header record.  There are 2 displays.

  6    Display  the source.    Uses the  DSPSRCARCM command  to display
       the source.

  7    Print  the   source.     Uses   the  DSPSRCARCM   command   with
       OUTPUT(*PRINT) to print the source.

  8    Copy out.   Prompts for  the CPYSRCARCM command  with pre-filled
       values.   You can modify  where the version is  to be copied to.

  9    Delete non-min.   This  option can  only be  specified when  the
       display  is   in  'current  version'   mode.    It   causes  all
       non-minimum  versions (as  specified in  the archive  header) to
       be deleted.

  R    Reset  to top.   This  option causes  the member selected  to be
       re-displayed at  the top of  the display and  the fields at  the
       top to  be reset.   This allows you  to reset to a  new starting
       point  instead of  keying the  member, file  and library  on the
       top of the display.

       This also provides  a quick method  of determining which  source
       library and file are being displayed.

A typical command would be:

         WRKSRCARC

   ARCFILE       The qualified  archived source  file to  be displayed.
                 The default  is *FIRST for both  the file and library.
                 Both defaults  would  cause  the  subfile  display  to
                 occur for the first  file found in the archive.   This
                 entry acts  as a 'set lower limit'.   The names do not
                 have  to match an  existing archived version.   If you
                 specify *FIRST  for the  library and  a specific  file
                 name, the  file name is ignored and  a message appears
                 on the initial display.

   ARCMBR        The  member to  be displayed.   The default  is *FIRST
                 meaning the  first member  in the  ARCFILE  parameter.
                 The entry  acts as  a 'set  lower limit'  and is  only
                 meaningful  if  both a  library and  source  file have
                 been entered.   If you  do not specify  a library  and
                 file, the  member name will  be ignored and  a message
                 appears on the initial display.

   SRCTYP        The  source  type to  be  searched.    The default  is
                 *ALL.   The value entered must  match a source type in
                 the  file  (e.g.    CLP,  RPG).     Only  the  current
                 versions  that  match the  selection  will  be in  the
                 subfile.

   SCAN          The  value (argument or string) to  scan.  The default
                 is *NONE.   The  scan function  always translates  the
                 value in  the data  base record  to upper case  before
                 making a  comparison.  Therefore you  should not quote
                 the value and enter lower  case.  You can scan  either
                 the member name  or the member text  description based
                 on the SCANTYPE parameter.

   SCANTYPE      The  type  of  scan  to  be  used.    The  default  is
                 *MBRNAME  to  scan  the  member  name.    An  entry of
                 *MBRTEXT will scan the  member text field.  The  value
                 is ignored if SCAN(*NONE) is specified.

   FROMDATE      The  FROM  date for  the  version  create  date.   The
                 default  is *BEGIN  meaning  the beginning  version in
                 the  file.    This  searches  all  versions.    If   a
                 FROMDATE is  entered it must  be in the  form CYYMMDD.
                 Only  the versions created  on or after  the date will
                 appear in the  subfile.   This allows  a quick  method
                 of  reviewing   the  recently   added  versions   (the
                 members that have recently changed).

   SRCARCLIB     The  library  containing  the  source  archive  files.
                 The default is *LIBL.

SCNSRCARC (Scan Source Archive) command               *CMD
---------------------------------------

SCNSRCARC  provides a  scan of  the current  versions of the  source in
the archive.    A string  (argument) is  specified to  scan  for and  a
report is  printed identifying all the  members that have at  least one
use  of  the string.   Options  are  provided to  limit  the scan  to a
specific file, library or source type.

SCNSRCARC should be submitted to batch.

There is  no  restriction regarding  the case  where  the value  to  be
scanned for  spans two records  in the archive  detail file.   The last
20  bytes  of   each  record  (maximum  length  of  the  argument)  are
concatenated as the first 20 bytes  of the next record before the  scan
occurs.

The scan performance  is usually very  good considering other  types of
source scans.  This is due to:

  **   A  single  member  exists and  therefore  only  one open  occurs
       rather than opening each member to be scanned.

  **   More  bytes  can be  scanned in  one  function than  with normal
       source.

A typical command would be:

      SCNSRCARC   ARGUMENT(PAYROLL) SRCTYP(CLP)

   ARGUMENT      The argument  to scan  for.   Up  to 20  bytes may  be
                 specified.   The argument must  not contain 2  or more
                 consecutive   blanks   or   2   or  more   consecutive
                 asterisks.   Blanks at  the end  of  the argument  are
                 automatically trimmed off.

   ARCFILE       The qualified name  of the source file  and library in
                 the archive to scan.  Both values default to *ALL.

   SRCTYP        The  source type  in  the archive  to scan  for.   The
                 default is *ALL meaning all source types.

   SRCARCLIB     The  library  containing  the  source  archive  files.
                 The default is *LIBL.

   TRANSLATE     A *YES/*NO  value that  defaults to  *NO.  Enter  *YES
                 to   translate  the  source   to  upper   case  before
                 scanning the data.

PRTSRCARC (Print Source Archive) command              *CMD
----------------------------------------

PRTSRCARC   provides  a  basic  printing   function.    Two  forms  are
supported:

   *TOTAL        Provides  one  line of  output  per  source  file  and
                 describes the number of members and versions.

   *DETAIL       Provides one  line of output per  member and describes
                 the  number of versions,  the current  version and its
                 number of records and text description.

Selection criteria can be specified  to limit the output to a  specific
file,  library,  source  type  or  within a  date  range.    Using  the
FROMDATE  parameter  provides  a simple  means  of  printing all  those
members that have changed since the  specified date.  A summary  occurs
for the archive  files describing the  size, the number of  records and
the number of deleted records.

A typical command would be:

       PRTSRCARC

   OPTION        The  printing  option.    *TOTAL  is the  default  and
                 prints  one  line per  source  file.   *DETAIL  may be
                 specified to print one line per member.

   ARCFILE       The qualified name of  the source file and library  in
                 the archive  to print.   Both values default  to *ALL.

   FROMDATE      The  FROM date for  selection.  The  default is *BEGIN
                 which  means  the  earliest  date  in  the  file.    A
                 specific  date  must   be  entered  in  the   form  of
                 CYYMMDD.     If  a  specific  FROMDATE  is  used  with
                 TODATE(*CURR), a  member will  either have  a  current
                 version or no  version will be  found.  The  number of
                 versions  will be those  found within the  date range.

   TODATE        The  TO  date for  selection.   The  default  is *CURR
                 which means the  current date.   A specific date  must
                 be  entered in  the form  of CYYMMDD.   If  a specific
                 value  is  entered it  might not  include  the current
                 version for  one  or  more members.    Therefore,  the
                 column  of   version  numbers  will  be   the  'latest
                 version'  and may  not be  the  current version.   The
                 number of versions  will be  those found  in the  date
                 range.

   SRCTYP        The  source  type  in  the  archive  to  print.    The
                 default is *ALL meaning all source types.

   SRCARCLIB     The  library  containing  the  source  archive  files.
                 The default is *LIBL.

DSPSRCARCM (Display Source Archive Member) command    *CMD
--------------------------------------------------

DSPSRCARCM  displays or prints a  version that is in  the archive.  The
compressed source is  decompressed to a  file in QTEMP.   If a  display
is requested,  the SEU  'display only' function  is used.   If printing
is requested, the TAA tool PRTSRCF is used with 132 wide output.

DSPSRCARCM  would normally be  entered as an option  from the WRKSRCARC
subfile display.  Two options  are provided to either print or  display
the source.   If  the command  is entered  directly, a typical  command
would be:

        DSPSRCARCM    ARCMBR(mmmm) ARCFILE(llll/ffff)

   ARCMBR        The archive member to be displayed.

   ARCFILE       The  qualified  archived  source  file containing  the
                 member.   Both  the file  name  and the  library  name
                 must be entered.

   SRCARCLIB     The  library  containing  the  source  archive  files.
                 The default is *LIBL.

   VERSION       The  version to be  displayed.   The default  is *CURR
                 meaning  the current version.   If a specific value is
                 entered, it must be in the form CYYMMDDnn.

   OUTPUT        Whether to print or  display the member.   The default
                 is  * which  has the  same  meaning as  on system  DSP
                 commands.   *PRINT may  be entered  to cause printing.

CPYSRCARCM (Copy Source Archive Member) command       *CMD
-----------------------------------------------

CPYSRCARCM 'copies  out'  the source  (from  the  archive to  a  source
member).   You can  'copy out' any  version, a  generic member  name or
all members  for a file.   The archive source is  decompressed and then
written to the source member.

If generic or all  members are 'copied out',  only the current  version
is copied  for  each member.   You  must specify  REPLACE(*YES).   This
operates  like  CPYSRCF in  that  if the  member  exists, the  existing
source is cleared.  If the member does not exist, it is added.

If  the source member does  not exist, the source  member is added with
the source type that existed when the version was archived.

The default is to  'copy out' to the  original source file and  member.
You can specify  a different source file or member.   CPYSRCARCM can be
entered  as an option from the WRKSRCARC  subfile display.  The command
prompt would  appear  with  most of  the  values pre-filled.    If  the
command is entered directly, a typical command would be:

          CPYSRCARCM    ARCMBR(mmmm) ARCFILE(llll/ffff)

If CPYSRCARCM fails, consider the use of RCLSRCARCM.

See the section on  'Recovery' for an example of how to  'copy out' all
current versions created after a specific date.

   ARCMBR        The  archive member to  be copied out  of the archive.
                 A specific member, a generic  member name or *ALL  may
                 be   entered.     If  *ALL   or   generic  are   used,
                 VERSION(*CURR)  and REPLACE(*YES)  must  be specified.

   ARCFILE       The  qualified  archived  source  file  containing the
                 member.   Both  the file  name  and the  library  name
                 must be entered.

   SRCARCLIB     The  library  containing  the  source  archive  files.
                 The default is *LIBL.

   VERSION       The  version  to  be 'copied  out'.    The  default is
                 *CURR meaning  the current  version.   If  a  specific
                 value is  entered, it must  be in the  form CYYMMDDnn.

   TOMBR         The  source member to  be copied  to.  The  default is
                 *ARCMBR  meaning  the   same  value   as  the   ARCMBR
                 parameter.   If  ARCMBR  is a  generic  name or  *ALL,
                 TOMBR(*ARCMBR) must be specified.

   TOSRCFILE     The qualified  source file name to be  copied to.  The
                 default  is  *ARCFILE  meaning the  same  name  as the
                 ARCFILE parameter.

   REPLACE       A *YES/*NO value  that defaults to  *NO.  The  default
                 will only  cause the command  to operate when  the 'to
                 member'  does not  exist.   This prevents  a potential
                 error from  occurring.   *YES will  cause an  existing
                 member to  be cleared first  (if no member  exists, it
                 would be added).

                 If  a  generic  member  or  *ALL  members are  copied,
                 REPLACE(*YES) must be specified.

   UPDHST        A  *YES/*NO  value  that  defaults  to  *YES.     This
                 determines whether the  archive header record  will be
                 updated  with  the  copy  information (who,  when,  to
                 what   file).    The   *NO  value  can   be  used  for
                 application  functions   such   as  DSPSRCARCM   which
                 perform only a temporary copy.

                 If  the user has  only *USE  authority to  the SRCARHP
                 file   (archive  header),  only   UPDHST(*NO)  may  be
                 specified.  See the section on 'Security'.

SYNSRCARCM (Synchronize Source Archive Member) command  *CMD
------------------------------------------------------

SYNSRCARCM synchronizes what  is in  the archive to  the source  files.
It is designed for two typical uses:

  **   In  a disaster  recovery situation  where the  source files  are
       restored,  but  are  not  as  current  as  the  source  archive.
       Because the restore  causes the  change date to  be changed,  it
       would appear that all  of the source members have  changed.  See
       the discussion of disaster recovery.

  **   If the  source file is moved, or restored  or GRTOBJAUT is used,
       all  of  the  source  members  are  considered  changed  by  the
       system.   If  UPDSRCARC is  run, all  members  will be  updated.
       You  can  use SYNSRCARCM  to  recover  from  this situation  and
       prevent  a  massive update  that might  down  level some  of the
       data in the archive.

SYNSRCARCM requires  that  you specify  a  synch date  (SYNDATE  parm).
This date is  used to compare against  the members in the  archive.  If
the  SYNDATE value is less  than or equal to  the current version date,
the current  version  is  copied  out of  the  archive  (CPYSRCARCM  is
used).  If the member  does not exist in the source file,  it is added.

If the  SYNDATE value is greater  than the current version  date in the
archive  and  the member  does  not exist  in  the source  file,  it is
ignored  (this  is  probably   a  member  that  has  been   removed  by
MTNSRCARC).   If  the member  does  exist, a  simulation of  CPYSRCARCM
occurs.    This  means  that the  archive  header  for  the  version is
updated as if it had been copied  out to a member.  The change date  of
the source  member is  used as the  latest change  date in  the current
version.    This  prevents  the  source  member from  being  considered
changed the next time UPDSRCARC is run.

A typical command would be:

         SYNSRCARCM    SYNDATE(0050801)

This would cause  synchronization of  the archive to  the source  file.
All current versions equal  to 0920801 or greater would  be copied out.
All  current versions that  have a  corresponding source  member (still
exists)  would be updated  as if a  'copy out' had  occurred.  The user
name for the 'copy out' is updated as *SYNSRCARC.

When the  command completes,  the completion  messages contains  totals
of the actions performed.

   SYNDATE       The  synchronization date  to  be used.    It must  be
                 entered in the form CYYMMDD.

   ARCFILE       The  qualified  archived  source  file containing  the
                 member.   *ALL is the  default.   If *ALL  is used,  a
                 specific  library cannot  be  used.   If  *ALL is  not
                 used, the library name must be entered.

   SRCARCLIB     The  library  containing  the  source  archive  files.
                 The default is *LIBL.

DLTSRCARCM (Delete Source Archive Member) command     *CMD
-------------------------------------------------

The normal method  of deleting old  versions from the  archive is  with
the MTNSRCARC  (or MTNSRCARC2) command.   MTNSRCARC provides  a cleanup
of the entire archive, but will never delete the current version.

DLTSRCARCM  can  be  used to  delete  one  or  more  versions from  the
archive  for a  named member,  a generic  member or  all members.   You
must use DLTSRCARCM if you want to delete all versions of a member.

The versions in the archive  for a given member are considered  a chain
of  versions.   You cannot  delete  a version  from the  middle of  the
chain.   You can only delete off the  end of the chain (oldest version)
for either one or multiple versions.

You cannot delete a  version if the header  record has been changed  to
request a  minimum number of  versions and the  version you  attempt to
delete  is within  that minimum.    For example,  assume that  you have
changed the  header record  SHMINV field  to specify  5  versions.   If
there are  6  versions in  the archive,  you  can only  delete the  6th
version (the oldest one).

An  option  on  the  command  allows  you  to  delete  all  non-minimum
versions   based  on  the  SHMINV  value.    You  can  also  specify  a
non-current  version  ID  and  request  that  both  it  and  any  older
versions  be   deleted.    Generic   members  or  all  members   for  a
library/file may be specified.

A typical command would be:

         DLTSRCARCM    ARCMBR(mmmm) ARCFILE(llll/mmmm)
                         VERSION(090123100)

There are two methods of deleting all the versions of a member.

  **   If  you  are entering  a  command and  do not  know  the version
       number, specify:

           DLTSRCARCM    ARCMBR(mmmm) ARCFILE(llll/mmmm) VERSION(*ALL)

  **   If you are  operating from  the WRKSRCARC  display, specify  the
       delete option  for the  current version (This  can be  done when
       the  'current' versions are  being displayed).   When the prompt
       appears, all  parameters will  be pre-filled  except the  ALLVER
       parameter.  Enter *YES to delete all.

The parameters are:

   ARCMBR        The archive member  to be deleted out of  the archive.
                 Depending on  other parameters, you  can either delete
                 specific versions or all versions in the archive.

                 A  generic name may be  entered to provide for cleanup
                 of multiple  members.   *ALL may be  specified if  you
                 want to operate on all members in a library/file.

                 If you  have an archive for multiple  files and decide
                 to   stop  archiving  one  of   the  files,  MBR(*ALL)
                 ALLVER(*YES) can  be  specified  to  drop  the  entire
                 file (all versions  of all members) from  the archive.

   ARCFILE       The  qualified  archived  source  file containing  the
                 member.   Both  the file  name  and the  library  name
                 must be entered.

   VERSION       The version  to be deleted.   If  a specific value  is
                 entered, it must be in the form CYYMMDDnn.

                 *NONMIN  may be  entered  to delete  all  members that
                 are  not required by  the SHMINV value  in the archive
                 header record.   See  the section  on 'Archive  header
                 control  information'.   The default  for the  archive
                 header record is 1 version.

                 *ALL   may   be  entered   to   delete   all  versions
                 (including the current version).

                 *NONE is a special value  intended for the case  where
                 DLTSRCARCM  is being  used  repeatedly and  SETLR(*NO)
                 is  used  to  keep the  files  open.    A *NONE  value
                 causes  the  program  to  close  the  files  and   end
                 immediately.  SETLR(*YES) must be specified.

   ALLOLDER      A *YES/*NO  value that defaults  to *NO.   If *YES  is
                 entered,  any  older versions  will  also be  deleted.
                 *YES  is only valid if a  specific version ID has been
                 named and it is not the current version.

   SRCARCLIB     The  library  containing  the  source  archive  files.
                 The default is *LIBL.

   ALLVER        A  *YES/*NO value  that  defaults to  *NO.   *YES  can
                 only  be specified when a  specific version number has
                 been entered  and  it is  the  current version.    The
                 intent  of the  *YES value  is to  allow for  deletion
                 from   the  WRKSRCARC   display  when  you   want  all
                 versions to be deleted.

   SETLR         A *YES/*NO  value  that defaults  to  *YES.   The  *NO
                 value  is   intended   for  those   cases  where   the
                 DLTSRCARCM  command will  be used  repeatedly  and the
                 program  and  files should  remain open.   To  end the
                 program, use VERSION(*NONE).

RTVSRCARCD (Retrieve Source Archive Member Description)  *CMD
-------------------------------------------------------

RTVSRCARCD allows the  information from a  source archive member to  be
retrieved.   The command  can only be  used in a  CL program  and works
like any RTV command.

A typical command would be entered as:

       RTVSRCARCD    ARCMBR(xxx) ARCFILE(xxx) RTNVER(&RTNVER)

The  command  would  return the  version  ID (the  date  added)  of the
current version of the member specified.

The parameters are:

   ARCMBR        The member name in the archive.

   ARCFILE       The qualified  file name  of the  source  file in  the
                 archive.

   VERSION       The  version  of the  member  to  be retrieved.    The
                 default is *CURR for the current version.

                 The  special  values *PRV1  - *PRV20  may  be entered.
                 For example, *PRV1  means the  first version  previous
                 to  the  current  version,  *PRV2   means  the  second
                 version previous to the current version.

                 *LAST may  also be specified to mean  the last version
                 (oldest) in the archive.

   RTNTYP        The  type of version  to be returned.   The default is
                 *NAMED meaning the  version specified for  the VERSION
                 parameter.

                 *PRV  may be  specified to  mean the  version previous
                 to  the one specified for the  VERSION parameter.  For
                 example,   if   VERSION(*CURR)   is   specified   with
                 RTNTYP(*PRV),  it  is  the  equivalent  of  specifying
                 VERSION(*PRV1).   *PRV may be helpful  when a specific
                 version is known and  the previous version is  needed.
                 If the  previous version  does not  exist, TAA9892  is
                 sent as an escape message.

   SRCARCLIB     The  library of the  source archive.   The  default is
                 *LIBL.

The  other  parameters  supported are  return  variables  providing the
information about  the member requested.   You  can see the  parameters
and the  required attributes of  the return variables by  prompting for
the command.

RCLSRCARCM (Reclaim Source Archive Member) command    *CMD
--------------------------------------------------

The  Reclaim  Source  Archive member  command  is  intended  for damage
conditions.   It should rarely  be needed.   CPYSRCARCM  is the  normal
method of 'copying out' of the archive.

If  the  header record  is  destroyed,  but  the details  still  exist,
CPYSRCARCM  cannot be used.   If CPYSRCARCM finds  unexpected values in
the compressed source, it will fail.

RCLSRCARCM is designed to 'copy out' whatever it can.

To use  RCLSRCARCM you  must know  the internal  key to  the  record(s)
that make up  the member in  the SRCARDP file.   DSPPFM can be  used to
find the  source you are looking  for.  If the first  record exists for
the  member, you can  use the scan  function of DSPPFM  to locate it by
scanning for  the member name.   Be  sure you  have the proper  version
(there may be multiple versions in the file).

The  key is  the  first 6  bytes (11  packed  digits).   A  member will
normally  be made up  of multiple records  which contain  the same key.
The key  which  is  the largest  number  for  the same  member  is  the
current version.   Use F10 from the  DSPPFM display to show  the key in
hexadecimal format.

Once  you determine the  internal key, you  need to have  a source file
and member in existence  to reclaim the source  into.  RCLSRCARCM  will
add records  to the source  file member (it  does not clear  the member
first).

RCLSRCARCM supports  the same INCLUDE  parameter as on  UPDSRCARC.  The
value  stored  with  the  source  is ignored  and  the  value  from the
command is  used.   This determines  how  the source  will be  written.
You  need to  look  at the  source  you want  to  reclaim to  determine
whether  it  was stored  with  the  sequence number  and/or  the change
date.

A typical command would be:

     RCLSRCARCM    KEY(5032) TOFILE(llll/ffff) TOMBR(mmmm)

The parameters are:

   KEY           The internal  key  to  the version  to  be  reclaimed.
                 See  the previous  discussion about  how to  determine
                 the key.  The leading zeros may be omitted.

   TOFILE        The  qualified name of  the source file  to be written
                 to.  The library defaults to *LIBL.

   TOMBR         The member name  to be  written to.   The member  must
                 exist and  records are added  to any  existing records
                 in the member.

   SRCARCLIB     The  library  containing  the  source  archive  files.
                 The default is *LIBL.

   INCLUDE       Whether  to  include  the sequence  number  and change
                 date  fields from  the  archive.   This  is  the  same
                 parameter as  on UPDSRCARC.   The  control information
                 stored  in the archive  that describes  how the source
                 was archived is ignored.   The data may exist, but  if
                 the control  information does not  (or is  not valid),
                 the  'copy  out' function  cannot  distinguish between
                 the data  and  actual  source characters.    You  must
                 specify the value  to reflect what is stored  with the
                 detail records in the archive.

                 The  default is  *NONE  meaning the  archive  does not
                 contain  either  the sequence  number or  change date.
                 *SEQNBR  may   be   specified  meaning   the   archive
                 contains  the  sequence   number  on  each  statement.
                 *CHGDAT   specifies  that  the  archive  contains  the
                 change date on  each statement.   *BOTH specifies  the
                 archive contains both values.

                 It may be  necessary to re-run the  RCLSRCARCM command
                 with a  different value for INCLUDE  after you see the
                 source that is output.

CMPSRCARCM (Compare Source Archive Member) command    *CMD
--------------------------------------------------

The Compare  Source Archive  member command  compares two  versions  of
the same member in  the archive, a range of versions  (one spooled file
per comparison),  or the actual source member against  a version in the
archive.     Special   values  exist   to  assist   in  specifying  the
versions/member to be compared.

TAA9891 is  sent  as an  escape message  if the  versions  differ.   If
CMPVERRNG(*YES)  is  specified,  no  escape message  occurs  (you  must
check the spooled files for any differences).

   ARCMBR        The  archive member to  be compared.   A specific name
                 must be entered.

   ARCFILE       The qualified  archived  source  file  containing  the
                 member.   Both  the  file name  and  the library  name
                 must be entered.

   FROMVER       The  From version of the  member to be  compared.  The
                 default is  *CURR  for  the  current  version  in  the
                 archive.

                 The  special values  *PRV1 -  *PRV20  may be  entered.
                 For  example, *PRV1 means  the first  version previous
                 to   the  current  version,  *PRV2  means  the  second
                 version previous to the current version.

                 *SRCMBR may  be  entered  to mean  the  actual  source
                 member  that  exists in  a  source  file  (not in  the
                 archive).   If  *SRCMBR is  specified, you  cannot use
                 TOVER(*PRV) or CMPVERRNG(*YES).

   TOVER         The To  version of  the member  to be  compared.   The
                 default is *PRV  to mean the version  previous to that
                 specified for  the From version.   *PRV cannot be used
                 when FROMVER(*SRCMBR) is specified.

                 *CURR may be entered to mean the current version.

                 The special  values *PRV1  -  *PRV20 may  be  entered.
                 For example,  *PRV1 means  the first version  previous
                 to  the  current   version,  *PRV2  means  the  second
                 version previous to the current version.

                 Note  that  if  FROMVER(*CURR)  is  specified  using a
                 TOVER  value  of  *PRV  or  *PRV1  produces  the  same
                 comparison.   *PRV  may  be helpful  when  you know  a
                 specific version, but not the previous version.

                 *LAST  may also be specified to  mean the last version
                 (oldest) in the archive.

   CMPVERRNG     A *YES/*NO value for  whether to compare all  versions
                 within the  FROMVER and TOVER  specified.  *NO  is the
                 default to only compare the versions specified.

                 *YES may  be specified to compare  all versions within
                 the  FROMVER  and  TOVER  range.    For  example,   if
                 FROMVER(*CURR)  and TOVER(*PRV5)  are  specified,  the
                 current  version  would be  compared  to *PRV1,  *PRV1
                 would  be compared  to *PRV2, *PRV2  would be compared
                 to *PRV3,  etc.  A  separate spooled  file will  exist
                 for  each comparison.   The actual  FROMVER must  be a
                 greater  value  than  the  TOVER.    For  example, you
                 cannot   request   FROMVER(*PRV5)   and   TOVER(*PRV3)
                 because  the  actual  version number  for  *PRV5  will
                 always be higher than *PRV3.

   SRCARCLIB     The  library  containing  the  source  archive  files.
                 The default is *LIBL.

   DSPSPLF       An option  to  determine  whether  DSPSPLF  should  be
                 used if CMPSRCARCM finds changes.

                 For either  *YES or *NO,  if no  changes are found,  a
                 completion  message  is sent  without  a spooled  file
                 being created.

                 *YES  is the default  and uses DSPSPLF  to display the
                 spooled  file.   The  spooled  file  is  automatically
                 deleted  when  you end  DSPSPLF.    *YES  may only  be
                 specified in an interactive job.

                 *NO  causes the  spooled file  to be output  for later
                 printing or displaying.

                 If  CMPVERRNG(*YES)  is  specified,  a  DSPSPLF   *YES
                 value is  changed to *NO  and a diagnostic  message is
                 sent.   You  must display all  the spooled  files that
                 were output.

CHKSRCARC (Check Source Archive)                       *CMD
--------------------------------

The Check Source Archive command  checks if the source archive  members
have a  corresponding member in  the source  file they were  originally
copied from.  A listing is produced.

   ARCFILE       The  qualified  archived  source file  containing  the
                 member.    Both the  file  name and  the  library name
                 must be entered.

   ARCMBR        The archive member  to be compared.   A specific  name
                 may be  entered, a generic name, or  the special value
                 *ALL.

   SRCARCLIB     The  library  containing  the  source  archive  files.
                 The default is *LIBL.

   OUTPUT        How to  output  the results.    *  is the  default  to
                 display the  spooled file  if the  command is  entered
                 interactively.   If the  display is  ended with F3/F12
                 or the Enter  key, the spooled  file is deleted  after
                 it is  displayed.   To  retain the  spooled file,  you
                 may use  the the System Request  'Cancel' function and
                 the spooled file will exist in a HLD status.

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

Other information
-----------------

Archive header control information
----------------------------------

The Archive  header record will normally be  displayed using WRKSRCARC.
When  you identify  the version  you want  to see  in detail,  Option 5
will display all of the fields (two screens).

Certain fields in  the header  contain control information  and can  be
changed using Option  2.  This will  bring up a change  display showing
the current values and you can key new values.

You  can only make  changes to the  current version.   Any new versions
added  will  automatically  pick  up  the  existing  values  with   the
exception of the SHALWD field.

The following describes the fields in detail:

  **   'Owner' (SHOWNR).   10 bytes.  Default  to blanks.  This  is not
       used  by the source  archive, but is  intended to let  you enter
       an   owner  of  the  source   to  assist  in  understanding  and
       categorizing your source.

  **   'Application' (SHAPP).  10 bytes.   Default to blanks.   This is
       not  used by  the source  archive, but  is intended  to  let you
       enter  an application  area that  the source  belongs to.   This
       can assist you  in understanding  and categorizing your  source.

  **   'Allow diff  create date'  (SHALWD).   1 byte.   Y/N value  that
       defaults  to N.    This value  is  always set  to N  when  a new
       version is  created.   When  UPDSRCARC runs,  it will  cause  an
       error to be printed  if the create date of the  source member is
       not  the  same  as the  create  date  originally  stored in  the
       archive.    This  protects  against the  case  where  the source
       member  has  been removed  and  a  programmer  has  subsequently
       re-used  the same  name for  a different  purpose.   If  the new
       member  should replace the existing archive  version, enter a Y.
       This will  allow  the UPDSRCARC  command  to bypass  the  create
       date check and archive the new version.

       Another  alternative   is  to  specify  CHKCRTDAT(*NO)   on  the
       UPDSRCARC command.   This will ignore  any create date checking.

       If the source file has been  deleted and is restored (or you  do
       a total restore of  the system), all of the create  dates of the
       members  will be  changed  to reflect  the date  restored.   The
       UPDSRCARC  CHKCRTDAT(*NO)  option should  be  used in  this case
       for the first time UPDSRCARC is run.

  **   'Allow src  mbr  remove' (SHALWR).    1 byte.   Y/N  value  that
       defaults to Y.   This controls whether the  MTNSRCARC command is
       allowed  to remove the corresponding  source member.  Specifying
       N  overrides  what  you  specify   for  the  'number  of   days'
       parameter  on  MTNSRCARC.    Therefore,  you  can  specify  that
       certain  source members  should remain in  the file  even though
       they have not been changed or used.

  **   'Minimum versions' (SHMINV).   3 digits.  Defaults  to 1.   This
       allows you  to specify a  minimum number  of versions that  must
       exist  for a  specific member.    The value  prevents MTNSRCARC,
       MTNSRCARC2,  or  DLTSRCARCM from  deleting  more than  the value
       specified.  This is  intended for critical source  members where
       you may  choose to  keep the last  N versions regardless  of how
       old they are.

       If  you reduce the value  (it must be 1  or greater), no changes
       occur to  the existing  versions until  MTNSRCARC or  DLTSRCARCM
       are run.

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

The archive programs do  not adopt any authorization.   They do use the
security specified to the archive files.

By default,  most archive functions are public.   The default authority
is *CHANGE which  allows any user  to update or  delete records in  the
archive.

Functions which  operate against  the source  members normally  require
some  special authorization.   For  example,  removing a  source member
requires object existence authority.

Three  files are  used to  make up an  archive (A  separate library may
contain a separate archive).   If you are going to  restrict authority,
you must consider the first two:

   SRCARHP       Header  file with  one record  per version  of control
                 information

   SRCARDP       Detail  file   with  one  or  more  compressed  source
                 records per version

   SRCARHL.      Logical  over  SRCARHP.     Should  not  need  to   be
                 considered for security purposes.

   SRCARHM.      Logical  over SRCARHP  in  arrival  sequence.   Should
                 not need to be considered for security purposes.

There are three typical solutions to security:

  **   A  public archive.   This  is achieved  by taking  the defaults.
       If your programmers can do all  functions on all source and  the
       end users are restricted to menus, this is a good solution.

  **   A private archive.  This could be achieved by either:

          Placing the  source  and the  archive files  in a  restricted
          library.

          Removing  public authority  from  the archive  files  and the
          source files.

  **   Restricting  updates  to the  archive.   For  example  you might
       want  a solution  where  a  controlling  user is  the  only  one
       allowed  to change  the archive.   Either  anyone  or designated
       users  would be allowed  to read from  the archive.   This could
       be achieved by:

          Restricting *CHANGE  authority to  the archive  files to  the
          controlling user.

          Providing *USE authority  to the public or  to specific users
          who should only be able to display or 'copy out' source.

       You  must  also   consider  what  authority  is  needed  by  the
       controlling user on  the actual source  files.  Obviously,  *USE
       authority  is  needed.   If  members  are  to  be  removed,  the
       controlling user needs the 'object existence' right.

       A  disadvantage  of   restricting  certain  users  to  the  *USE
       function  involves 'copying out' the source.   Since a *USE only
       user cannot  update the archive  header, CPYSRCARCM  UPDHST(*NO)
       must be  used.  This means  that if the source  member no longer
       exists,  'copy out'  will create  the member  with a  new create
       date, but the  archive header  record will not  be updated  with
       the new  date.  If  the member is  'copied out' to  its original
       source  file, UPDSRCARC will  fail on a  'create date mismatch'.
       See the  section on  'Archive  header control  information'  for
       how to recover from this situation.

Retention strategy
------------------

You  must have  a  retention  strategy for  both  the versions  in  the
archive and the source members.

              Archive versions
              ----------------

The following  describes some different  approaches you can  take which
are generally presented in an order of 'least complex' first.

  **   Take  the defaults on MTNSRCARC.   The current version is always
       kept  in  the  archive.    The  defaults   are  VERDAYS(60)  and
       MAXVERS(10).   This  will  delete any  versions  that are  older
       than 60 days or the 11th thru N version for any member.

  **   Alter  the defaults.  You can  specify any combination you want.

  **   Use MTNSRCARC2  instead  of  MTNSRCARC.   MTNSRCARC2  will  only
       delete old  versions if  1) the maximum  number of  versions has
       been  reached  or  2)  the  current  version  is  older  than  a
       specified number of  days.   MTNSRCARC2 does  not delete  source
       members.  If you  want automatic removal of source  members, use
       MTNSRCARC  (Use  VERDAYS  =  *MAX  and  MAXVERS  =  *MAX).    in
       addition to MTNSRCARC2.

  **   Specify  a value in the archive  header record for those members
       where you  always  want a  minimum  number of  versions  greater
       than 1.   The SHMINV value is always  honored regardless of what
       you  specify on MTNSRCARC,  MTNSRCARC2, or DLTSRCARCM.   See the
       section on 'Archive header  control information' for the  SHMINV
       field.

  **   Specify  MAXVERS(*MAX)   and  control  the  deletion   with  the
       VERDAYS  value.   For example,  if  you specify  VERDAYS(90) and
       MAXVERS(*MAX),  only  versions  older  than  90  days  would  be
       removed.   A single  member could  have many versions.   If  you
       have the space, this is reasonable solution.

  **   Specify  VERDAYS(*MAX) and control  the number of  versions kept
       with  MAXVERS.  For example,  if you specified VERDAYS(*MAX) and
       MAXVERS(5), any  versions beyond 5  would be deleted  regardless
       of how old they were.

       For  development  source,  this   would  normally  not  be  used
       because  a single member may change  frequently and you normally
       would not want to keep versions that are quite old.

       For production  source  (where  the  same member  is  not  being
       changed every  day) this could be  a reasonable approach  if you
       had the space and wanted a historical record of your source.

  **   Specify MAXVERS(1)  to provide an archive  with only the current
       versions kept.   If you have  source that you  need to keep  but
       never change, this would be reasonable.

  **   Use  multiple  MTNSRCARC  commands  for  the  same  archive  and
       request  different VERDAYS and  MAXVERS values depending  on the
       archived  file.    You  would  probably  want  a  CL  program to
       perform  the  multiple  MTNSRCARC  commands.    Only   the  last
       MTNSRCARC command should specify RGZPFM(*YES).

            Source members
            --------------

You  need to  decide  whether  to let  the  source archive  maintenance
function  remove source  members that have  not changed  recently.  The
source archive  has advantages  whether you  let it  remove the  source
members or not.

Allowing MTNSRCARC to  remove the source members that  have not changed
recently  is  the  optimal  solution  from  a system  and  save/restore
viewpoint.  If  you do not  need to  use all of  the source  regularly,
removing the static  source is generally  a good tradeoff.   It assists
in  improving the performance  of both  SEU and the  MTNSRCARC command.
It  also has  a favorable impact  on such commands  as DSPOBJD, DSPLIB,
SAV and RST.

There are situations  where removing source  members is not  desirable.
For example,  if you  have applications that  rely on the  source being
in existence or you need to distribute the source in a save format.

The  following describes some  different approaches you  can take which
are generally presented in an order of 'least complex' first.

  **   Take the  default on  MTNSRCARC.   This will  remove any  member
       that has not been changed in 60 days.

  **   Alter the default to your own value.

  **   Specify SRCDAYS(*MAX) so  that the source members  will never be
       removed.   You may choose to manually  delete the source members
       from the SEU or PDM display by looking at the member name.

  **   Use a value or default  for SRCDAYS and specify USECHK(*YES)  to
       prevent the  member from being  removed if it  has been used  or
       changed  in the last  N days.   USECHK  refers to the  'last use
       date'  which is kept  on a member  level.  Opening  the file for
       'read only' causes the 'use date' to change.

       For example,  if you  use SEU,  the 'use  date' changes  because
       the member  is read  into a work  space (whether you  update the
       source  or not).  The  'from member' 'use  date' also changes if
       you copy the source using SEU  or with CPYSRCF.  If you use  SEU
       and  update the  member  or  it is  the  TOMBR  on CPYSRCF,  the
       'change  date'  changes.   A  restore  also  changes the  change
       date.

  **   Specify a value in the  archive header record for those  members
       where you  do not want  to remove the  member regardless of  its
       'change  date' or  'use date'.   This  would be  appropriate for
       those  members that  you use  as a  base for copying  into other
       source members.   See  the  section on  'Archive header  control
       information' for the SHALWR field.

  **   Use  multiple  MTNSRCARC  commands  for  the  same  archive  and
       request  different  SRCDAYS  values  depending  on the  archived
       file  (ARCFILE  parameter).    You  would  probably  want  a  CL
       program to  perform the  multiple MTNSRCARC  commands.  You  can
       request  a different  value depending  on  the file  or library.
       Only the last MTNSRCARC command should specify RGZPFM(*YES).

Backup
------

The following comments  assume that you  are using UPDSRCARC  regularly
to  capture the  source changes.    This is  essential  to designing  a
proper backup strategy.

You must  decide whether you  will let MTNSRCARC  remove source members
or not.  See the section on 'Retention strategy'.

In  either case, there is  still an advantage in  never backing up your
source files.   The advantage  is greater if  you let MTNSRCARC  remove
source members  which have  not changed recently.   This  also improves
the  performance of general system functions  like DSPLIB, DSPOBJD etc.

There  is  considerable   system  overhead   involved  in  saving   and
restoring source  files containing  many source  members.   There is  a
fixed  amount of  overhead associated  with  each member  regardless of
how many  records exist  in  the member.   Consequently,  reducing  the
number of members has a  major impact on how fast a source  file can be
saved  or restored.   For  source files,  the  overhead of  getting the
member  ready to  be saved  or restored  is generally greater  than the
time it takes to transfer  to or from the media.  This  is particularly
true on faster tape drives.

There is  a very noticeable impact  when restoring a large  source file
when  the file does  not exist  on the system.   The  system must first
create all of the member  control blocks and then perform the  restore.

            Backing up the entire archive
            -----------------------------

If  your strategy  is  to periodically  save all  members  of a  source
file,  saving the archive will  generally be faster even  though it may
have several  versions  for some  members  (this assumes  a  reasonable
retention  strategy).   If  you  make  a  lot of  source  changes,  the
performance  difference is  less.  If  you have  only a  single version
per   member  in  the  archive,  the  performance  difference  is  very
noticeable on fast tape drives.

SAVCHGOBJ  is  generally  an   effective  function  on  source   files.
Because  most source  members  do  not change  daily,  only saving  the
changes can be a significant performance gain.

Assuming  you  use  UPDSRCARC  daily,  SAVCHGOBJ  would  not  save  the
archive files  if no  source changes  had occurred.    For many  source
files this  would be very  typical.   If you are  regularly programming
the  system, it would be  unusual not to change  some source during the
day.   If you  have 'production  source' that  is not  changed until  a
development  version   is  ready,   there  could   be  days  when   the
'production'  source does  not  change.   Most  systems  have different
sets  of source files (e.g.   per application) and  it is probable that
not every set changes every day.

If you are  archiving several types of  source files, the most  typical
strategy would be:

  **   Periodic (e.g.  monthly) use of MTNSRCARC.

  **   Periodic  (e.g.    weekly)   full  save  of  the  archive  (e.g.
       SAVLIB)

          Do not save your source files

          Daily:  UPDSRCARC  to  update the  archive  for  any changes.
          SAVCHGOBJ of the archive.   This would save the archive  only
          if had been changed.

            Backing up only changes to an archive
            -------------------------------------

Saving  an entire  archive every  day  versus a  SAVCHGOBJ approach  on
regular  source files  could  be an  advantage for  either  approach in
terms of the  time for  the SAV  command.  Because  SAVCHGOBJ spends  a
considerable amount  of time determining  what needs  to be saved,  the
fastest  approach is  application  dependent.   SAVCHGOBJ  would almost
always require less media.

You  can  provide  a  'save  change'  approach  by  journaling  the two
archive physical  files.   This would  cause journal  entries for  only
the  versions  that  have  changed.    It would  be  a  more  efficient
approach  from a save viewpoint  (both time and media)  than the use of
SAVCHGOBJ.

Note  that  this  is  considerably  different  than  journaling  source
files.  Journaling  source files causes several types  of overhead that
generally  makes  it undesirable.   The  following  compares journaling
source files versus journaling a source archive.

  **   With journaling source  files, every SEU  update (work space  is
       written to the member)  causes a journal entry for  every source
       record.  If  UPDSRCARC is run only once  a day, only one version
       of  the  changes  is  captured  and  the  compression  technique
       causes less journal entries to be written.

  **   With journaling source files,  source changes can occur  all day
       long   which   causes   journaling   overhead  all   day   long.
       Journaling  the  archive  causes  the  majority  of the  journal
       entries to be written when  UPDSRCARC/MTNSRCARC are run.   These
       functions can be scheduled.

  **   With  journaling  source  files, every  member  being  journaled
       causes overhead  to journaling.  Journaling  many members causes
       a noticeable  difference  when changing  to  a new  receiver  or
       saving a  journal receiver.   Journaling an archive  only causes
       two members to be journaled.

To  start journaling,  use the  STRJRNPF command  for the  two physical
files (SRCARHP and SRCARDP) in the archive library.

If  the  source  is being  changed  on  a daily  basis,  journaling the
archive is generally the  most optimal solution from a  save viewpoint.
This  assumes  that  you  can  schedule  when  the  UPDSRCARC/MTNSRCARC
functions occur to minimize the system impact.

The strategy would then be:

  **   Periodic  (e.g.  monthly) use of  MTNSRCARC.  You could consider
       ending  journaling  just  prior  to  using  MTNSRCARC  and  then
       restarting it to reduce the amount of journaling overhead.

  **   Periodic  (e.g.    weekly)  full   save  of  the  archive  (e.g.
       SAVLIB)

          - Do not save your source files

  **   Daily:  UPDSRCARC to update the  archive for any  changes.  Save
       of the journal receivers.  If  you use SAVCHGOBJ, by default  it
       will save  the  journal receivers  and bypass  any objects  that
       are journaled.

          - Do not save your source files

As  with all journaling  solutions, you  must periodically change  to a
new journal receiver and delete old journal receivers.

The  most significant  performance gain for  all save/restore functions
occurs when  you need  to recover  some old  source version.   In  most
cases you will  find it in the archive and thus  avoid having to locate
the  media  and restore  it.   Restoring  one or  several  members from
backup media requires a good deal of both people and system time.

            Disaster recovery
            -----------------

One of  the  major  backup considerations  is  how to  recover  from  a
disaster situation where the entire system must be restored.

  **   If  you do  not  save your  source files,  they  will not  exist
       following  a  disaster.   You  must re-create  the  source files
       (CRTSRCPF) and then use  the CPYSRCARCM command.   You can  copy
       out  all versions  or  all versions  that  exist at  a  specific
       date.

  **   If you  have saved your source files at  some point and they are
       restored,  they are probably  at a down  level from the archive.
       Because  the restore  will  change  the  change  date  of  every
       member,  it will  appear to  UPDSRCARC  as if  every member  has
       been  changed.   Before running UPDSRCARC,  you need  to run the
       special command SYNSRCARCM.

Assume you are doing the following:

  **   Daily.  Using UPDSRCARC and backing up the archive.

  **   Monthly.  Using SAVLIB LIB(*ALLUSR).   This will cause both  the
       archive and the source files to be saved.

  **   Bi-monthly  (every  60 days).    Using  MTNSRCARC with  the  the
       defaults.   Therefore,  some members exist  only in  the archive
       (the actual source member has been removed).

Assume the following:

  **   The last SAVLIB LIB(*ALLUSR) was run on 0920901.

        - No more source changes were made on 0920901 after the backup.

  **   The last backup of the archive was 0920915.

  **   The system crashes on 0920916 and must be totally restored.

  **   RSTLIB LIB(*ALLUSR) was run on 0920917.

Restoring all  of  the  libraries  from  the  SAVLIB  of  0920901  will
restore both the  source files and the  source archive.  The  next step
would  be to  restore the  most  current backup  of the  archive  - the
0920915 version.

At  this  point  the  archive  is more  current  than  the  source file
members.  However,  the restore of the  source files has caused  all of
the  member change  dates to  be  changed to  the date  of the  restore
(0920917).   If  UPDSRCARC  is run  at this  point,  all of  the source
members would be  considered new  versions and the  versions that  were
added between 0920901 and 0920915 would be made old versions.

Rather than do this, the special command SYNSRCARCM can be used.

Using  SYNSRCARCM  with  a  date of  0920902  will  cause  any  current
versions in  the archive with a  date equal to or  greater than 0920902
to be  'copied out'.   Any  members that  were changed  after the  last
full backup will be copied out and placed into the source members.

SYNSRCARCM will also capture  the change date and time  from any source
member that  exists in both the archive and  the source file and update
the  archive with the information.   It simulates a  'copy out' so that
the result is the archive  member has the same change date/time  as the
source member.

If  UPDSRCARC is  run  immediately following  SYNSRCARCM,  it will  not
cause any  changes to be made to the  archive since the archive and the
source file are synchronized.  As  soon as new SEU changes are made  to
the  source,  UPDSRCARC  will  recognize   them  and  capture  the  new
changes.

Deleting a source archive
-------------------------

A CRTSRCARC  command exists, but a corresponding  DLT command does not.
Deleting a source archive  deletes all knowledge of  the versions.   To
delete a source archive issue the following commands:

     DLTF          FILE(llll/SRCARHL)
     DLTF          FILE(llll/SRCARHM)
     DLTF          FILE(llll/SRCARHP)
     DLTF          FILE(llll/SRCARDP)

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

If you  are  archiving  S/38  Text  Management  members  which  contain
underscore or  highlighting,  you must include the sequence number. See
the discussion for the UPDSRCARC command INCLUDE parameter.

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

The following TAA Tools must be on your system.

     ADDDAT       Add date
     EDTVAR       Edit variable
     EXTLST       Extract list
     CHKGENERC    Check generic
     DSPSRCMBR    Display source member
     FILEFDBCK    File feedback
     FMTLIN       Format line
     HLRMVMSG     HLL Remove message
     LOCKMSG      Lock record message
     PRTSRCF      Print source file member
     RPGSTSDS     RPG Status data structure
     RTVDAT       Retrieve date
     SCNVAR       Scan variable
     SNDCOMPMSG   Send completion message
     SNDDIAGMSG   Send diagnostic message
     SNDESCMSG    Send escape message
     SNDSTSMSG    Send status message
     TAAARC       TAA Archive
     WRTSRC       Write source

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

The tool  is ready to  use, but you  must create the  files to  be used
with the command:

      CRTSRCARC     SRCARCLIB(xxxx)

Testing
-------

It  may be  desirable to  test  some of  your source  with  the archive
functions  to give  yourself confidence and  ensure that  it is working
properly.

For example, you could  set up a test  archive and archive one  of your
files  using UPDSRCARC.   Then create  a separate  source file  and use
CPYSRCARCM  to 'copy out' all of the  current versions.  You could then
use a function like the TAA  tool CMPSRC2 to compare all of the  source
in your original file to the 'copied out' file.

After performing some  updates to your real source file,  you could use
UPDSRCARC  to capture the  changes.  Then  you could use  WRKSRCARC and
try some of the supported options.

PRTSRCARC will let you display a summary of the archive.

You can force  a new  change date/time  for a member  by invoking  SEU,
using F3 to  end and requesting 'Y'  on the Exit display to  update the
member.   You  could do  this followed  by  UPDSRCARC for  a particular
member  multiple times.   Each  repetition would  cause a  new version.
You can  then  try the  MTNSRCARC command  with  the MAXVERS  parameter
specified to remove excess versions.

Recovery
--------

Most  recovery  can  occur  thru  supported system  or  source  archive
commands.    Save  and  restore  commands  provide  the basic  support.
Journaling can also be considered.  See the section on 'Backup'

If  UPDSRCARC  or  MTNSRCARC  are  interrupted,  recovery  should  only
require re-running  the commands.   You  may need  to cause the  change
date/time  of  the source  member  to  be changed  again  to  force the
member to be properly archived by  UPDSRCARC.  Consider the use of  the
TAA tool PRTSRCSUM to determine what has recently been changed.

If damage  occurs, recovery  would normally  occur using  restore.   If
some  of the  detail records  are damaged,  you  may choose  to recover
what you can using CPYF.

The  RCLSRCARCM command  is intended  for the  unlikely case  where the
connection between the  header record and  the detail records has  been
lost.    It  can  also   be  used  when  CPYSRCARCM  fails  because  of
unexpected   conditions  (missing   or  invalid   control  characters).
RCLSRCARCM should  allow  retrieving of  any  source from  any  version
still in the archive.

In some  cases you  may want  to 'copy  out' all  of the versions  that
were  created as  of a  specific date.    This could  be done  with the
following CL program which  is in the proper  format to be copied  into
a CL source  member (use CPYTAA  TAAARCMBR(SRCARC) to copy  the current
documentation member to QATTINFO in TAATOOL).

             PGM        /* Copy all versions created after a date */
             DCLF       FILE(SRCARHP)
 READ:       RCVF       /*  Read archive header record */
             MONMSG     MSGID(CPF0864) EXEC(GOTO EOF)
                        /* Bypass unless it is requested lib/file */
                        /*   Specify the file and library needed */
             IF         (&SHFILE *NE fff) GOTO READ
             IF         (&SHLIB *NE lll) GOTO READ
             IF         (&SHVERC *NE 'Y') GOTO READ /* Not current */
                        /* Specify a date */
             IF         (&SHVER *GE 090123100) GOTO CPY
                        /* If you want to copy all source which */
                        /*   should not be removed do           */
             IF         (&SHALWR *EQ 'N') GOTO CPY
             GOTO       READ
 CPY:                   /* Specify a TOSRCFILE */
             CPYSRCARCM ARCMBR(&SHMBR) ARCFILE(&SHLIB/&SHFILE) +
                          TOSRCFILE(llll/ffff)
             GOTO       READ
  EOF:       ENDPGM

Compression algorithm
---------------------

The  compression  algorithm used  is  a tradeoff  between  the time  it
takes  to perform  the compression/decompression,  the amount  of space
saved and the need to  include some identification in case  recovery is
needed.

Most source files  have a high degree of consecutive  blanks.  The next
most   common  occurrence  of   consecutive  repetitive  characters  is
asterisk.  After  these two  characters there is  normally very  little
consecutive  repetition  that  can  be  compressed.    There  are  more
sophisticated  algorithms  that  involve  non-consecutive  compression,
but they require more CPU cycles than is deemed reasonable.

The source  archive  function  only compresses  repetitive  blanks  and
asterisks.   If  two or  more  occur in  sequence,  the characters  are
replaced by a  hex value (X'FD' or X'FE' followed  by a one byte binary
field  which contains a  count of the repeated  characters (up to 255).
If only two  consecutive blanks or asterisks  occur, there is no  space
saving  (2 bytes  are replaced  by 2  bytes), but  the  compression and
decompression occurs faster.

Special  hex  characters  appear  in  the  compressed  source (X'FA'  -
X'FF').   There  is  no restriction  on  the use  of  these  characters
within  the source.   If  they occur,  an escape  character (X'FF')  is
used followed by the X'Fx' character from the source.

The  UPDSRCARC command provides  an option  for whether to  include the
sequence number and change  date found in each  source record.   Either
field, both or none may be specified.

Each detail  record (in  SRCARDP) contains  an 11  digit packed  number
assigned  to  the  version and  a  5  digit  packed statement  sequence
number.    This is  followed by  a 500  byte area  where the  source is
compressed.  The first record  for each member has a standard  41 bytes
made up of:

          Pos  1        X'FA'
          Pos  2-11     File
          Pos 12-21     Library
          Pos 22-31     Member
          Pos 32-40     Version CYYMMDDnn
          Pos 41        Include option from UPDSRCARC for whether the
                            compressed source includes the sequence
                            number and date found in each source rcd.
                                (B=Both, N=None, S=Seq nbr, C=Chg date)

The compressed  source area  of 500 bytes  will hold  multiple records.
Overflow  will occur  to the  next record.   A  new source  record will
rarely start at the beginning of a 500 byte record.

The following special Hex Fx  characters will appear in the  compressed
source:

     X'FA'  Beginning of source (once per version)
     X'FB'  End of source (once per version)
     X'FC'  Beginning of a new source record
     X'FD'  Beginning of 2 or more consecutive asterisks
     X'FE'  Beginning of 2 or more consecutive blanks
     X'FF'  Escape character which is followed the X'Fx' character

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

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

   UPDSRCARC     *CMD                       TAASMAA       QATTCMD
   CPYSRCARCM    *CMD                       TAASMAA2      QATTCMD
   DLTSRCARCM    *CMD                       TAASMAA3      QATTCMD
   MTNSRCARC     *CMD                       TAASMAA4      QATTCMD
   DSPSRCARCM    *CMD                       TAASMAA5      QATTCMD
   WRKSRCARC     *CMD                       TAASMAA6      QATTCMD
   SCNSRCARC     *CMD                       TAASMAA7      QATTCMD
   PRTSRCARC     *CMD                       TAASMAA8      QATTCMD
   RCLSRCARCM    *CMD                       TAASMAA9      QATTCMD
   CRTSRCARC     *CMD                       TAASMAA10     QATTCMD
   SYNSRCARCM    *CMD                       TAASMAA11     QATTCMD
   RTVSRCARCD    *CMD                       TAASMAA12     QATTCMD
   MTNSRCARC2    *CMD                       TAASMAA13     QATTCMD
   CMPSRCARCM    *CMD                       TAASMAA14     QATTCMD
   CHKSRCARC     *CMD                       TAASMAA15     QATTCMD
   SRCARHP       *FILE          PF          TAASMAAP      QATTDDS
   SRCARDP       *FILE          PF          TAASMAAQ      QATTDDS
   SRCARHL       *FILE          LF          TAASMAAL      QATTDDS
   SRCARHM       *FILE          LF          TAASMAAM      QATTDDS
   TAASMAAD      *FILE          DSPF        TAASMAAD      QATTDDS
   TAASMAAC      *PGM           CLP         TAASMAAC      QATTCL
   TAASMAAC2     *PGM           CLP         TAASMAAC2     QATTCL
   TAASMAAC3     *PGM           CLP         TAASMAAC3     QATTCL
   TAASMAAC4     *PGM           CLP         TAASMAAC4     QATTCL
   TAASMAAC5     *PGM           CLP         TAASMAAC5     QATTCL
   TAASMAAC6     *PGM           CLP         TAASMAAC6     QATTCL
   TAASMAAC7     *PGM           CLP         TAASMAAC7     QATTCL
   TAASMAAC8     *PGM           CLP         TAASMAAC8     QATTCL
   TAASMAAC9     *PGM           CLP         TAASMAAC9     QATTCL
   TAASMAAC10    *PGM           CLP         TAASMAAC10    QATTCL
   TAASMAAC11    *PGM           CLP         TAASMAAC11    QATTCL
   TAASMAAC12    *PGM           CLP         TAASMAAC12    QATTCL
   TAASMAAC13    *PGM           CLP         TAASMAAC13    QATTCL
   TAASMAAC14    *PGM           CLP         TAASMAAC14    QATTCL
   TAASMAAC15    *PGM           CLP         TAASMAAC15    QATTCL
   TAASMAAC26    *PGM           CLP         TAASMAAC26    QATTCL
   TAASMAAC27    *PGM           CLP         TAASMAAC27    QATTCL

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

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

   TAASMAAR      *PGM           RPG         TAASMAAR      QATTRPG
   TAASMAAR2     *PGM           RPG         TAASMAAR2     QATTRPG
   TAASMAAR3     *PGM           RPG         TAASMAAR3     QATTRPG
   TAASMAAR4     *PGM           RPG         TAASMAAR4     QATTRPG
   TAASMAAR6     *PGM           RPG         TAASMAAR6     QATTRPG
   TAASMAAR7     *PGM           RPG         TAASMAAR7     QATTRPG
   TAASMAAR8     *PGM           RPG         TAASMAAR8     QATTRPG
   TAASMAAR9     *PGM           RPG         TAASMAAR9     QATTRPG
   TAASMAAR11    *PGM           RPG         TAASMAAR11    QATTRPG
   TAASMAAR12    *PGM           RPG         TAASMAAR12    QATTRPG
   TAASMAAR13    *PGM           RPG         TAASMAAR13    QATTRPG
   TAASMAAR15    *PGM           RPG         TAASMAAR15    QATTRPG
   TAASMAAR24    *PGM           RPG         TAASMAAR24    QATTRPG

There are no RPG programs for the CRTSRCARC or DSPSRCARCM commands.

Structure
---------

UPDSRCARC  Cmd
  TAASMAAC   CL
    TAASMAAR   RPG

CPYSRCARCM  Cmd
  TAASMAAC2  CL
    TAASMAAR2  RPG

DLTSRCARCM  Cmd
  TAASMAAC3  CL
    TAASMAAR3  RPG

MTNSRCARC  Cmd
  TAASMAAC4  CL
      DLTSRCARCM Cmd
    TAASMAAR4  RPG
    TAASMAAR24  RPG

MTNSRCARC2  Cmd
  TAASMAAC13  CL
      DLTSRCARCM Cmd
    TAASMAAR13  RPG
    TAASMAAR24  RPG

DSPSRCARCM  Cmd
  TAASMAAC5  CL

WRKSRCARC  Cmd
  TAASMAAC6  CL
      DSPSRCARCM Cmd
      CPYSRCARCM Cmd
      DLTSRCARCM Cmd
    TAASMAAR6  RPG
    TAASMAAC26 CL
      TAASMAAD   DSPF

SCNSRCARC  Cmd
  TAASMAAC7  CL
    TAASMAAR7  RPG

PRTSRCARC  Cmd
  TAASMAAC8  CL
    TAASMAAR8  RPG

Structure continued
-------------------

RCLSRCARCM Cmd
  TAASMAAC9  CL
    TAASMAAR9  RPG

CRTSRCARC  Cmd
  TAASMAAC10  CL

SYNSRCARCM Cmd
  TAASMAAC11 CL
    TAASMAAR11 RPG

RTVSRCARCD Cmd
  TAASMAAC12 CL
    TAASMAAR12 RPG

CMPSRCARCM Cmd
  TAASMAAC14 CL

CHKSRCARC  Cmd
  TAASMAAC15 CL
    TAASMAAR15 RPG
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top