CCIDs and Comments for Product Management

Using Change Control Identifiers (CCIDs) and COMMENT fields as project management tools in
Endevor
ce18
Change Control Identifiers (CCIDs) provide
Endevor
users with an important project management tool. CCIDs can function as logical grouping mechanisms by which user-specified portions of the
Endevor
inventory can be tagged, then viewed, tracked, and manipulated.
In addition to the CCID, you can also specify a comment for
Endevor
actions. Consider using the comment and the CCID to provide additional information. For instance, the person who performs an action might use the COMMENT field to note the purpose of the action.
Users can specify CCIDs and/or comments when they request actions. You can decide whether to require CCIDs and/or comments for all action requests on a system-by-system basis.
You can specify a CCID and/or comment when you request any of these
Endevor
actions: ADD, UPDATE, RETRIEVE, GENERATE, MOVE, TRANSFER, DELETE, and RESTORE.
Endevor
updates the CCID and/or comment in up to six places with the CCID and/or comment specified in the action request. Whether a CCID and/or comment is updated depends on the effect the action has on the source and outputs managed by
Endevor
.
The following list details CCID and/or COMMENT fields that may be updated:
  • Last Action CCID and/or comment
    The CCID and/or comment used the last time any action was performed that updated
    Endevor
    in any way (every action except RETRIEVE). This CCID and/or comment is stored in the Master Control File.
  • Current Source CCID and/or comment
    The CCID and/or comment used the last time an
    Endevor
    action changed the source. This CCID and/or comment is stored in the Master Control File.
  • Generate CCID and/or comment
    The CCID and/or comment used the last time an
    Endevor
    action caused output processing to occur. Output processing occurs when a processor is run or an output data set is updated. This CCID and/or comment is stored in the Master Control File.
  • Retrieve CCID and/or comment
    These fields only reflect the CCID and/or comment used during the RETRIEVE action if the last action at that stage was RETRIEVE. This CCID and comment are stored in the Master Control File. Viewing this information lets you determine which elements have been retrieved for update by project.
  • Source Delta CCID and/or comment
    Each delta level contains the CCID and/or comment specified in the action that created the delta level.
  • Component List Delta CCID and/or comment
    Each component list delta level contains the CCID and/or comment specified in the action that created the delta level.
Specify Required CCIDs
During your
Endevor
implementation, decide whether to require CCID and/or comments. You can require the use of CCIDs and/or comments on a system-by-system basis.
Follow these steps:
  1. Select option
    3
    on the Environment Options Menu and press Enter.
    The System Request panel appears.
  2. Type
    U
    in the COMMAND field, enter the environment name in the ENVIRONMENT field, and press Enter.
    The System Definition panel appears.
  3. Enter
    Y
    in the CCID and/or COMMENT fields, and press Enter to save your changes.
    If you do not specify a CCID and/or comment when one is required for the action you are requesting,
    Endevor
    displays the Action Prompt panel. To complete your action request, type a valid CCID and/or comment and press Enter.
Predefine CCIDs
Predefining CCIDs lets you perform the following:
  • Validate CCIDs entered by users against the predefined CCIDs.
  • Associate user IDs or specific inventory areas with certain CCIDs.
You can predefine CCIDs in one of the following ways:
  • Define a CCID definition data set within
    Endevor
    .
  • Use a product such as IBM Tivoli Information Management for z/OS;
    Endevor
    provides an interface for this product.
  • Create your own file;
    Endevor
    provides a user exit capability so you can define your own CCID definition file.
