Altering Element Record Metadata

This article explains how to alter Master Control File Element metadata, how to set up the Alter action, and how to review Alter action activity.
ce18
This article explains how to alter Master Control File Element metadata, how to set up the Alter action, and how to review Alter action activity.
 
 
 
2
 
 
How to Alter Master Control File Element Metadata
The Alter action changes Element metadata in the Master Control File and some changes cannot be easily reversed. Before you submit an Alter statement, we recommend that you back up the Master Control Files. If you wanted to undo changes, it might be easier to restore the Master Control Files. Otherwise, to undo changes that were made using name-masked values, you would probably need to code multiple Alter statements.
You can use the Alter action to change Element master record information (Element metadata) in the Master Control File. You specify an Element and what changes you want made to its metadata. Different metadata fields and multiple Element instances can be changed by the same Alter action. The Element metadata is changed at the location where the matching elements are found; the Alter action never fetches the Element.
The Alter action can be executed in Update or Noupdate mode. Noupdate mode produces the same output messages as Update mode; however the Master Control File Element record is not updated. Noupdate mode is an analysis tool that lets you see what effect the Update mode would have before you run it.
The Alter action is an Element action and is processed similarly to other Element actions, for example, the Add, Delete, Generate actions. However, the Alter action does not execute processors.
Using the Alter action, you can change the following Master Control File Element record metadata fields:
  •  
    Generate CCID
    CCID for the last Add, Update, Generate, Move, or Transfer action that executed the Generate processor against the Element.
  •  
    Last action CCID
    CCID for the last action that modified the Element.
  •  
    Retrieve CCID
    CCID for the last Retrieve action that was executed against the Element.
  •  
    Processor Group name
    Current Processor Group for the Element.
  •  
    Signout UserID
    Current user ID to which the Element is signed out.
  •  
    Description
    Base description for the Element. This value is usually set by the Comment field when the Element is added.
  •  
    User Data
    An 80-byte field stored with the Element. This value can also be set using a User Exit 2 (before action) program on an Add, Update, or Generate action.
To change the Master Control File element metadata, code the Alter statement. Submit the Alter statement for batch processing or include it in a Package. Packages can be submitted in foreground or batch. The Alter action is not available from the Foreground Options menu. Alter statements can be submitted from the Batch Options menu, but the SCL Generation menu does not have an option for the Alter action.
 For more information about the SCL syntax for the Alter statement, see Alter Statement.
Alter Statements in Packages
You can include Alter statements in a Package. Packages can be submitted in foreground or batch, including those packages that contain Alter statements. However, the following limitations apply:
  • When you create or modify a Package, you cannot use the Build Package Actions option on the Create/Modify Package panel to build the Alter action. The Build Package Actions option does not support building the Alter action.
  • When submitted in a Package, valid Alter statement syntax is restricted as follows:
    • Wildcarding or masking of the from location fields (Environment, System, and so on) is not permitted.
    • The Alter action Search option is not permitted in a Package and if coded, the Package cast will fail.
  • The default settings in the Optional Features table that affect package processing can be adjusted depending on the preferences of the administrator. For more information about the Optional Features table, see How to Set Up the Alter Action.
Alter Action Security
Functional security settings, Element signout metadata, and the locking of Elements during Alter action processing control who can update which Elements. Alter action processing is secured by the following controls:
  • Functional security -- The Alter Action uses 
    Endevor
     security to verify that a user is authorized to perform the requested actions against the Element. The following security checks are performed:
    • Does the user have retrieve authority for the Element at the inventory location at which it is found? This check is performed before altering an Element.
    • Does the user have Override Signout authority at the inventory location at which the Element is found? This check is performed when the Override Signout clause is specified and the Element is not signed out to the current user.
    • Does the user have Alter authority for the Element at the target Stage and Environment?
    • Does the user have authority to alter the specific metadata field that they are attempting to update?
    For information on how to setup security, see How to Set Up the Alter Action.
  • Signout UserID -- The Alter Action does not alter Elements that are signed out to users other than the current user, unless the Override Signout option is specified.
    • To perform the Alter action when the Element is signed out to someone else, Override Signout must be used and the corresponding authority granted.
    • The Alter action retains the current Signout Userid for the Element; it does not update the Signout UserID with the user ID of the person performing the Alter action. If you want the Signout Userid Element field to be changed as part of the Alter action, use the Replace Signout UserID clause.
  • Element locking -- Serializing the Element applies to Update mode and Noupdate mode. The Alter action puts a lock on an Element when it is being processed. The following search criteria determine which Elements get locked:
    • When the Search option is specified -- At the first Environment where the Element is found in the logical map when Search First option is used, or at all Environments where the Element is found in the logical map when the Search All option is used.
    • When the Nosearch option is specified -- At the Environment specified, or if name-masking was used, at all the Environments that match the specified request.
