SRCARC -- Source Archive

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

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