This section contains information about CCID validation in
Endevor
and about the CCID definition data set that you can define within
Endevor
.
CCID Validation
If you have predefined CCIDs, the CCID definition file is read into memory at
Endevor
startup. Changes to the definition file during an
Endevor
work session do not take effect until you exit
Endevor
and then re-enter the system.
CCID validation processing takes effect at the time an action is performed. That is, a batch action could be built (using the batch or package construction screens), but denied at execution time.
If the system you are working with is defined with CCID required, then a valid CCID must be specified for all actions requiring a CCID. If the system you are working with is not defined with CCID required, the CCID is not validated and any value including no CCID (spaces) for the action is allowed.
CCID validation applies only to specific actions. This processing is not applicable with the LIST or PRINT actions, because you cannot specify a CCID for these actions. Additionally, CCID validation is not performed for the MERGE action.
Create a CCID Definition Data Set
You can define and maintain CCIDs in a sequential file that you identify in the Defaults Table. This file is optional. This file lets you predefine CCIDs and associate each CCID, with user IDs and/or
Endevor
inventory areas.
When a CCID is specified in an
Endevor
action,
Endevor
validates that CCID against the contents of this data set. It determines whether the user is authorized to use the specified CCID with the inventory area against which the action is being performed.
You must maintain the definition file using the ISPF (or any other) text editor or by creating the file from your existing project management system. The definition file must be a card-image data set (80-byte, fixed-format records).
The format of the records in the CCID definition file is variable; the records may be comments ("comment lines") or definitions ("definition lines"). CCIDs are required on every definition line; optionally, a TSO user and/or
Endevor
element identification information (environment, system, subsystem, element name, type, and stage) can be given.
Follow these steps:
  1. Allocate that CCID validation data set. Use the standard ISPF data set utilities, option 3.2 from the ISPF/PDF Primary Options menu. Allocation the data set with the following attributes: LRECL=80, RECFM=FB, DSORG=PS, and BLKSIZE=any multiple of 80. The data set name must be the same as that specified for the CIPODSN parameter in the Defaults table. The data set name can be any valid name that conforms to your site naming conventions.
    When you create the sequential file, be sure to specify a data set name in the format: project.dataset.type, where
    type
    is a unique value. This causes the ISPF editor to use a unique profile for the data set.
  2. Initialize the data set by copying member SAMPCIPO from the iprfx.iqual.CSIQJCL library into the allocated data set. SAMPCIPO is a sample CCID definition data set that is distributed with the
    Endevor
    system. You can use SAMPCIPO to build a data set appropriate to the needs of your organization. Because
    Endevor
    requires information to be placed in certain columns, we recommend that you copy member SAMPCIPO into the data set. By using this member as a template, you can ensure that the fields in the data set are positioned in the correct columns. Use the standard ISPF copy utility-option
    3.3
    on the ISPF/PDF Primary Option Menu-to copy SAMPCIPO from the sample JCL library (iprfx.iqual.CSIQJCL) into the data set. Use the ISPF edit service to tailor the data set to meet the requirements of your site.
  3. Add the Data Set Name to the Defaults table, by adding the data set name to the CIPODSN parameter. Do not update the CIPODSN parameter in the Defaults Table before allocating the CCID validation data set. If CIPODSN contains a non-null entry,
    Endevor
    assumes that the entry is a data set name and looks for that data set during initialization. If
    Endevor
    cannot find the data set, it generates an error message. Therefore, before using
    Endevor
    , ensure that the CCID validation data set is allocated and defined appropriately.
Sequential Data Set Purpose
There are two reasons why a sequential data set is used for CCID definition:
  • A sequential data set allows you to use the standard ISPF text editor for editing.
  • A sequential data set allows you to off-load project management information from an existing application (such as IBM Tivoli Information Management for z/OS) and construct the data set using an application program.
To assist in the building of the application program, an assembler macro has been supplied with the system. The macro resides in the installation source library (
iprfx.iqual.CSIQOPTN
) built during Step 1 of the
Endevor
installation process. The member name of the macro is $CIPOREC.
To write a program to create a CCID definition data set, use the record layout that is specified in $CIPOREC, using your own data.
Editing the File Using the ISPF Text Editor
Setting up a CCID definition file as a sequential file allows you to use the ISPF text editor to edit the file, as follows.
1. Enter the following primary commands:
TABS ON; CAPS ON; NULLS OFF
2. Set your tab positions as follows:
* * * * * * * * 3 16 25 34 36 45 54 63
Using the CCID Definition Data Set
The CCID definition data set can be used to register the names of CCIDs. The CCID definition data set can also contain user and/or element identification data.
Using the CCID definition feature with this additional information can assist you in project management. You can create multiple lines in the CCID definition data set for each valid CCID. For a CCID value, these successive lines specify the users allowed to work under this CCID, the inventory items/areas which may be worked on, or both.
For example, assume that a site has two projects: TAX-CHNG-89 and NEW-COMPPLAN. Only people in the Development Department (TSO user IDs: DEVxxx) are allowed to perform changes as part of these projects. The inventory areas for the changes are as follows:
  • Environment =
    DEMO
  • Stage number =
    1
  • Systems for TAX-CHNG-89 =
    PAYROLL
    and
    ACCOUNTG
  • Systems for NEW-COMPPLAN =
    PAYROLL
    and
    PERSONEL