Alter Action Processing
Alter action processing has the following conditions and results:
  • Alter actions are processed in Type Sequence order and follow the same Type Sequence rules as other Element actions.
  • Concurrent Action Processing supports the Alter action. If Concurrent Action Processing is enabled and requested, Alter actions are processed concurrently in Type Sequence order.
  • The Alter action does not execute processors.
  • Whenever an Element metadata field is updated, an SMF record is written for the updated field. The Element metadata field is updated and the SMF record is written, even if the Element metadata field value is identical before and after the update.
  • The Alter Action invokes the following 
    Endevor
     User Exits: User Exit 1 (security), User Exit 2 (before action), and User Exit 3 (after action).
    • A User Exit 2 or User Exit 3 program can query all the Alter fields that are defined in the assembler $ALTRDS User Exit block or the COBOL ALTER-ACTION-BLOCK of EXITBLKS, but none of these fields can be modified.
    • A User Exit 2 program can modify the action CCID, the action Comment, and the Override Signout (Y/N) options located in the assembler $REQPDS block or REQUEST-INFO-BLOCK of the COBOL Exit block EXITBLKS.
      The signout check is performed on the Element at the target location after the User Exit 2 call, but before matching and Alter action processing are performed.
    • The Signout Userid and User Data Exit Request block fields cannot be modified for the Alter action.
    • The SMF record is not passed to the User Exit 3 program for the Alter action.
    • The Alter action exit control block contains information associated with the Alter action. This block is pointed to by the primary information exit control block. This block is only available at the time of User Exit 2 and User Exit 3 calls for the Alter action.
    • A separate call to the security exit is performed for each field that is specified in an Alter action request. All fields in the Alter request are verified, even if a security failure occurs on a field. However, if any of the fields fail the security check, the entire action will fail and none of the Alter fields will be updated. 
    • To make the value of ALTERFLD available for user Exit 1 programs, the new field ECBALTRF is added to the assembler control block ($ECBDS DSECT). For the COBOL control block, the new field is ECB-ALTER-FIELD.
How to Set Up the Alter Action
To enable the Alter action, the 
Endevor
 administrator must ensure that the prerequisites are complete for functional security, Type Sequencing, and SMF recording. Optionally, the administrator can adjust the default settings in the Optional Features table that affect package processing depending on how they want the Alter action to be used in packages.
  •  
    Enable Alter action security
     -- The 
    Endevor
     administrator works with the site security administrator to enable certain user IDs to perform the Alter action.
    • The 
      Endevor
       administrator reviews the BC1TNEQU table to determine if the delivered setting is appropriate for their site. Permission to process the Alter action is determined by the security authorization function (SAF) set in the External Security Interface (ESI) BC1TNEQU table. The following entry for the Alter action is included in the BC1TNEQU sample: FUNCEQU SAFAUTH=ALTER,C1ACTNS=(ALTER). As delivered, the SAF authorization value of Alter is equated with the Alter access level (c1access). This entry restricts access to the Alter action to users who have ALTER authority for the ESI pseudo data set name.
       If you already have a BC1TNEQU table in place, you must add a statement for the Alter action to control its use; otherwise, 
      anyone can execute the Alter action
      .
    • In addition, the administrator can add the ALTERFLD keyword to a level of the NAMEQU for the ACTION_INITIATION  entry of the BC1TNEQU table for more granular control of access to the Alter action. The administrator can limit who can perform Alter action updates on Element record metadata depending on which metadata field the user is attempting to update. When the security exit encounters an Alter action and builds the pseudo data set, a value that corresponds to the metadata field specified on the Alter action is substituted for the ALTERFLD node on the pseudo data set name. Your security administrator can configure your site's security software to restrict users from this pseudo data set based on their user profile. Thus, the External Security Interface and your security software can limit who can perform updates on specific metadata fields.
    • The site security administrator ensures that the appropriate user IDs are associated to the Alter access level. If the ALTERFLD is coded, the security administrator ensures that the appropriate user IDs are permitted to access the pseudo data sets that enable access to the Alter action depending on the field being requested.
 
