Build and promote by change code

You can also use architecture definitions to identify the parts associated with a specific change or group of changes. This can be done in any architecture member using the CCODE statement. In addition to the normal contents of an architecture definition, such an architecture member contains a list of CCODE keywords followed by a change code and include flag. An example of such an architecture definition follows:

     * ARCHDEF FOR PACKAGE PKG00001
     CCODE  POY66045 INCLUDE   * Include changes for problem POY66045
     CCODE  POY66615 INCL      * Include changes for problem POY66615
     INCL   SCLM     ARCHDEF   * SCLM ARCHDEF

There are no SCLM-enforced conventions for change codes. The only restriction is that it be a maximum of 8 characters. For SCLM to determine the change code, any change code that contains an embedded blank or whose first character is other than A-Z, 0-9, @, # or $ must be enclosed in delimiters. A delimiter can be any character not specified above. Here are some examples:

     CCODE A                  * this includes change code A
     CCODE ,A B C,  E         * this excludes change code A B C
     CCODE /AB/     IN        * this includes change code AB
     CCODE 'A B'    EX        * this excludes change code A B
     CCODE 1"       EXCLUDE   * this excludes change code 1"

Valid values for the include flag are INCLUDE or EXCLUDE. The default value is INCLUDE. A value of INCLUDE indicates that only the changes specified are included. A value of EXCLUDE indicates that everything except the specified changes are included. The following table illustrates the conditions under which SCLM will build and promote by change code.

Table 1. The conditions under which SLCM builds and promotes by change code
MEMBER CHANGE CODE	CCODE CCODEX INCLUDE	CCODE CCODEX EXCLUDE
CCODEX	Yes	No
CCODEY	No	Yes
no change code	No	Yes

Multiple CCODE statements can be specified in an architecture definition. An error message is issued when the include flag value is not the same on all statements. Duplicate CCODE statements are ignored. Any CCODE statements whose change code and include flag resolve to the same value are considered duplicates. For example, the following CCODE statements are duplicates:

     CCODE 1
     CCODE '1 ' INCLUDE

CCODE and COPY keywords cannot be used in the same architecture definition. Because the COPY keyword causes an actual copy of an architecture definition to be inserted into the first, the architecture definition referenced by the COPY statement must also be free of CCODE statements. To build an architecture definition containing COPY statements by change code, create a new architecture definition that contains the CCODE statement and an include (INCL) of the original architecture definition.

The concept of a package (group of changes) is supported through the ability to specify multiple CCODE keywords in an architecture definition. To more easily identify and maintain these architecture definitions, you can define a TYPE called PACKAGE with a language of ARCHDEF and use the package identifier or change code as the name for each member name. Or you can define a single architecture member and update the change code values in that member for each new build or promote by change code.

Only those CCODE statements that appear in the architecture definition specified as input to the build or promote will be processed. All other CCODE statements will be ignored. For example, assume that you have architecture definitions ISPF, PDF, SCLM and ISPFSUB. The architecture definitions contain the following statements:

     * ARCHITECTURE DEFINITION MEMBER ISPF
     INCL  ISPFSUB ARCHDEF
     INCL  PDF     ARCHDEF
     INCL  SCLM    ARCHDEF
     CCODE A       INCLUDE

     * ARCHITECTURE DEFINITION MEMBER ISPFSUB
     CCODE D       INCLUDE

     * ARCHITECTURE DEFINITION MEMBER PDF
     CCODE B       INCLUDE

     * ARCHITECTURE DEFINITION MEMBER SCLM
     CCODE C       INCLUDE

When the ISPF architecture definition is built, only members with the change code A will be included from the build group. The CCODE statements to include change codes B, C, and D will not be processed for this build because they were found in included architecture definitions.

During the verification phase of build and promote, SCLM will search the change code list for members in the build or promote scope at the specified group. If the member is in scope and the change code appears (or does not appear in the case where EXCLUDE is specified) on the change code list, it will be included. Otherwise, SCLM will continue to search for the member beginning at the next group. Change codes will be processed for all editable members stored in PDS data sets under SCLM control, including architecture definitions. Change codes will be processed on included members when their data sets are allocated with IOTYPE=I, KEYREF=SINC. Included members whose data sets are allocated with a KEYREF of SREF or CREF will not be processed by change code. To process includes referenced by SREF and CREF allocations:

Add FLMINCLS macros to reference the desired types.
Change the FLMALLOC macros to use KEYREF=SINC.
Add an INCLS parameter to the FLMALLOC macros to reference the FLMINCLS macros.

The architecture definition specified as input to the build or promote will always be processed, regardless of its change codes. Change codes are only significant for the build or promote group. In scope members found above this group will be included regardless of change code. If the specified change appears on a member's change code list but is not the last change and INCLUDE is specified, a warning message will be issued.

We recommend you build and promote each change to a member before beginning another. In cases where this is not possible, multiple changes that affect a single member should be built or promoted together. For instance, assume that you have members A, B, and C. Change 1 affects members A and B while change 2 affects members A and C. As both changes affect member A, the inclusion of either change without the other will cause the changes to be unsynchronized. Change codes 1 and 2 should be built and promoted together.

To build an application containing dynamic includes by change code, a build without change codes must occur first. Otherwise, the build can fail because includes are missing.

A promote by change code must always be preceded by a successful build of the same architecture definition. At the completion of a promote by change code, rebuild the application at the higher group. Change codes are used to determine whether a member found at the report input group will be included in the Architecture Report when executing the Architecture Report Utility against an architecture definition containing CCODE statements. The Database Contents Utility, on the other hand, does not use change codes specified on CCODE statements to determine whether a member will appear in the report or tailored output.