The CCID definition file would be coded as:
card position 3 16 25 34 36 45 54 63 * CCID USERID ENVIRON # SYSTEM SUBSYS TYPE ELEMENT TAX-CHING-89 DEV* DEMO 1 PAYROLL TAX-CHING-89 DEV* DEMO 1 ACCOUNTG NEW-COMPPLAN DEV* DEMO 1 PAYROLL NEW-COMPPLAN DEV* DEMO 1 PERSONEL
Sample CCID Definition Data Set
The following is a sample CCID definition data set.
card position 3 16 25 34 36 45 54 63 * CCID USERID ENVIRON # SYSTEM SUBSYS TYPE ELEMENT AC-DEV-89/02 ZSXBAP1 DEMO 1 ACCOUNTG MA-DEV-89/02 ZSX* DEMO 1 MANUFACT PE-DEV-89/02 ZSXJMH1 DEMO 1 PERSONEL PE-DEV-89/02 ZSXPGM1 DEMO 1 PERSONEL PE-DEV-89/02 ZSXSXV1 DEMO 1 PERSONEL QA-89/02 ZSXREL1 DEMO 2 * * * * EMERGENCY-FIX 2
The following coding conventions apply to this data set:
  • Any line that begins with an asterisk (
    *
    ) in column 1 is considered a comment line.
  • Every non-comment line is considered a definition line, and must specify a CCID.
    The CCID field is always required.
  • All other fields on a definition line are optional. If any field is left blank (such as the SUBSYSTEM field for the first five lines listed in the previous sample), it is ignored.
  • Name masks (for example, ZSX* or simply
    *
    in the previous sample) can be used in any of the optional fields. Imbedded asterisks are not allowed.
A description of each field and its card position are shown in the data set that follows:
  • CCID (3)
    The name of the CCID. The name must be fully specified, defining a valid CCID. This value must be specified on every definition line. The same CCID may appear on multiple lines.
  • Userid (16)
    (Optional) If used, only the users whose user ID is specified (whether by full name or with the use of a name mask) may use the CCID indicated on this line.
  • Environ (25)
    (Optional) Environment name. If used, only elements in the environment specified (whether by full name or with the use of a name mask) can be updated under the CCID indicated on this line.
  • # (34)
    (Optional) Stage number. If used, only elements in the stage specified (1, 2, or *) can be updated under the CCID indicated on this line.
  • System (36)
    (Optional) System name. If used, only elements in the system specified (whether by full name or with the use of a name mask) can be updated under the CCID indicated on this line.
  • Subsys (45)
    (Optional) Subsystem name. If used, only elements in the subsystem specified (whether by full name or with the use of a name mask) can be updated under the CCID indicated on this line.
  • Type (54)
    (Optional) Element type. If used, only elements of the type specified (whether by full name or with the use of a name mask) can be updated under the CCID indicated on this line.
  • Element (63)
    (Optional) Element name. If used, only elements whose names are specified (whether by full name or with the use of a name mask) can be updated under the CCID indicated on this line.
How Element Actions Update CCIDs or Comments
You can specify a CCID and/or a comment when requesting
Endevor
to perform the following actions:
  • ADD
  • UPDATE
  • RETRIEVE
  • GENERATE
  • MOVE
  • TRANSFER
  • DELETE
  • RESTORE
Endevor
uses the CCID and/or comment that you specify for the action to update one or more of the following fields:
  • Master Control File fields:
    • CURRENT SOURCE CCID and/or COMMENT
    • GENERATE CCID and/or COMMENT
    • RETRIEVE CCID and/or COMMENT
    • LAST ACTION CCID and/or COMMENT
  • SOURCE DELTA CCID and/or COMMENT
  • COMPONENT LIST DELTA CCID and/or COMMENT
The fields that
Endevor
updates depend on the action you specify. The following sections on specific actions provide details on which of the CCID and/or COMMENT fields are updated, and under what circumstances.
Add Action CCID Updates
When you specify a CCID and/or comment in an ADD action,
Endevor
updates CCID and/or COMMENT fields differently depending on whether you are adding a new element or an existing element.
Specifying an Add Action for a New Element
— When you specify a CCID and/or comment in an ADD action for a new element,
Endevor
uses this CCID and/or comment to set the following fields:
  • LAST ACTION CCID and/or COMMENT fields.
  • CURRENT SOURCE and SOURCE DELTA CCID and/or COMMENT fields.
  • GENERATE and COMPONENT LIST DELTA CCID and/or COMMENT fields if the generate processor is run.
  • CCID is held for the AUTOGEN option.