Note:
 For more information about security, see 
ALTERFLD
 in the article Name Equates Table.
  •  
    Enable Type Sequencing
     -- Type Sequencing may already be enabled at your site, because it is a prerequisite for SCL statement processing. Type Sequencing determines the order in which Types are processed in batch. For Type Sequencing to be in effect, both the Parmlib data set and the Type Sequence member must be defined to the Defaults table C1DEFLTS.
  •  
    Enable the SMF option
     -- The SMF option may already be enabled at your site, because it is a prerequisite for other functions. The SMF option can record each action and each security violation that occurs during 
    Endevor
     processing and is set per Environment.
    For the SMF option to be in effect, the Defaults table (C1DEFLTS) must include the following parameters:
    • The SMFREC# parameter must be set in the TYPE=MAIN portion of the Defaults table. SMFREC# sets the SMF record number that is assigned to SMF records written by 
      Endevor
       at this site.
    • The parameter SMFACT=Y must be set in the TYPE=ENVIRONMENT portion of the Defaults table to write out SMF action records.
    If you want to track security violations for your own auditing purposes, make sure that SMFSEC=Y is set in the TYPE=ENVIRONMENT portion of the Defaults table to write out SMF security records.
    For more information about the SMF option, see SMF Recording.
  •  
    (Optional) Configure Package Processing Options 
    -- The Optional Features table includes the following options that affect package processing. Depending on how you want the Alter action to be used, adjust the default settings as appropriate:
    •  
      Limit processing to one action in the same package
       -- (Optional) You can limit package processing to one action against the same Element instance within the same package. This option disallows additional actions that modify the same Element instance within the same package. This restriction applies to any action, not only to Alter actions. The following message is delivered with the severity level of C (for caution with a return code of 8):
      C1G0507C ELEMENT IS REFERENCED BY MULTIPLE ACTIONS WITHIN THIS PACKAGE
      To disallow more actions, set the severity level for this message to E (for error with a return code of 12) using this parameter in update the Optional features table, ENCOPTBL:
      ENHOPT MSGSEVERITY_C1G0507=C W/C/E O002833
    •  
      Allow nonpackage actions -- 
      (Optional) If you want to use the Alter action outside of a package against an Element in an inventory location that usually requires a package, add the Alter action to this option:
      ALLOW_NON_PKG_ACTIONS -- Specifies actions that can be performed outside of a package, even if the inventory location would usually require a package.
    •  
      Allow packages containing Alter actions only to skip approval process -- 
      (Optional)
       
      If you want to use the Alter action in a package, but want to skip the package approval process, add the Alter action to this option:
      PKG_ACTIONS_NO_APPRVR -- Specifies actions in a package that do not require approval.
Review Alter Action Activity
To view or verify the effects of an Alter action on an Element, you have the following options:
  •  View the Element master panels for the following information:
    • Current metadata values for the Element, which may have been changed by Alter actions, including the User Data field.
    • Metadata about Alter actions that were performed against the Element.
  • Print the Element master to view the current metadata, which may have been changed by Alter actions. Currently, printing the Element master does not print the User Data field or the metadata about the Alter actions that were performed against the Element. For more information about how to print, see 
    Printing Element Information Using the Print Elements Action
    .
  • Review the Alter action metadata fields returned by the List Element function. You can use the following options to access this data:
    • An API program. For more Information about the Alter action metadata response structure fields for the API function List Element, see Information about Alter Action Metadata in API Function Calls.
    • The Comma Separated utility. For more information about the Alter action metadata fields extracted by the List Element option of the Comma-Separated utility, see Alter Action Metadata, in Comma-Separated Value (CSV) Utility.
