The ADD statement allows you to add an element to an environment's entry stage in CA Endevor SCM. The entry stage for an environment is defined through the C1DEFLTS table.
The Add statement has the following syntax:
►►─ ADD ELEment ─ element-name ─┬──────────────────────────────┬──────────────►
└─┬─ THRough ─┬─ element-name ─┘
└─ THRu ────┘
►─ FROm ─┬─┬─ FILe ───┬─ dd-name ─────────────────────────────┬─ TO ─────────►
│ └─ DDName ─┘ │
├─ DSName ─ dataset-name ─┬────────────────────────┬─┤
│ └─ MEMber ─ member-name ─┘ │
└─ PATH ─ usspath ─ HFSFILE ─ filename ──────────────┘
►─ ENVironment ─ env-name ─ SYStem ─ sys-name ─ SUBsystem ─ subsys-name ─────►
►─ TYPe ─ type-name ─────────────────────────────────────────────────────────►
►─┬─────────────────────────────────────────────────────────────────────┬────►
└─ OPTion ─ ¤ ─┬────────────────────────────────────────────────┬─ ¤ ─┘
├─ CCId ─ ccid ──────────────────────────────────┤
├─ COMment ─ comment ────────────────────────────┤
├─ NEW VERsion ─ version ────────────────────────┤
├─ UPDate if present ────────────────────────────┤
├─ DELete input source ──────────────────────────┤
├─ OVErride SIGNOut ─────────────────────────────┤
├─┬─ BYPass GENerate PROcessor ────────────────┬─┤
│ └─ PROcessor GROup ─┬─ EQual ─┬─ group name ─┘ │
│ └─ = ─────┘ │
└─ AUTogen ─┬───────────────────┬────────────────┘
├─ SPAN NONe ───────┤
├─ SPAN ALL ────────┤
├─ SPAN SYStems ────┤
└─ SPAN SUBsystems ─┘
►─ . ────────────────────────────────────────────────────────────────────────►◄
Indicates the element or elements to be added. You can use a name-mask in the element name to specify more than one element. For more information about syntax rules, see Element Name Syntax Rules.
Indicates that a range of elements should be added, beginning with the element coded in the ADD ELEMENTS statement, up to and including the element specified in this statement. You can use a name-mask with the element name. If you use the THROUGH clause, however, you cannot enter a member name in the FROM clause.
Note: If you are working with a sequential file, the THROUGH clause is ignored.
The FROM clause indicates the location of the element being added. CA Endevor SCM uses both the FROM clause in the action and any preceding SET FROM clause to determine the "from" criteria for that action.
Note: For more information, see the description of the SET FROM statement in the chapter "Using Set, Clear, and EOF Statements."
The SET FROM statement allows you to specify only a file (DDname) or data set name, not a member name.
You must enter a FILE, DDNAME, DSNAME, or PATH in conjunction with HFSFILE (enter one and only one). If you enter either a FILE or DDNAME, be sure the appropriate JCL DD statement is coded.
Enter a member name if it differs from the element name specified in the ADD ELEMENTS clause. If you do not enter a member name, CA Endevor SCM assumes that the element name and member name are the same. If you provide a member name:
The USS directory where the element source file resides.
The file in the USS directory that you want to put under the control of CA Endevor SCM.
The TO clause indicates where the element is being added. CA Endevor SCM uses both the TO clause in the action and any preceding SET TO clause to determine the "to" criteria for that action.
Note: For more information, see the description of the SET TO statement in the chapter "Using Set, Clear, and EOF Statements."
You must specify an environment, system, subsystem, and type for the ADD action. Remember that you cannot use a name-mask with any field in the TO location.
OPTION clauses allow you to further specify action requests.
You can enter a 1- to 12-character CCID and/or a 1- to 40-character comment.
CCIDs and/or comments may be required. If you do not provide a required CCID and/or comment, the ADD action fails.
When you specify a CCID and/or comment in an ADD action, CA Endevor SCM treats the CCID and/or COMMENT fields differently depending on whether you are adding a new element or an existing element.
CA Endevor SCM also clears the environment's entry stage RETRIEVE CCID and/or COMMENT fields when you add an existing element. If you use the BYPASS GENERATE PROCESSOR option, the ADD action does not set the generate or component list delta CCID and/or COMMENT fields.
If the element exists up the map, the version number associated with the existing element will be assigned, by default. If the New Version clause is omitted and the element does not exist up the map, the element is assigned version 1. If the New Version clause is used and the element exists at the target location or at a location up the mapped route, the ADD action fails.
To successfully add an element to CA Endevor SCM, that element cannot currently exist in the entry stage.This also applies to a sourceless element. If the element is present in the entry stage, CA Endevor SCM returns an error message, regardless of whether the element at the entry stage is a sourced or sourceless element. The UPDATE IF PRESENT option, however, allows you to add the element even if it is in the entry stage, by automatically changing the ADD action to UPDATE.
After an element has been successfully added to CA Endevor SCM, you can use this option to remove the member from the library in which it originated.
If you input a sequential file, this option deletes that file.
If the element has been signed out to a person other than yourself, you must code this option to perform this action. This option updates the signout ID at the appropriate stage, with the user ID of the person performing the override. Use OVERRIDE SIGNOUT with caution to avoid regressing changes made by another user.
Use this option if you do not want the generate processor executed for the element. Otherwise, as part of normal processing, CA Endevor SCM looks for and executes the generate processor for the element when it is added.
You can specify that a particular processor group be used for this action. If you do not indicate a processor group and:
Applicable for Add, Update, and Generate actions in batch requests. This option cannot be used in packages and the option does not work if Bypass Generate Processor is set. The Global Type Sequencing batch processing method must be enabled. Autogen only acts on components whose Types are listed in the Global Type Sequencing table. If the component's Type is not listed in the Global Type Sequencing table, the Autogen request is ignored. In addition, your site must have purchased and activated the CA Endevor Automated Configuration. Autogen can be specified alone or with various Span keyword options. "Autogen Span" is not a valid option. Valid options follow:
Generates all elements that use the component that is the target of the action. These using elements are generated at the target location that is specified in the SCL statement. If they do not exist at the target location, they are brought back to the target location as sourceless elements. An administrator can change the behavior of the Autogen feature, by activating AUTOGEN_SOURCE in the Optional Features Table (ENCOPTBL). When this option is activated, the Generate actions for the using elements are built with the Copyback, instead of the NoSource, option. For more information about sourceless elements, see the NoSource option description in Generate Syntax.
Note: Using elements are elements that use the element that is the target of an Add , Update, or Generate action. For example, if Autogen is specified for copybook, COPYA, then the programs that use that copybook are known as using elements.
Generates all elements that use the component being acted upon. This option has the exact same effect as the option "AUTOGEN."
Generates using elements that are found in any System and Subsystem combinations within the Environment and Stage of the component's logical map.
Generates using elements found in any System, provided the element's Subsystem name matches the name of the Subsystem of the target component. Only Systems found within the Environment and Stage of the component's logical map or higher up the map are searched. This option is different from the Autogen option in that it includes additional Systems with the same Subsystem name in the search.
Generates using elements from all Subsystems with the same-named System of the component specified. Only Subsystem found in the System of the target component within the Environment and Stage of the component's logical map or higher up the map are searched. This option is different from the Autogen option in that it includes additional Subsystems with the same System in the search.
The following restrictions apply to the SPAN options:
Example: Add SCL
This SCL adds a new element to the Payroll reporting subsystem in the environment PROD. After the ADD action completes, the source member will be deleted.
ADD ELEMENT 'PAYRPT31'
TO ENVIRONMENT 'PROD'
SYSTEM 'PAYROLL'
SUBSYSTEM 'REPORTS'
TYPE ' COBOL'
FROM DSNAME 'PAYROLL.SRCLIB'
OPTIONS DELETE INPUT SOURCE
CCID REQ#43213
COMMENT 'ADD THE NEW PAYROLL REPORTING PROGRAM' .
Important: The Alter action changes Master Control File metadata and 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, you would probably need to code multiple Alter statements to undo changes that were made using name-masked values.
Use the Alter statement to change element record metadata in the Master Control File. The Alter action alters the element metadata at the location where the matching elements are found. The action never fetches the element back to the specified From location.
SMF recording must be active for any Environment in which you use the Alter action. If SMF recording is not active, the Alter action will fail. For more information about enabling SMF, see the Administration Guide.
Note: For more information about the Alter action, see the chapter "Altering Element Record Metadata" in the Administration Guide.
The Alter action statement has the following syntax:
►►─ ALTer ELEment ─ element-name ─┬──────────────────────────────┬───────────►
└─┬─ THRough ─┬─ element-name ─┘
└─ THRu ────┘
►─ FROm ─ ENVironment ─ environment-name ─ SYStem ─ system-name ────────────►
►─ SUBsystem ─ subsystem-name ─ TYPe ─ type-name ───────────────────────────►
►──┬─ STAge ─ stage-id ────────┬────────────────────────────────────────────►
└─ STAge NUMber ─ stage-no ─┘
►─ REPlace ─ ¤ ┬─────────────────────────────────────────────────────────┬ ¤ ─►
├─ GENerate CCID ─┬────────────────┬─ WITh 'to-value' ────┤
│ └─ 'from-value' ─┘ │
├─ LASt ACTion CCID ─┬────────────────┬─ WITh 'to-value' ─┤
│ └─ 'from-value' ─┘ │
├─ RETrieve CCID ─┬────────────────┬─ WITh 'to-value' ────┤
│ └─ 'from-value' ─┘ │
├─ DEScription ──┬────────────────┬─ WITh 'to-value' ─────┤
│ └─ 'from-value' ─┘ │
├─ PROcessor GROup ─┬──────────────┬─ WITh to-value ──────┤
│ └─ from-value ─┘ │
├─ SIGNOut USERId ─┬────────────────┬─ WITh 'to-value' ───┤
│ └─ 'from-value' ─┘ │
└────┤ USER DATA ├────────────────────────────────────────┘
►─┬──────────────────────────────────────────────────────────────────┬─ . ──►◄
└─ OPTion ─ ¤ ─┬─────────────────────────────────────────────┬─ ¤ ─┘
├─── CCId ─ ccid ─────────────────────────────┤
├─── COMment ─ comment ───────────────────────┤
├─── OVErride SIGNOut ──────────────────────┤
├─┬─ SEArch ───┬───────────────────┬─┬────────┤
│ │ └─┬─ ALL ───────────┤ │ │
│ │ └─ FIRst FOUnd ◄ ─┘ │ │
│ └─ NOSearch ───────────────────────┘ │
└─┬─ UPDate ELEment ─────┬────────────────────┘
└─ NOUpdate ELEment ◄ ─┘
Expansion of USER DATA:
├─ USEr DATA ┬────────────────────────────────┬──────────────────────────►
└─ (from-position,'from-value') ─┘
►─ WITh (to-position,length,pad,'to-value') ─────────────────────────────┤
Note: You can use name-masking to specify some variable values. A name-masked value is not explicit, because it includes a full (*) or partial (for example, ENV*) wildcard, multiple placeholders (%), or both. For more information about name-masking, see Name-Masking.
Name-masking is allowed on all values except on the to-value, which is the new value that replaces the current value (the from-value) in the specified element record field. Therefore name-masking enables the same Alter statement to make the following changes:
You can change multiple metadata fields and multiple element instances in the same Alter statement as follows:
Value specifications are case-sensitive, except for the Processor Group field, which is always in upper case.
The Alter action statement clauses are described next:
Changes the Master Control File metadata for the specified elements. You can name-mask the ELEMENT element-name. However, only the wildcard asterisk is supported on the THRU ELEMENT-NAME element-name. Long-named elements are supported.
Specifies the inventory location of the element that you want to alter. Specify an Environment, System, Subsystem, Type, and Stage or Stage Number. Name-masking is valid on all the variable values. The Search option searches for the element beginning with the specified Environment Stage and continues along the map. The Nosearch option limits the search to the specified Environment Stage. The Alter action alters the element metadata at the location where the matching elements are found and never fetches the element back to the specified From location.
Replaces the Master Control File metadata with the specified value. One or more options can be specified on the same Replace clause; they are not mutually exclusive. You can specify multiple Replace clauses on the same Alter statement. However, you cannot specify the same option more than once per Alter statement. All Replace from- and to-values are case-sensitive except for Processor Group. All Replace from- and to-values can contain embedded spaces if enclosed in quotes or double quotes, except for the Processor Group.
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 from-value variable specifies the current value in the Master Control File and can be name-masked or omitted.
The to-value is required and specifies the new value. You can use name-mask characters (% and *), but they are treated as text values.
Specify one or more of the following options:
Specifies the current value and the replacement value for the 1- to 12-character CCID field, for the last Generate action in the Master Control File. The from-value supports name-masking, but the to-value treats name-mask characters as text characters. If the from-value is omitted or fully wildcarded, then the replacement will occur regardless of what is currently in the Master Control File field that is being interrogated. If the to-value string contains embedded spaces or you want to include leading spaces in the to-value string, it must be enclosed in quotes. This value is case-sensitive, regardless of the MIXEDFMT parameter setting in the C1DEFLTS table. You cannot alter the Generate CCID if the element was never Generated. Attempting to do so will cause the action to fail and none of the other replacements will be performed.
Specifies the current value and the replacement value for the 1- to 12-character CCID value, for the last action in the Master Control File. The from-value supports name-masking, but the to-value treats name-mask characters as text characters. If the from-value is omitted or fully wildcarded, then the replacement will occur regardless of what is currently in the Master Control File field that is being interrogated. If the to-value string contains embedded spaces or you want to include leading spaces in the to-value string, it must be enclosed in quotes. This value is case-sensitive, regardless of the MIXEDFMT parameter setting in the C1DEFLTS table.
Specifies the current value and the replacement value for the1- to 12-character CCID value, for the last Retrieve action in the Master Control File. The from-value supports name-masking, but the to-value treats name-mask characters as text characters. If the from-value is omitted or fully wildcarded, then the replacement will occur regardless of what is currently in the Master Control File field that is being interrogated. If the to-value string contains embedded spaces or you want to include leading spaces in the to-value string, it must be enclosed in quotes. This value is case-sensitive, regardless of the MIXEDFMT parameter setting in the C1DEFLTS table. You cannot alter the Retrieve CCID if the element was never Retrieved. Attempting to do so will cause the action to fail and none of the other replacements will be performed.
Specifies the element description to be replaced and the replacement value. Valid values can be 1 through 40 characters in length and are case-sensitive. The from-value supports name-masking, but the to-value treats name-mask characters as text characters. If the from-value is omitted or fully wildcarded, then the replacement will occur regardless of what is currently in the Master Control File field that is being interrogated. If the from-value or to-value string contains embedded spaces or you want to include leading spaces in the to-value string, it must be enclosed in quotes. To clear the field, enter a blank character in quotes. This value is case-sensitive, regardless of the MIXEDFMT parameter setting in the C1DEFLTS table.
Note: The description in the Master Control File was originally set by the comment field value coded when the element was first added. This value was also placed into the level 0 delta comment field. The to-value you code updates the Master Control File description field. The level 0 delta comment field is not modified.
Specifies the name of the Processor Group to be replaced and the replacement value. Valid values can be one to eight national characters in length. The from-value supports name-masking, but name-mask characters are not valid on the to-value. If the from-value is omitted or fully wildcarded, then the replacement will occur regardless of what is currently in the Master Control File field that is being interrogated. The processor group specified on the to-value must exist, or the action will fail and none of the other replacements will be performed.
If *NOPROC* is coded on the from-value or to-value, the asterisk (*) characters are treated as ordinary characters in the text string instead of name-mask characters.
Note: When the Alter action changes a Processor Group, the action does not execute the Delete Processor on the old Processor Group or the Generate Processor on the new Processor Group. Performing a Generate action, at any time after the Alter was performed with a processor group change, will not necessarily remove any orphaned components or output libraries.
Specifies the Signout UserID to be replaced and the replacement value. Valid values can be one to eight national characters in length and are case-sensitive. Name-masking is supported on the from-value. If the from-value is omitted or fully wildcarded, then the replacement will occur regardless of what is currently in the Master Control File field that is being interrogated. No edits are performed on the Signout UserID field. It is up to the operating system to enforce naming standards.
Specifies what part of the current User Data field will be matched and where a new text string will replace all or part of the current User Data field. The new value overwrites all or part of the current value. Valid values can be 1 through 80 characters in length and are case-sensitive. Name-masking is supported on the from-value.
Note: User Data can also be changed through an exit 2 (before action) program on Add, Update, and Generate actions. When processing the Alter action, the exit 2 field that sets the user data (assembler field REQUSR or COBOL field REQ-USER-DATA) is ignored. Any Add, Update, or Generate actions that call an exit 2 program to set the user data field can overwrite a user data value previously set by the Alter action.
Specifies the value to be matched and where the search for that value begins.
from-position— Specifies the position within the User Data field to match against the from-value.
from-value— Specifies the value to be matched. If the string contains embedded spaces, it must be enclosed in quotes. Name-masking is supported.
Specifies the value to be added and where to add it. The length and pad values are optional, but either both must be used or both omitted. If the length and pad values are not used, the commas are still required, for example: WITH (to-position, , , 'to value’)
Examples of valid Replace clauses for User Data follow:
Replaces the text in columns 1 through 5 with TASKA.
Replaces the text found in positions 25 through 29 with the value of UserA when the from-value found in position 1 is ZZZ.
Replaces the text beginning in column 1 with USERA.
Specifies processing options.
Specifies a 1- to 12-character CCID to be added to the SMF record for the target element. For the Alter action, this option does not update the Master Control File. This value may be case-sensitive depending on the MIXEDFMT parameter setting in the C1DEFLTS table.
Specifies a 1- to 40-character comment to be added to the SMF record for the target element. For the Alter action, this option does not update the Master Control File. This value may be case-sensitive depending on the MIXEDFMT parameter setting in the C1DEFLTS table.
Specifies that you want to update the element, even if the element is signed out to someone else. If the element is signed out to someone else, you must code this option to perform the Alter action. However, 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.
Specifies a logical or physical search of the software inventory that is based on the C1DEFLTS table Environment definitions. After an Environment Stage is matched, the Stage Master Control File is searched based on other criteria: the Alter action element name specification and the Replace and Options clauses.
Specifies a logical search of the software inventory that is based on the mapping of Environment Stages as defined in the C1DEFLTS table. The search begins with the Environment Stage that is specified on the element action From clause and continues along the map. On the From clause, the Environment name must be explicit. Name-masking is supported on the Stage ID. If the Stage ID is name-masked, the starting location is Stage 1, regardless of whether that Stage is in the logical map or is the entry Stage for the Environment. The Alter action changes the Master Control File for each matching element at the location where the element is found.
The ALL and First Found options are ignored by all actions, except the Alter action.
ALL— Identifies all elements that are found in the logical search. If the Alter action is run in Update mode, then all the elements that are found in the search get updated.
FIRST FOUND— Identifies the first element that is found in the logical search. If the Alter action is run in Update mode, then only the first element that is found in the search gets updated. The default.
Specifies a physical search of the software inventory that is based on an exact match to the C1DEFLTS table Environment definitions, regardless of mapping. The search is limited to the Environment Stage that is specified on the element action From clause. Name-masking is supported on the Environment name (for the ALTER action only) and on the Stage ID.
If the Environment or Stage is name-masked, more than one Environment Stage can meet the selection criteria. For example, If you specified an environment-name of D* and the C1DEFLTS table includes the unmapped environments DEV, QA, PRD, and DEMO, then both the DEV and DEMO Environments would match.
Specifies the action mode. Specify one of the following modes:
UPDATE ELEMENT— Updates the Master Control File.
NOUPDATE ELEMENT— Identifies the elements that meet the Alter selection criteria, but does not update the Master Control File. The default.
Note: The UPDATE | NOUPDATE ELEMENT option cannot be coded in the SET statement.
Example— Alter Action Replacement of User Data
The following examples show User Data replacement:
ALTER ELEMENT TESTELM1 OPTION UPDATE ELEMENT REPLACE
USER DATA (1,'ENV1') WITH (1,80,' ','ENV1234 SYSTEM01')
If the original user data field contained this:
----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8 ENV1 SYSTEM99SUBSYS99TYPE0099 TESTUPDATEACT
It would contain this after the replacement:
----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8 ENV1234 SYSTEM01
ALTER ELEMENT TESTELM1 OPTION UPDATE ELEMENT REPLACE
USER DATA (1,'ENV1') WITH (1,80,'@','ENV1 SYSTEM01')
If the original user data field contained this:
----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8 ENV1 SYSTEM99SUBSYS99TYPE0099 TESTUPDATEACT
It would contain this after the replacement:
----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8 ENV1 SYSTEM01@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
ALTER ELEMENT TESTELM1 OPTION UPDATE ELEMENT REPLACE USER DATA (1,'ENV1') WITH (15,25,'@','88SYSSUB') If the original user data field contained this: ----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8 ENV1 SYSTEM99SUBSYS99TYPE0099 TESTUPDATEACT It would contain this after the replacement: ----+----1----+----2----+----3----+----4----+----5----+----6----+----7----+----8 ENV1 SYSTEM88SYSSUB@@@@@@@@@@@@@@@@@ TESTUPDATEACT
|
Copyright © 2014 CA Technologies.
All rights reserved.
|
|