In addition, the first time an element is added to
Endevor
the comment specified is stored separately. This comment appears in the ELEMENT DESCRIPTION field of the Master Control File display, and remains with the element as long as it resides in
Endevor
.
Specifying an Add Action for an Existing Element—
When you specify a CCID and/or comment in an ADD action for an existing element,
Endevor
uses this CCID and/or comment to set the following fields:
  • LAST ACTION CCID and/or COMMENT fields.
  • CURRENT SOURCE and SOURCE DELTA CCID and/or COMMENT fields if the element has changed.
  • GENERATE CCID and/or COMMENT fields if the generate processor is run.
  • COMPONENT LIST DELTA CCID and/or COMMENT fields if the component list has changed.
  • CCID is held for the AUTOGEN option.
Endevor
also clears the Stage 1 RETRIEVE CCID and/or COMMENT fields when you add an existing element.
If you specify the BYPASS GENERATE PROCESSOR option, the ADD action does not set the generate or component list delta CCID and/or COMMENT fields.
Update Action CCID Updates
When you specify a CCID and/or comment in an UPDATE action for an existing element,
Endevor
uses this CCID and/or comment to set the following fields:
  • LAST ACTION CCID and/or COMMENT fields.
  • CURRENT SOURCE and SOURCE DELTA CCID and/or COMMENT fields if the element has changed.
  • GENERATE CCID and/or COMMENT fields if the generate processor is run.
  • COMPONENT LIST DELTA CCID and/or COMMENT fields if the component list has changed.
  • CCID is held for the AUTOGEN option.
Endevor
also clears the Stage 1 RETRIEVE CCID and/or COMMENT fields when you UPDATE an element.
If you specify the BYPASS GENERATE PROCESSOR option, the UPDATE action does not set the generate or component list delta CCID and/or COMMENT fields.
Retrieve Action CCID Updates
When you specify a CCID and/or comment in a RETRIEVE action for an existing element,
Endevor
uses this CCID and/or comment to set the RETRIEVE CCID and/or COMMENT fields.
Generate Action CCID Updates
When you specify a CCID and/or comment in a GENERATE action,
Endevor
updates CCID and/or COMMENT fields differently depending on whether you specify the GENERATE action with or without copyback.
Specifying a Generate Action without Copyback—
When you specify a CCID and/or comment in a GENERATE action without copyback,
Endevor
uses this CCID and/or comment to set the following fields:
  • LAST ACTION CCID and/or COMMENT fields.
  • GENERATE CCID and/or COMMENT fields.
  • COMPONENT LIST DELTA CCID and/or COMMENT fields if running the generate processor causes the component list to change.
Specifying a Generate Action with Copyback—
When you specify a CCID and/or comment in a GENERATE action with copyback,
Endevor
uses this CCID and/or comment to set the following fields:
  • LAST ACTION CCID and/or COMMENT fields at the generate location.
  • GENERATE and COMPONENT LIST DELTA CCID and/or COMMENT fields at the generate location.
Endevor
also sets current source and source delta CCID and/or COMMENT fields to the value associated with the element that is copied back.
Move Action CCID Updates
When you specify a CCID and/or comment in a MOVE action,
Endevor
updates CCID and/or COMMENT fields differently depending on whether you specify the MOVE action with history or without history.
Specifying a Move Action without History—
When you specify a CCID and/or comment in a MOVE action without history,
Endevor
uses this CCID and/or comment to set the LAST ACTION CCID and/or COMMENT fields.
Endevor
also performs the following actions:
  • Sets the target CURRENT SOURCE and GENERATE CCID and/or COMMENT fields to their value at the starting location of the MOVE.
  • Sets the target SOURCE DELTA and COMPONENT LIST DELTA CCID and/or COMMENT fields to their last value at the starting location of the MOVE.
  • Clears the RETRIEVE CCID and/or COMMENT fields.
Specifying a Move Action with History—
When you specify a CCID and/or comment in a MOVE action with history,
Endevor
uses this CCID and/or comment to set the LAST ACTION CCID and/or COMMENT fields.
Endevor
also performs the following actions:
  • Sets the CURRENT SOURCE and GENERATE CCID and/or COMMENT fields to their start location value.
  • Moves SOURCE DELTA and COMPONENT LIST DELTA CCIDs and COMMENTs with their respective delta levels.
  • Clears the RETRIEVE CCID and/or COMMENT fields.