Alter Action Messages and Return Codes
You can review the messages and return codes issued during Alter action processing to verify that the intended action was performed.
By default the Action Execution report and the Action Summary report are written to the C1MSGS1 DD statement. If your batch execution JCL is coded with the C1MSGS1 and C1MSGS2 DD statements the Action Execution Report is written to the C1MSGS1 file and the Execution Summary report is written to the C1MSGS2 file. The execution report can be viewed online by browsing data sets userid.C1TEMPR1.MSGS or userid.C1TEMPR2.MSGS.
Various messages are issued during Alter action processing, including the following:
  • If the from-value is omitted or fully wildcarded, the mask-value in message
     C1G0076I
     is set to an asterisk:
    C1G0076I MASK:
    FIELD-NAME MASK-VALUE
  • The Alter action changes the Master Control File for each matching Element at the location where the Element resides. No copyback logic occurs. Message C1G0280I prints the location where the Element was located and updated:
    C1G0280I ELEMENT AT LOCATION
    environment/stage id/system name/subsystem name/type name
    SELECTED FOR PROCESSING
  • C1MSGS2 Summary Report -- Return codes indicate whether all, some, or no fields matched the mask. *NOUPDT* denotes Noupdate mode in which no updates were performed.
Return codes are associated with certain conditions. In the following descriptions of the return codes, the Replace clause matches when the Alter action statement specifies a value for the Master Control File field you want to replace and the specified value matches what is currently in the Master Control File field.
  • When Noupdate is active, report messages and return codes simulate what would happen in Update mode.
  • When the “EXACT MATCH” option is specified to alter the Description, Last Action CCID, Generate CCID, or Retrieve CCID, the original value of the supplied from-value is shown in message C1G0076I.
  •  
    RC=0 
    Indicates that the Alter request completed 100% successfully. All requested Master Control File fields are (or will be) updated as specified by the submitted Alter action syntax. RC=0 is returned in the following cases:
    • All Replace clauses match and Update option is specified, therefore the Master Control File record is updated.
    • All Replace clauses match but Noupdate option is specified, therefore the Master Control File record is
       not
       updated.
    • No from-value is provided and Update option is specified. The Master Control File record is updated.
    • No from-value is provided and Noupdate option is specified. The Master Control File record is
       not  
      updated.
  •  
    RC=4 
    Indicates that the Alter request only partially completed. One or more of the request fields in the SCL are not (or will not be) updated. RC=4 helps you to determine that some Master Control File fields were updated successfully, but not all, without having to read all report messages. RC=4 is returned in the following cases:
    • Some Replace clauses match and Update option is specified, therefore only the matched Master Control File fields are updated, while the non-matched fields are bypassed.
    • Some Replace clauses match but Noupdate option is specified, therefore the Master Control File record is 
      not
       updated.
    • No Elements found.
  •  
    RC=8 
    Indicates that no from-values matched the current Master Control File fields for any of the replace clauses specified. RC=8 lets you quickly determine which Elements were not updated at all; identify possible error conditions or an invalid SCL request. RC=8 is returned in the following cases:
    • No Replace clauses match and Update option is specified, therefore the Master Control File record is 
      not
       updated.
    • No Replace clauses match and Noupdate option is specified, therefore the Master Control File record is 
      not
       updated.
  •  
    RC=12
    Indicates invalid syntax or specification.
Element Master Information About Alter Actions
The Element Master panels display metadata values for a particular Element. The following types of information are displayed:
  •  
    Current metadata values for the Element
  •  
    View the current metadata for the Element to verify that the metadata values are as you expected.
  •  
    Information about Alter actions that were performed against the Element (Alter action metadata)
    The Alter Action section of the Element record in the Master Control File provides information about the Alter actions that were run against the Element. This metadata concerns the Alter action itself, for example the last date and time that the Alter action was run against the Element. You can see this Alter action metadata displayed on the last panel of the Element Master panel in the Alter Action section.
    Navigate to the end of the last Element Master panel to find the Alter Action section. Review the following fields in the Alter Action section to see information about the Alter actions that were run against this Element:
    •  
      First Date/Time
      Indicates the date and time that the first Alter action was performed against this copy of the Element.
    •  
      Cumulative # of Fields Altered
      Indicates the total number of times that fields were updated by all the Alter actions performed against this copy of the Element.
    •  
      Last Date/Time
      Indicates the date and time that the last Alter action was performed against this copy of the Element. If the First Date/Time matches the Last Date/Time, then the Alter action was only run once.
    •  
      Last UserID
      Indicates the user ID associated with the last Alter action performed against this copy of the Element.
    •  
      Fields Updated by the Last Alter Action
      Indicates whether any of the following Master Control File Element record metadata fields were updated for the last date and time the Alter action was run against this Element: Generate CCID, Last Act CCID, Retrieve CCID, Description, Processor Group, Signout UserID, and User Data. Valid values are Y for yes or N for no.
      These fields are reset after every Alter action. For example, if an Alter action replaced the Generate CCID and the Last Action CCID, then those field values would be Y and the other values would be N. If the next Alter action replaced the Processor Group, then only the Processor Group would be Y and the other fields, including the Generate CCID and Last Action CCID, would be N.
 The Last Element Action section on the Element Master panels is not changed by the Alter action, or by Signin or Retreive.
