FLMATVER macro

Use this macro to enable the audit and version utility and to define the group and the type of members in that group to record audit and version information for.

You must specify the name of the VSAM data sets to contain the audit information and the name of the partitioned data sets to contain the versions using the FLMCNTRL and FLMALTC macros. You can define multiple versioning partitioned data sets for a project.

Using the group and type defined in the FLMATVER macro, SCLM records information in the VSAM data set each time a member's accounting information is created, updated, or deleted within that SCLM group. This information is a record that contains the member's accounting information, the type of operation, the user ID of the user who performed the operation, and the date and time the operation occurred.

You can use the FLMATVER macro to store a version of a member. The member is stored when the particular SCLM operation (such as SAVE) has completed successfully. The version contains the information to recreate the member as it previously existed. You can disable the versioning function while maintaining the audit capabilities. Version information is captured each time an editable member or an output that is not record format U is created or updated, but not when it is deleted. Sequence number differences can be ignored by coding the SEQNUM parameter, otherwise, they are treated as data.

Macro format


>>-FLMATVER--GROUP=-+-group-+--,TYPE=-+-type-+------------------>
                    '-*-----'         '-*----'   

>--+-----------------------+--+-------------------+------------->
   '-,SEQNUM=-+-STANDARD-+-'  |           .-NO--. |   
              +-STD------+    '-,VERSION=-+-YES-+-'   
              +-COBOL----+                            
              '-NONE-----'                            

>--+----------------------------+--+--------------------+------><
   '-,VERCOUNT=number_to_retain-'  |            .-YES-. |   
                                   '-,CHECKSUM=-+-NO--+-'

Parameters

GROUP|*

The name of the group for which the audit data, version data, or both, is to be maintained. The group must be defined in the project. Use an asterisk (*) to indicate all groups.

,TYPE|*

The name of the type for which the audit data, version data, or both, is to be maintained. The type must be defined in the project. Use an asterisk (*) to indicate all types.

Audit information can be captured for editable or noneditable types. Version information can be captured for editable types and non-editable types that are not record format U. This means that you can maintain version information for types such as "source" and "object", but not for load modules or other data that has record format U. Therefore, if you have a project with record format U data, such as load modules, do not specify TYPE=* and VERSION=YES. If you attempt to version data that is record format U, an error message is issued during SCLM processing.

,SEQNUM=STANDARD|STD|COBOL|NONE

If you specify STANDARD, STD, or COBOL, SCLM ignores sequence number differences when creating a version of a member.

STANDARD or STD means ignore differences in the last eight columns of the data for fixed formats, and the first eight columns of the data for variable formats. In both cases the ignored columns are presumed to be standard sequence numbers.

COBOL means ignore differences in the first six columns of the data, which are presumed to be COBOL sequence numbers.

Omitting this parameter, or specifying NONE, indicates that all columns are to be treated as data.

Note: When changing the value of the SEQNUM specification for a project, also change the VERPDS specification on the FLMCNTRL or FLMALTC macros for the affected groups. Failure to do so may cause checksum verification errors when attempting to recover versions created with the previous specification (see the CHECKSUM keyword).

,VERSION=YES|NO

If you specify YES, both the versioning and auditing processes are active. If you specify NO, versioning is not active; however, the audit process is active. If not specified, VERSION will default to NO. Version data can be captured for any editable or non-editable (output) members that are not record format U.

Note: You cannot have versioning without auditing.

,VERCOUNT=number_to_retain

The number of versions to keep in the version partitioned data set for the group or type specified. If you specify a value of zero (0), then all versions associated with a member are kept.

If you specify a value of two (2) or more, each time a member is changed the latest copy of the member is stored and the earliest copy is deleted, so that the number of versions remains constant. Any audit records that are associated with versions that have been deleted are retained, but no longer indicate that a version of the member exists. If you do specify a value of two or more, allocate a separate VERPDS for each combination of group and type that has versioning enabled.

Note: Failure to allocate a separate VERPDS for each combination of group and type can cause retrieval problems. Use the FLMALTC macro, or use the @@FLMGRP variable in the VERPDS name.

If a VERCOUNT value is not specified on the FLMATVER macro or if a value of one (1) is specified, then the value specified using the VERCOUNT parameter on the FLMCNTRL macro is used. If a VERCOUNT value is not specified on either macro, then all versions associated with a member are kept.

,CHECKSUM=YES|NO

If you specify YES or omit this parameter, checksum verification of versions on retrieval is in effect.

In the case of message FLM39220 Return Code 34, which indicates a damaged version or a version created before SEQNUM support was available in SCLM, you may take this action to override the checksum verification failure:

Insert the CHECKSUM=NO parameter.
Reassemble the project definition.
Retry retrieval of the version.

Attention: The validity of the retrieved version is not assured. This procedure is recommended for emergency use only.

Example

The statements shown here illustrate how to capture versions of members as well as auditing information.

The first of these statements saves versions of members with TYPE=COBOL and GROUP=PROD, ignoring differences in columns 1-6 where COBOL sequence numbers are expected. The second statement saves versions of your COPYBOOK members, including the non-editable members that might have been generated as a result of building a BMS member. The third statement tells SCLM to keep only the latest two versions of your object modules. This overrides any VERCOUNT specified on the FLMCNTRL macro for the project.

FLMATVER GROUP=PROD,TYPE=COBOL,VERSION=YES,SEQNUM=COBOL
FLMATVER GROUP=PROD,TYPE=COPYBOOK,VERSION=YES
FLMATVER GROUP=PROD,TYPE=OBJ,VERSION=YES,VERCOUNT=2

Note: If sequence number differences are to be ignored, full length source lines are saved in the delta file for all lines with non-sequence number differences, but lines that differ only in the sequence number are not saved in the delta file. So, when the version is retrieved, the original sequence numbers for unchanged lines are lost. Instead, the sequence numbers for the most current version are retained.

This statement saves only the auditing information for members with TYPE=PASCAL and GROUP=PROD:

FLMATVER GROUP=PROD,TYPE=PASCAL,VERSION=NO

Note: You can omit the VERSION=NO parameter as it is the default. If omitted, versions of the member will not be saved.

The order of the FLMATVER macros is important to keep in mind. Versioning is enabled/disabled in the order specified, so after turning versioning off for GROUP=* or TYPE=*, any later FLMATVER macros that specify a particular GROUP or TYPE will be ignored.

In this example, no version will be saved for PROJ.AAA.SOURCE.

    FLMATVER GROUP=*,TYPE=*,VERSION=NO
    FLMATVER GROUP=AAA,TYPE=SOURCE,VERSION=YES

However, if the two statements are reversed, a version of PROJ.AAA.SOURCE will be saved.

    FLMATVER GROUP=AAA,TYPE=SOURCE,VERSION=YES
    FLMATVER GROUP=*,TYPE=*,VERSION=NO