Transfer Action CCID Updates
When you specify a CCID and/or comment in a TRANSFER action,
Endevor
updates CCID and/or COMMENT fields differently depending on whether you specify the TRANSFER request without history, with history, or with synchronization.
Specifying a Transfer Action without History—
When you specify a CCID and/or comment in a TRANSFER action without history,
Endevor
uses this CCID and/or comment to set the following fields:
  • LAST ACTION CCID and/or COMMENT fields.
  • GENERATE and COMPONENT LIST DELTA CCID and/or COMMENT fields if the generate processor is run.
Endevor
also:
  • Sets the CURRENT SOURCE CCID and/or COMMENT fields from their value in the previous stage.
  • Sets the SOURCE DELTA CCID and/or COMMENT fields from their last delta value in the previous stage.
  • Clears the RETRIEVE CCID and/or COMMENT fields.
Specifying a Transfer Action with History—
When you specify a CCID and/or comment in a TRANSFER action with history,
Endevor
uses this CCID and/or comment to set the following fields:
  • LAST ACTION CCID and/or COMMENT fields.
  • GENERATE and COMPONENT LIST DELTA CCID and/or COMMENT fields if the generate processor is run.
Endevor
also performs the following actions:
  • Sets the CURRENT SOURCE CCID and/or COMMENT fields from their value in the previous stage.
  • Moves SOURCE DELTA CCIDs and COMMENTs with their respective delta levels.
  • Clears the RETRIEVE CCID and/or COMMENT fields.
Specifying Synchronize along with the Transfer with History—
Endevor
creates a synchronize source delta level. When
Endevor
creates this synchronize delta level, it performs the following actions:
  • Sets the CCID and/or COMMENT fields from the base value.
  • Sets the synchronize flag to indicate that this source delta level was created as a result of the synchronize option.
If you specify the BYPASS GENERATE PROCESSOR, the TRANSFER action does not set the generate or component list delta CCID and/or COMMENT fields.
Delete Action CCID Updates
If you specify a CCID and/or comment on a DELETE action, that CCID and/or comment is logged to SMF (if SMF logging is being performed). The CCID and/or comment is available to
Endevor
exits.
Restore Action CCID Updates
When you specify a CCID and/or comment in a RESTORE action for an existing element,
Endevor
uses this CCID and/or comment to set the following fields:
  • LAST ACTION CCID and/or COMMENT fields.
  • GENERATE and COMPONENT LIST DELTA CCID and/or COMMENT fields if the generate processor is run.
Endevor
sets the CURRENT SOURCE, SOURCE DELTA, and RETRIEVE CCID and/or COMMENT fields based on the contents of the archive data set from which you restore.
If you specify the BYPASS GENERATE PROCESSOR, the RESTORE action will not set the generate or component list delta CCID and/or COMMENT fields.
Summary CCID Impact Chart
The following chart summarizes the impact of
Endevor
actions on the six fields that each action may update with the CCID and/or comment information that you specify for the action:
Action
Current Source CCID/ Comment
Generate CCID/ Comment
Last Action CCID/ Comment
Retrieve CCID/ Comment
Source Delta CCID/ Comment
Component CCID/ Comment
Add (new element)
Set
Set if changed
Set
Set
Set if generated
Add (existing element)
Set if changed
Set if generated
Set
Set
Set if generate creates a delta
Update
Set if changed
Set if generated
Set
Set if changed
Set if generate creates a delta
Retrieve
Set
Generate without copyback
Set
Set
Set if generate creates a delta
Generate with copyback
Set to copied back value
Set
Set
Set to copied back value
Set
Signin
Clear
Delete
Restore
Set from archive
Set if generated
Set
Set from Archive
Set from Archive
Set if generated
Archive
Move without history
Set from start location value
Set from start location value
Set
Clear
Set from last start location delta value
Set from last start location delta value
Move with history
Set from start location value
Set from start location value
Set
Clear
Carried with delta levels
Carried with delta levels
Transfer without history
Set from previous stage value
Set if generated
Set
Clear
Set from last delta value previous stage
Set if generated
Transfer with history
Set from previous stage value
Set if generated
Set
Clear
Carried with delta levels
Set if generated
Transfer with SYNC
Set from previous stage value
Set if generated
Set
Clear
Set from base value. Carried with delta levels + on SYNC level
Set if generated