Certain Element actions clear the Alter action metadata fields. For more information, see Element Actions that Clear Alter Action Metadata and Element Actions that Retain Alter Action Metadata.
Element Actions that Clear Alter Action Metadata
When actions are performed against an Element, the Alter action metadata fields are retained or cleared depending on the action. The Alter action metadata fields are 
cleared
 when the following actions are performed against an Element:
  • Add or Update that causes a fetch to the target location -- For example: Suppose you add an existing Element from a production Environment to a target location lower in the map. And suppose that the existing Element had been altered and had Alter metadata before it was fetched back to the target. Then the Element that was added at the target location, does not include the Alter action metadata.
  • Generate with Copyback or Nosource -- For example:
    • If you Generate Element Y at Stage 2 with Copyback to Stage 1, then the Alter metadata gets cleared at Stage 1.
    • If you Generate Element Y at Stage 2 with Nosource to Stage 1, then the Alter metadata gets cleared at Stage 1.
  • If your site uses the 
     
    Endevor
     Quick Edit
     option, when Edit is used to fetch an element back to a lower stage.
Element Actions that Retain Alter Action Metadata
When actions are performed against an Element, the Alter action metadata fields are retained or cleared depending on the action. The Alter action metadata fields are 
retained
 when the following actions performed against an Element:
  • Move -- For example: If you Move Element Y from Stage 2 with or without history, to the next location in the map, then the Alter metadata is retained at the target location. If the Bypass Element Delete option is coded on the Move action, the Alter metadata is retained at the source location.
  • Transfer -- For example: If you Transfer Element Y from Stage 2 to an archive file, then Transfer it back from the archive file, the Alter metadata is retained at the target location. This is true even if the target location is a different location than where it was archived from.
  • Restore
  • Generate in place
  • Update in place -- For example: If you Update Element Y that resides at Stage 1, then the Alter metadata is retained at Stage 1.
  • Archive
  • Copy
  • Delete only components
  • Signin
SMF Recording
You can audit Alter action activity by reviewing SMF records. SMF recording, which can record security violations and action activity, must be active to enable the Alter action.
  • Security records can show if a user attempted to perform an Alter action for which they do not have permission. For example, suppose someone attempted to alter an element at an Environment they did not have access to, an error would be produced. The security record would log who attempted to perform the failed action.
  • Activity records show if the Alter action was performed and what effect the action had on the Element record in the Master Control File.
Endevor SMF Reports
SMF historical reports summarize security violations and Element activity recorded by 
Endevor
. These reports are available when SMF logging is in use at your site and are generated using the SMF records written during 
Endevor
 processing. The following reports show Alter action activity:
CONRPT40 -- 
 Security Violation Summary. For each system requested, this report gives a detailed account of each security violation that occurred. Specifically, this report lists each attempt -- by any user -- to perform an unauthorized action. Attempts to perform unauthorized Alter actions are recorded.
CONRPT42 -- 
 Element Activity Profile. This report details each action performed against the Elements within a particular system, subsystem, Element type, and stage. Using this report, you can determine exactly which Elements were changed using the Alter action. Also, shown are the Replace clause specified on the Alter action and the Master Control File Element record value before and after it was replaced and the mask value that was specified on the Alter action. If the Replace User Data clause was specified, the additional parameters are shown.
API List SMF Function for Alter Action
The API List SMF function lets you list the SMF record data corresponding to activity related to 
Endevor
 actions. The ALSMFA_RS Response Structure includes Alter action fields that indicate the Master Control File Element record field to which the Alter action requested a change and whether the field was changed. The Alter action data area contains the before, after, and mask values for the Master Control File Element record field that was processed.
For more information about Alter action fields for the List SMF function, see the "ALSMFA_RS Response Structure Fields" section of List SMF Data.