Search and Replace Element Text Strings and Component List Output Data Set Names

Using the Search and Replace utility on text strings in elements, and on output data set names in component lists
ce18-18-0-08
The Search and Replace utility lets you search for and optionally replace text strings in elements, and output data set names in component lists.
2
Search and Replace Utility
You can run the utility in validate mode to check that the SCL statements generated for your search request are valid. Whether the utility is run in replace or validate mode, you can generate a report of the search targets found. Additionally, other options can be specified.
Searching and Replacing Text Strings
The option to update text within elements enables you to search for a character string in elements that are under
CA Endevor
control. You have the option to replace the character string with a different character string. If you specify a replacement string, the element is updated and added back into the entry stage at the environment specified on the request.
The Search and Replace utility is controlled by the SEARCH ELEMENT request (available in batch only). You specify the inventory location to be searched as well as any additional selection criteria, such as CCID or processor group. You also provide the character string for which you are looking and, optionally, a character string with which you want to replace the original string.
If you include a replacement string in your request, the utility replaces the original character string with the second string. The utility then adds the element back into the entry stage at the environment specified on the request. If you do not specify a replacement string, the element is not updated.
The premise of the Search and Replace Utility is that one or more text strings can be found and, optionally, replaced by one or more different text strings. Information is compared on a line-by-line basis, within specific columns. Information is replaced within specific columns of specific lines.
The following concepts are also important to your understanding of the search and replace process.
  • IN-COLUMNS and BOUNDS ARE parameters are used in conjunction with each other to set the limits for the search and replace operations.
    For a discussion of compare column ranges, IN COLUMNS rules, and BOUNDS ARE rules, see Text Replacement.
  • Data is manipulated only within the modifiable range. Data in columns outside this range is neither modified nor affected by data shifting.
    For a discussion and examples regarding replacement string length, see Shorter Replacement String.
  • You can override the type compare columns by assigning IN-COLUMNS and BOUNDS ARE values in the SEARCH ELEMENT statement. You cannot assign a value that exceeds the type definition compare column value. For example, you are using element type COBOL, whose compare columns are 7-72. If you assign a right boundary of 80, you will receive an error message. The right boundary can be any value up to and including 72. Similarly, assigning a left boundary of 6 results in an error. The left boundary value cannot be less than 7.
    For a discussion of the SEARCH ELEMENT SCL, see Search Element SCL. For a discussion about IN COLUMNS and BOUNDS ARE rules, see Text Replacement.
How the Search and Replace Utility Begins the Search
The Search and Replace utility begins its search at the inventory location indicated in the SEARCH ELEMENT request. If the element is not found at that location and if you requested that all environments in the map be searched, the utility checks subsequent environments for the element. Once found, the utility processes only the first occurrence of the element. Remaining stages are neither searched nor processed.
The search is always done against the current level of the element, and always begins at the entry stage of the indicated environment. You cannot specify a beginning stage location in your SEARCH ELEMENT request.
The Search String
The search string can be from 1-72 characters in length. You cannot use a string that contains both single quotation marks and double quotation marks.
By default, the Search and Replace utility looks for the character string in the column range associated with the element type entered in the request. You can override the type values by coding an explicit search column range.
Search and Replace Utility Processing Modes
The Search and Replace utility executes in one of three modes:
  • Validate
    Executed when you code VALIDATE in the PARM= field in the execution JCL. The utility parses and verifies the SCL statements in the SEARCH ELEMENT request.
    For more information about validate mode, see Validate Mode.
  • Search-Only
    Executed by default, the utility searches for the search string specified and produces a report indicating the element in which the string is found. Optionally (depending on what is coded in the execution JCL), the utility generates SCL for each element that contains the search string.
    For more information about search-only mode, see Search-Only Mode.
  • Replacement
    Executed when a replacement text string is included in the request and the OPTIONS UPDATE ELEMENT clause is coded. Both conditions must exist in order for the utility to replace one string with another. The utility replaces the original string with the replacement string, and adds the element back into the entry stage of the environment specified on the SEARCH ELEMENT request.
    For more information about replacement mode, see Replacement Mode.
Search and Replace Column Definitions
There are several terms used to describe the search columns and replace columns. It is important that you understand each term as you work with the Search and Replace Utility. These terms are described as follows:
  • Compare columns (or type compare columns)
    The compare columns associated with the element type definition. Each type (for example, COBOL, Assembler, or JCL) has specific columns within which
    CA Endevor
    looks to identify changes. For example, the compare column range for COBOL is 7-72.
  • BOUNDS ARE parameters (or bounds or boundaries)
    The columns within which
    CA Endevor
    can place the new text string. BOUNDS ARE parameters begin with
    left-column
    and end with
    right-column
    . If omitted, the type definition compare columns are used.
    The BOUNDS ARE parameters usually define the modifiable range.
  • IN COLUMNS parameters (or search columns)
    The columns within which
    CA Endevor
    searches for a particular text string. IN COLUMNS parameters begin with
    from-column
    and end with
    to-column
    . If omitted, the BOUNDS ARE values are used.
  • Modifiable range
    The union of the BOUNDS ARE parameters and IN COLUMNS parameters.
    • The left or first position of the modifiable range is the IN COLUMNS from-column.
    • The right or end position of the modifiable range is BOUNDS ARE right-column, with one exception:
      If the IN COLUMNS to-column is greater than the BOUNDS ARE right-column, the IN COLUMNS to-column value is used as the end of the modifiable range.
    The default modifiable range is the compare column range of the element type.
Search and Replace Utility Operating Considerations
This section details operating considerations that pertain to the Search and Replace utility.
Miscellaneous Operating Considerations
Miscellaneous operating considerations include the following:
  • All updates to elements are performed at the entry stage in the environment specified in the SEARCH ELEMENT request.
  • Variable length records are never shortened. A record's length may increase, but it will not decrease.
  • In replacement mode, the Search and Replace utility does not search elements that are signed out to users other than the current user, unless the OVERRIDE SIGNOUT option is specified in the SEARCH ELEMENT request. Nor does the utility search elements in an in-between stage (that is, a stage not on the map but between two stages that are on the map).
The Search and Replace utility uses the
CA Endevor
security system 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 searching 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. (Applies to replacement mode only.)
  • Does the user have ADD or UPDATE authority for the element at the entry stage of the specified environment?
    This check occurs when the updated element is added back into
    CA Endevor
    . If the element exists at the entry stage, the user must have UPDATE authority for the element at that stage. If the element does not exist at the entry stage, the user must have ADD authority for the element at that stage.
Serializing the Element
The Search and Replace utility puts a “lock” on an element when it is being processed. The lock is placed at the environment indicated in the SEARCH ELEMENT request and at the source environment, if the element was found up the map. Therefore, other
CA Endevor
actions against the element, such as SIGNOUT or RETRIEVE, may be prohibited while you are processing the element.
Serializing the element applies to replacement mode only.
Exits Invoked by the Search and Replace Utility
The Search and Replace utility invokes three
CA Endevor
exits:
  • Exit 1--Security
  • Exit 2--Before Action
  • Exit 3--After Action
Exits are handled as follows:
  • Exit 1
    Invoked for the following actions:
    • Retrieve
    • Add, Update
    When invoked:
    • Before any element processing begins.
    • Before ADD or UPDATE processing, only if it has been determined that the element will need to be added back into
      CA Endevor
      .
  • Exit 2
    Invoked for the following actions: Add or Update
    When invoked: Before action processing begins.
  • Exit 3
    Invoked for the following actions: Add or Update, based on exit 2
    When invoked: After a corresponding (and successful) invocation of exit 2.
    • If exit 2 is invoked and allows an action, exit 3 is invoked after the action has been performed.
    • If exit 2 is invoked but does not allow an action, exit 3 is not invoked.
    • If exit 2 is not invoked for an action or element, exit 3 is not invoked for that action or element.
Validate Mode
The Search and Replace utility operates in validate mode when you code VALIDATE as part of the PARM= parameter in the execution JCL. In this mode, the utility parses and verifies the generated SCL statements for proper syntax. If no errors are found, the SCL statements are formatted.
Processing stops after validation. The actions implied by the SCL statements are not performed. Errors other than syntax errors are not noted at this time.
To invoke validate mode, you need to code the following in the execution JCL:
PARM='ENBS1000VALIDATE'
You can abbreviate the word validate, using any of the following entries:
V, VA, VAL, VALI, VALID, VALIDA, or VALIDAT
Search-Only Mode
The Search and Replace utility executes in search-only mode by default. In this mode, the utility searches for a particular search string in the elements specified in your SEARCH ELEMENT request. At a minimum, the utility generates a list of the elements that contain the search string. Depending on what you code in the request or in the execution JCL, the utility performs the following actions:
  • OPTIONS LIST DETAILS in the request
    Displays the line of the element that contains the search strings.
  • A replacement string and OPTIONS LIST DETAILS in the request
    Displays the line of the element that contains the search string followed by the same line containing the replacement string.
  • A replacement string in the request and allocate the ENSSCLOT file in the JCL
    Generates SCL for all the elements that would be affected by replacement of the search string. SCL statements are generated only when a replacement string is specified in the original search request.
Note that in search-only mode, the OPTIONS UPDATE clause is not specified.
Search-only Mode Processing
The Search and Replace utility determines the elements to be searched based on inventory location and additional selection criteria provided in the SEARCH ELEMENT request. For each element identified, the utility reads--on a record-by-record basis--the current level of the element, and searches for the search string. The utility produces a series of reports listing each element that was searched and the result of the search (for example, number of search string matches found in the element).
The Search and Replace utility verifies RETRIEVE authority before processing the element.
The Search and Replace utility does not do the following when in search-only mode:
  • The utility does not update the element.
  • The utility does not perform signout processing.
  • The utility does not check whether an element is at an in-between stage (a stage not on the map, but between two stages that are on the map).
The search string is case-sensitive. If the search string contains only uppercase characters, the utility looks only for text in uppercase characters. If a line in an element matches the text of the search string but is in lowercase or a combination of lowercase and uppercase characters, the utility does not record a match.
Generating Search Elements SCL
The Search and Replace utility provides the option of generating SCL statements for each element that contains the search string. These SCL statements can then be executed to perform actual replacement of the search strings.
This capability is useful when a large number of elements are searched before search strings are replaced. You can review the output to see how elements will be affected by the text replacement. If the output is acceptable, execute the Search and Replace utility again, using the generated SCL as the input file. Because the SCL statements have been created, the utility only needs to execute them; a second search of the entire inventory is not necessary. Using this option not only allows you to review the results of replacing text before you actually do so--it also saves you time.
The Search and Replace utility generates SCL statements if you enter a replacement string in the SEARCH ELEMENT request and you allocate the ENSSCLOT DD statement in the execution JCL. The SCL statements written to the ENSSCLOT file contain all the information entered in the original SEARCH ELEMENT request as well as an OPTIONS UPDATE ELEMENT clause. When you invoke the utility a second time, using the generated SCL as the input file, only the specified elements are searched and updated.
If the source SCL contains multiple SEARCH ELEMENT requests, the output data set may contain multiple SCL statements for the same element.
Each FROM statement in the generated SCL will contain explicit system, subsystem, and type values, even if you used a wildcard for that value in the original SEARCH ELEMENT request. These values represent the location where the updates will be applied.
ENSSCLOT File
The ENSSCLOT DD statement should refer to a sequential data set or a partitioned data set with an explicit member. Allocate the data set with the following attributes:
  • DSORG=PS (or PO if a member name is specified)
  • RECFM=F or FB
  • LRECL=80
Replacement Mode
The Search and Replace utility operates in replacement mode when you include both the REPLACE WITH clause and the OPTIONS UPDATE ELEMENT clause in your SEARCH ELEMENT request. In this mode, the utility searches the element for the search string, replaces each occurrence of the string with the replacement string, and adds the element back into
CA Endevor
at the entry stage of the specified environment.
Replacement Mode Processing
The Search and Replace utility determines the elements to be searched based on inventory location and additional selection criteria provided in the SEARCH ELEMENT request. For each element identified, the utility reads--on a record-by-record basis--the current level of the element, and searches for the search string. If the search string is found, the utility replaces that string with the replacement string specified in the SEARCH ELEMENT request. When the entire element has been searched and all relevant search strings replaced, the utility adds or updates the element to the entry stage of the environment indicated in your request.
In this mode, the utility verifies RETRIEVE, SIGNOUT, and ADD/UPDATE authorization. In addition, the utility checks whether any of the elements specified exist at an in-between stage (stage not on the map but between two stages that are on the map).
For more information about these authorizations and conditions, see Processing Checkpoints.
Be aware of the following:
  • SIGNOUT authorization and in-between stage checking are not performed in search-only mode. Consequently, elements that are signed out to another user or exist at an in-between stage may be searched, and may have SCL statements written to the ENSSCLOT file. Because the utility does perform these two checks in replacement mode, some of the SCL statements may terminate with an error if you use this ENSSCLOT file as input to a subsequent Search and Replace job.
  • The search string and the replacement string are case-sensitive. If the search string contains only uppercase characters, the utility looks only for text in uppercase characters. If a line in an element matches the text of the search string but is in lowercase or a combination of lowercase and uppercase characters, the utility does not record a match.
    Similarly, the utility places the replacement string in the element exactly as it has been coded in the SEARCH ELEMENT request. The utility does not convert lowercase characters to uppercase characters (or vice versa).
  • When fetch processing occurs, if the value of Signout Fetch (SOFETCH), a
    CA Endevor
    Defaults Table parameter, is Y, the element that is fetched will be signed out to you at the location from which it was fetched, unless it is already signed out to someone else. If the value of SOFETCH is N, the element that is fetched will not be signed out.
    The element that is put in the entry stage will be signed out to you.
Processing Checkpoints
Before and during processing, the utility checks for the following authorizations and conditions:
  • RETRIEVE authority
    Before processing an element, if the user does not have RETRIEVE authority, then processing stops for that element and begins for the next element.
  • RETRIEVE authority
    Before processing an element, if the user has RETRIEVE authority, then processing for the element continues.
  • SIGNOUT authority
    After RETRIEVE authority is determined but before processing for the element, if the user does not have SIGNOUT authority, then processing stops for that element and begins for the next element.
  • SIGNOUT authority
    After RETRIEVE authority is determined but before processing for the element, if the user does have SIGNOUT authority, then processing for the element continues.
  • Whether the element exists at an in-between stage
    After RETRIEVE and SIGNOUT authority are determined but before the element is searched, if the element exists at an in-between stage, then processing stops for that element and begins for the next element.
  • Whether the element exists at an in-between stage
    After RETRIEVE and SIGNOUT authority are determined but before the element is searched, if the element does not exist at an in-between stage, then processing for the element continues.
  • ADD/UPDATE authority
    After the element is searched and the search string is replaced, but before the element is added or updated into
    CA Endevor
    , if the user does not have ADD/UPDATE authority, then processing stops for that element and begins for the next element.
  • ADD/UPDATE authority
    After the element is searched and the search string is replaced, but before the element is added or updated into
    CA Endevor
    , if the user does have ADD/UPDATE authority, then the utility performs the appropriate action at the entry stage of the specified environment:
    • UPDATE if the element exists at the entry stage
    • ADD if the element does not exist the entry stage
Search and Replace Execution JCL
The Search and Replace control statements (SCL) are coded in the execution JCL used to activate the utility. The JCL which executes this utility can be found in member ENBSRPL1, in the JCL library iprfx.iqual.CSIQJCL.
ENSSCLIN DD Statement
The user control statements specified in the ENSSCLIN DD statement are SEARCH ELEMENT requests, which specify element search criteria, the search string, and, optionally, a replacement text string. You can code as many SEARCH ELEMENT requests as you need; there is no defined limit on the number of statements allowed.
For more information about the SEARCH ELEMENT SCL, see Search Elements SCL.
PARM= Statement
You must specify the ENBS1000 parameter to invoke the Search and Replace utility. You can optionally code the VALIDATE parameter (immediately after ENBS1000) to request validate mode processing.
The utility performs the following actions depending on the value that you specify in the PARM= statement:
  • PARM=ENBS1000
    Parses and validates all the requests before processing them.
    If the parser or validation routine detects an error, the utility will not execute any of the statements. The parsing routine attempts to parse all of the control statements before terminating.
  • PARM=ENBS1000VALIDATE
    Parses and validates all the requests, but does not execute the requests even if no syntax or validation errors are found.This parameter must follow the ENBS1000 parameter, as shown here:
    PARM=ENBS1000VALIDATE
Search Elements SCL
You can enter as many SEARCH ELEMENT requests as necessary in the control statement data set. There is no defined limit to the number of actions allowed in a single execution of the program.
The utility parses and validates all requests before it begins executing them. If there is a syntax error in any request or an error is found validating a request, none of the statements are executed. The utility tries to parse all statements before terminating.
When the requests have been successfully parsed, the utility executes them. Requests are executed as long as the highest return code is less than or equal to 12.
If you code PARM=VALIDATE, the utility will not execute the requests when parsing is complete.
The SEARCH ELEMENT syntax is shown in the next section, followed by a description of each clause in the syntax.
Search Elements Syntax
The following is the SEARCH ELEMENT syntax:
├── SEArch ELEment ─ element-name ─┬──────────────────────────────┬───────────► └─┬─ THRough ─┬─ element-name ─┘ └─ THRu ────┘ ►─ FROm ─ ENVironment ─ env-name ─ SYStem ─ sys-name ────────────────────────► ►─ SUBsystem ─ subsys-name ─ TYPe ─ type-name ───────────────────────────────► ┌───────────────────────────────────┐ ►── ▼ ─ FOR ─┬────────┬─ search-string ─┴────────────────────────────────────► └─ TEXt ─┘ ►─ ¤ ┬──────────────────────────────────────────────────────────────────┬─ ¤ ─► ├─┬──────┬ ─ COLumns ─┬─ from-column ─┬─┬─────────────────────────┬┤ │ └─ IN ─┘ └─ FIRst ───────┘ └─ TO ─┬─ to-column ─┬────┘│ │ └─ LASt ──────┘ │ ├─ REPlace WITh ─┬────────┬─ repl-string ──────────────────────────┤ │ └─ TEXt ─┘ │ └─ BOUnds ┬───────┬─┬──────────┬─┬─ left-col ┬─┬──────────────────┬┘ └─ ARE ─┘ └─ COLumn ─┘ └─ FIRst ◄ ─┘ └─ TO ┬─ right-col┬┘ └─ LASt ◄ ──┘ ►─┬──────────────────────────────┬──────────────────────────────────────────────► └─ WHEre ─ ¤ ─┬──────────┬─ ¤ ─┘ ├─┤ CCID ├─┤ └─┤ PRO ├──┘ ►─┬───────────────────────────────────────────────────────────────────────────┬─► └─ OPTion ─ ¤ ─┬──────────────────────────────────────────────────────┬─ ¤ ─┘ ├─ CCId ─┬──────┬─ ccid ───────────────────────────────┤ │ ├─ EQ ─┤ │ │ └─ = ──┘ │ ├─ COMment ─┬──────┬─ comment ─────────────────────────┤ │ ├─ EQ ─┤ │ │ └─ = ──┘ │ ├─ BYPass GENerate PROCessor ──────────────────────────┤ ├─ PROCessor GROup ─┬─ EQ ─┬─ group-name ──────────────┤ │ └─ = ──┘ │ ├─ OVErride SIGNOut ───────────────────────────────────┤ ├─ SEArch ENVironment ─┬─ MAP ──┬──────────────────────┤ │ └─ ONLy ─┘ │ ├─┬────────┬ ─ TRUncation ─┬──────┬─┬─ PROHibited ◄ ─┬─┤ │ └─ DATa ─┘ └─ IS ─┘ └─ PERmitted ────┘ │ ├─ LISt DETails ───────────────────────────────────────┤ └─ UPDate ─┬───────────┬───────────────────────────────┘ └─ ELEment ─┘
Search Element Clause
The SEARCH ELEMENT clause allows you to specify one or more elements to be searched. You can specify that a range of elements be searched by coding the THROUGH clause also. This clause is described next:
  • SEARCH ELEMENT
    element-name
    (Required) The name of the action followed by the name(s) of the element(s) you want to search.
    The element name can be explicit, partially wildcarded, or fully wildcarded. If you enter a partially wildcarded element name, only those elements matching the criteria are searched.
    If you use the THROUGH clause, the element indicated here is the first element in the range to be searched.
  • THROUGH (THRU)
    element-name
    (Optional) Indicates that a range of elements are to be searched, up to and including the element named in this clause. You can use a wildcard with the element name.
From Clause
The FROM clause identifies the
CA Endevor
inventory location at which the element search begins. You must enter all FROM information. You need to code the word FROM only once. The FROM clause is described next:
  • FROM ENVIRONMENT
    env-name
    Name of the environment. You must fully specify the environment name; you cannot use a wildcard.
  • FROM SYSTEM
    sys-name
    Name of the system. You can enter a fully specified system name or use a wildcard.
  • FROM SUBSYSTEM
    subsys-name
    Name of the subsystem. You can enter a fully specified subsystem name or use a wildcard.
  • FROM TYPE
    type-name
    Type associated with the element. You can enter a fully specified type or use a wildcard.
Note that you cannot indicate a stage. The search always begins at the entry stage of the environment you specify.
If you specify OPTIONS SEARCH ENVIRONMENT MAP, the utility searches this inventory location first, and then continues the search for the element up the map. If you specify OPTIONS SEARCH ENVIRONMENT ONLY, the utility searches only the environment defined in this clause.
If an element changes as a result of the search, the utility either adds it or updates it at the entry stage of the environment specified in this FROM clause. The element is always added (or updated) at the entry stage of this environment, no matter where the element was retrieved.
For Clause
The FOR [TEXT] clause identifies the text strings the utility searches for and, optionally, provide the compare ranges to be searched and replacement text for the search strings. If you do not enter column compare range values, the utility uses the COMPARE FROM and COMPARE TO columns associated with the element type.
The IN COLUMNS, BOUNDS ARE, and REPLACE WITH clauses can be entered in any order, as long as they all follow the FOR [TEXT]. These clauses are described in the following: search-string clause.
  • FOR [TEXT]
    search-string
    Identifies the character string for which the utility will search. This clause is required.
    The attributes of the search string are listed as follows:
    The minimum length of the search string is 1 character. Null (empty) search strings are prohibited.
    • The maximum length of the string is 72 characters. The length of the string must be less than or equal to the number of columns searched (see the description of IN COLUMNS that follows).
    • You can specify multiple search strings by repeating the FOR TEXT
      search-string
      clause. For example:
      FOR TEXT ABCDE FOR TEXT BCXYZ
    • If the string contains imbedded spaces or any other parser delimiter, it must be enclosed by either apostrophes or quotation marks.
      • If the string contains apostrophes, enclose it in quotation marks.
      • If the string contains quotation marks, enclose it in apostrophes.
    • The string itself cannot contain both apostrophes and quotation marks.
    • Trailing blanks are significant during the search operation if the search-string is quoted.
    • The comparison of text strings is case-sensitive; that is, lowercase characters remain lowercase.
  • [IN] COLUMNS . . .[TO] . . .
    Identifies the columns in which the utility looks for the search string (the compare range). This clause is optional.
    The values entered here override the compare column values implied by the element type (defined in the FROM clause). The from-column and to-column values must fall within the compare range values (inclusive), however. Otherwise, you receive an error message.
    If you do not use this clause, the utility uses the values provided in the BOUNDS ARE clause.
    You can enter the following in this clause:
    • from-column
      or FIRST, to indicate the first column (inclusive) of the compare range. You can enter any value as the
      from-column
      value as long as that value is less than or equal to the
      to-column
      value (see next). If you do not enter a
      from-column
      but you do enter a to-column, the utility uses the left-column value of the BOUNDS clause as the first column. FIRST reflects the COMPARE FROM value of the type associated with the element.
    • to-column
      or LAST, to indicate the ending column (inclusive) of the compare range. The to-column value must be greater than the from-column value, and cannot exceed 32,000. LAST reflects the COMPARE TO value of the type associated with the element.
  • REPLACE WITH [TEXT]
    repl-string
    Identifies the string that will replace the search string in the element. The replacement string has the same attributes as the search string (see the first entry in the FOR clauses table) with the following exception: null (empty) replacement strings are allowed.
    This clause is optional. If you use this clause, you need to code the OPTIONS UPDATE ELEMENTS clause in order to have the search string replaced and the element(s) updated. Otherwise, the utility runs in search-only mode (and may, depending on what is coded in the execution JCL, generate SCL statements).
    If the replacement string is identical to the search string, no elements are searched and an error message is issued.
  • BOUNDS [ARE] [COLUMNS] . . . [TO] . . .
    Identifies--in conjunction with the IN COLUMNS values, if coded--the columns in which the utility looks for the search string. This clause is optional.
    If you use this clause, the
    left-column
    and
    right-column
    values must be within the range of the element type COMPARE FROM and COMPARE TO columns (inclusive). Otherwise, you receive an error message.
    If you do not enter column values, the utility defaults to FIRST and LAST, which reflect the COMPARE FROM and COMPARE TO values of the type associated with the element.
    You can enter the following in this clause:
    • left-column
      or FIRST, to indicate the first column (inclusive) of the compare range. The utility uses this value if you do not specify an explicit IN COLUMNS
      from-column
      value. If you do not enter a
      left-column
      value, the utility defaults to FIRST.
    • right-column
      or LAST, to indicate the last column that can be modified in the range. If you do not enter a
      right-column
      value, the utility defaults to LAST.
Where Clauses
WHERE clauses provide additional element selection criteria. The search is limited to only those elements whose CCID or processor group match the entry in the SEARCH ELEMENT request. WHERE clauses are optional and are described as follows:
  • WHERE CCID OF . . . EQ . . .
    Specifies the CCID that must be associated with the element in order for the utility to search the element. The CCID can be from 1-12 characters in length, and can be explicit, partially wildcarded, or fully wildcarded. Note that coding a fully wildcarded CCID produces the same result as not coding this clause or coding WHERE CCID OF ANY--all elements are selected no matter what the CCID is.
    You can provide a list of CCIDs; enclose the list in parentheses. The CCID associated with the element must match at least one CCID in the list to be selected for processing. The utility checks only the current MCF for the CCID.
    You can limit the search to only those elements whose base, generate, last action, or retrieve CCID match the CCID specified in the request. Again, the utility checks only the current MCF record.
    If you use WHERE CCID OF ANY, all of the above CCID fields in the current MCF record are examined.
  • WHERE PROCESSOR GROUP EQ . . .
    Specifies the processor group that must be associated with the element in order for the utility to search the element. The processor group name can be from 1-8 characters in length, and can be explicit, partially wildcarded, or fully wildcarded. Note that coding a fully wildcarded processor group name produces the same result as not coding this clause--all elements are selected no matter what the processor group is.
    You can provide a list of processor groups; enclose the list in parentheses. The processor group associated with the element must match at least one of the processor groups in the list to be selected for processing.
Option Clauses
OPTION clauses allow you to further qualify your request. You can specify none, one, or more than one option. You need to code the word OPTION only once. Option clauses are described next:
  • CCID [EQ]
    ccid
    Specifies the CCID to be associated with the element when the element is added (or updated) back into
    CA Endevor
    . This CCID is assigned to the last action CCID and the generate CCID.
    The CCID can be from 1-12 characters in length, and must be explicit.
    This clause is optional except under the following condition: the element's system record requires that a CCID be coded and you code the REPLACE WITH clause in the request.
  • COMMENT [EQ]
    comment
    Specifies the comment to be associated with the element when the element is added (or updated) back into
    CA Endevor
    .
    The comment can be from 1-40 characters in length. If the comment contains imbedded spaces or punctuation marks, the text must be enclosed by string delimiters.
    This clause is optional except under the following condition: the element's system record requires that a comment be coded and you code the REPLACE WITH clause in the request.
  • BYPASS GENERATE PROCESSOR
    Indicates that the generate processor is not to be executed when the element is added back into
    CA Endevor
    . By default, the generate processor is invoked whenever an element is added back into
    CA Endevor
    .
    This clause applies only if you code the REPLACE WITH clause.
  • PROCESSOR GROUP EQ
    group-name
    Assigns a processor group to the element when the element is added back into
    CA Endevor
    . The processor group named must exist at the entry stage of the environment.
    The processor group can be from 1-8 characters in length, and must be explicit. This clause applies only if you code the REPLACE WITH clause.
  • OVERRIDE SIGNOUT
    If the element is signed out to someone else, override signout must be used and the corresponding authority granted.
    You will not get the signout of the element that is fetched. However, the element that is put in the entry stage will be signed out to you.
    This clause applies only if you code the REPLACE WITH clause.
  • SEARCH ENVIRONMENT {MAP | ONLY}
    Specifies whether the utility will search beyond the entry stage of the designated environment:
    • SEARCH ENVIRONMENT MAP indicates that the utility is to search the environment map for the element if the element is not found at the entry stage of the specified environment.
    • SEARCH ENVIRONMENT ONLY indicates that the utility is to search only the environment specified in the SEARCH ELEMENT request. The utility can search both stages of the environment, but not the other environments in the map.
    If this clause is not coded, the utility searches only the entry stage of the specified environment. This is the default.
  • [DATA] TRUNCATION [IS] {PROHIBITED | PERMITTED}
    Indicates whether data truncation will take place during string substitution:
    • Code DATA TRUNCATION IS PROHIBITED to prevent data in an element record from being truncated. This is the default. An error message is returned if text replacement would have resulted in data truncation.
    • Code DATA TRUNCATION IS PERMITTED to allow data in an element record to be truncated. Caution messages are issued in this situation.
  • LIST DETAILS
    Indicates that you want to list, on the Search and Replace Utility Execution Report, each line (or a portion of the line, up to 90 bytes of data) of text containing the search string. The lines are printed as they are encountered during execution of the request. If the request contains a replacement string, the updated line is also printed.
    If this clause is not coded, the text of each line containing the text string is not printed in the execution report. Each element searched, along with the number of matches found in that element (0 to 99999), is printed to the execution and summary report, regardless of the LIST DETAILS option setting.
  • UPDATE [ELEMENTS]
    Indicates that the utility is operating in replacement mode. That is, as appropriate, the utility replaces the search string with the replacement string and updates the element.
    If this clause is coded, you need to code the REPLACE WITH clause if you want to replace the search string and update the element(s). Otherwise, the utility runs in search-only mode.
    If this clause is not coded, the utility operates in search-only mode.
Text Replacement
The replacement text string may be equal to, longer, or shorter than the search string. A longer or shorter search string causes data to be shifted to the right or left and blank spaces to be consumed or inserted. The size of the replacement string does not affect the record length, however, except under the following conditions:
  • The record has a variable length.
  • Extending the record length is required to insert the replacement string.
  • The extended length will not exceed the maximum length permitted for the element.
The data record is always padded to its original length.
The search string and the replacement string are case-sensitive.
Compare Column Ranges
By default, the Search and Replace utility searches for the search string in the compare column range associated with the element type definition. You can override the type definition values, however, by specifying values in the IN COLUMNS clause or the BOUNDS ARE clause (or in both) in the SEARCH ELEMENT request.
The BOUNDS ARE clause, used in conjunction with the IN COLUMNS clause, restricts the range of data that is searched and the range of data that may be affected by a change.
  • When both the IN COLUMNS and BOUNDS ARE clauses are specified, the utility uses the higher of the IN COLUMNS to-column and the BOUNDS ARE right-column to set the rightmost column that may be affected by data shifting.
  • When the IN COLUMNS clause is specified, the search for the search string is limited to the columns indicated.
  • When the IN COLUMNS clause is not specified, the utility uses the values specified or implied by the BOUNDS ARE values.
  • When the BOUNDS ARE right-column is greater than the IN COLUMNS to-column, data between the to-column and the right-column is usually not changed. The data may be shifted either left or right, depending upon the length of the replacement string. If shifted to the left, the data might be moved into the compare column range. The data then becomes subject to change, as all or part of it could be searched and, possibly, replaced.
    If the replacement string is larger than the search string and data truncation is allowed, some of the “in-between” data may be truncated.
IN COLUMNS Rules
If you use the IN COLUMNS clause, you must follow the rules listed as follows:
  • The IN COLUMNS values must be in the range 1 through 32,000, inclusive.
  • The IN COLUMNS from-column value must be less than or equal to the to-column value.
  • The IN COLUMNS to-column value must be less than or equal to the source element length associated with the element type record.
  • The IN COLUMNS from-column and to-column values must be included in the range of FIRST to LAST, respectively. That is, the values must be within the element type COMPARE FROM and COMPARE TO values, inclusively.
  • If only a single column number is specified, the utility assumes it represents the from-column value. The to-column is calculated as the from-column plus the size of the search string less 1.
  • If only the to-column is specified, the from-column value is assumed to be the left-column value specified or implied in the BOUNDS ARE clause.If both from-column and to-column are omitted, they adopt the values specified or implied by the BOUNDS ARE clause.
BOUNDS ARE Rules
The rules for IN COLUMNS also apply to the BOUNDS ARE clause, with the following exceptions:
  • If only a single column number is specified in the BOUNDS ARE clause, the utility assumes it represents the left-column of the range.
  • If the left-column value is omitted from the BOUNDS ARE clause, the utility defaults to FIRST. FIRST reflects the COMPARE FROM value of the element type.
  • If the right-column value is omitted from the BOUNDS ARE clause, the utility defaults to LAST. LAST reflects the COMPARE TO value of the element type.
  • If the BOUNDS ARE left-column does not fall within the IN COLUMNS from-column--to-column range, the IN COLUMNS from-column (or the first column of the element type's compare column range) is used as the beginning column for the search and replace operation.
Shorter Replacement String
When the replacement text string is smaller than the original search string, the original string is replaced and blanks are inserted into the record as follows:
  • If no blanks appear between the search string and the rightmost column of the modifiable range, data up to and including that rightmost column is shifted left. Blanks are inserted at the rightmost column of the modifiable range.
  • If at least one blank occurs between the text and the rightmost column of the modifiable range but there are no repeating blanks within this range of data, blanks are inserted at the last blank within the range. The data preceding that blank is shifted to the left.
  • If the data between the search string and the rightmost column of the modifiable range contains at least two consecutive blanks, additional blanks are inserted at the first occurrence of the repeating blank characters.
Shorter Replacement String Example
The following example illustrates replacement with a text string shorter than the original search string. The x represents a blank space.
BOUNDS ARE; 1 and 12 IN COLUMNS: 3 and 10 ????+----1----+----2 Original text: AABBBCCCCDDDDDEEExxx Search string: BBB Compare range: 3-10 Replacement string: EE Updated text: AAEECCCCDDDxDDEEExxx
The modifiable range in this example is 3 through 12. A blank is inserted at column 12 to accommodate for the shorter replacement string. The remaining portion of the original text is not modified at all, as it is outside the range defined.
Longer Replacement String
When the replacement text string is larger than the original string, the search string is replaced and blanks are consumed as follows:
  • Data from the original string to the rightmost column of the modifiable range is searched from left to right. All repeating blank characters are consumed as required to perform the substitution. When the appropriate number of blanks have been consumed, the data between the end of the text string and the rightmost column of the modifiable range is shifted to the right and the replacement string is inserted into the record.
  • If there are not enough extra blank characters and data truncation is permitted (specified in the request), the utility performs data truncation. The data at the rightmost column of the modifiable range is deleted, as necessary, to provide space for the replacement string. The utility issues a cautionary message and continues processing the element.
    If there are not enough blank spaces for the replacement string and data truncation is prohibited, the utility does the following:
    Generates an error message.
    • Displays the data for the element on the Search and Replace Utility Execution Report.
    • Continues to search the element for other search and replace operations.
    • Does not update the element.
Longer Replacement String Examples
The following examples illustrate text replacement with a string longer than the original search string. The x represents a blank space.
Example 1
BOUNDS ARE: 1 and 26 IN COLUMNS: 3 and 10 ????+----1----+----2... Original text: AABBBCCCCDDDDDxxx Search string: BBB Compare range: 3-10 Replacement string: EEEEEE Updated text: AAEEEEEECCCCDDDDD
The modifiable range in this example is 3 through 26. The replacement string fits within the compare columns and is only three characters longer than the search text. Consequently, the three blanks at the end of the original text are consumed by the replacement string as the data shifts to the right.
Example 2
BOUNDS ARE: 1 and 10 IN COLUMNS: 3 and 10 ????+----1----+----2... Original text: AABBBCCCCDDDDDxxx Search string: BBB Compare range: 3-10 Replacement string: EEEEEE Truncation permitted: AAEEEEEECDDDDDxxx Truncation prohibited: Error
The modifiable range in this example is 3 through 10. The replacement string is too long to replace only the search string within the modifiable range. If truncation is permitted, the utility replaces the search string, and the characters following the search string up through column 10, with the replacement string. The remainder of the original text, starting in column 11, is not modified.
If truncation is not permitted, you receive an error message and processing stops for this element.
Example 3
BOUNDS ARE: 1 and 23 IN COLUMNS: 3 and 10 ????+----1----+----2... Original text: AABBBxxCCxxDDDDxxxGGG Search string: BBB Compare range: 3-10 Replacement string: EEEEEEE Updated text: AAEEEEEEExCCxDDDDxGGG
The modifiable range in this example is 3 through 23. The replacement string can replace the search string and shift data to the right, within the modifiable range. Repeating blanks are consumed in such a way as to shift the remainder of the original string to the right--the replacement string is four characters longer than the search string so four blanks were consumed.
Multiple Occurrences of the Search String
The data record may contain multiple occurrences of the search string. The scan for subsequent appearances of the string begins immediately after the last character of the replacement string in the modified record. See the following example:
Original text: ABCBE Search string: B Replacement string: QQ Updated text: AQQCBE Final result: AQQCQQE
The first occurrence of B is replaced by QQ. The utility begins its search for the next appearance of B after the second Q in the text string.
The results of search and replace with multiple occurrences of the search string may not be what you expect, due to data being shifted into and out of the compare column range by replacement strings.
If you had a compare column range of 1-4 in the previous example, the utility would not replace the second occurrence of B, because the search string is now outside the specified column range. Similarly, if a replacement string is shorter than the search string, data may move into the compare column range that would not otherwise be included in the search.
Search and Replace Utility Reports
The Search and Replace utility generates three reports as part of its normal processing:
  • Control Statement Summary
    Shows the control statements that were provided in the ENSSCLIN DD statement and identifies any parser or statement validation errors.
  • Execution Report
    Contains information about the execution of each request.
  • Summary Report
    Summarizes each request processed. The summary indicates the element name, the return code, the number of matches found, the location where the match was found, and the location where the element was added (updated) back into
    CA Endevor
    .
These reports are written to the ENSMSGS1 DD statement.
Search and Replace Control Statement Summary Report
The Search and Replace Control Statement Summary Report shows the control statements coded in the ENSSCLIN DD statement, and whether there are any parser and validation errors.
Search and Replace Utility Execution Report
The column ruler is printed once for each element containing a search string. The ruler may be reprinted if a subsequent search string is found in the element but cannot be displayed using the column ruler shown; for example, the starting column number is not valid for the second search string. In this situation, a new ruler, with the appropriate starting column number, is printed for the element.
Search and Replace Utility Summary Report
The Search and Replace Utility Summary Report provides the following information for each request processed:
  • Statement Number
    The statement number associated with a SEARCH ELEMENT request.
    If the SEARCH ELEMENT request contains multiple FOR TEXT clauses and at least one search string was found in the element, multiple report lines are generated for the element. The first line provides the element information, and lists the
    total
    number of matches found. Each additional line for the element (numbered nn.1, nn.2...nn.x, for x number of FOR TEXT clauses) lists the number of matches found for a
    specific
    FOR TEXT clause.
  • Page Number
    The page number on the Search and Replace Utility Execution Report at which processing for the element began.
  • Element
    The name of the
    CA Endevor
    element that was processed.
  • Return Code
    The return code associated with the element's SEARCH ELEMENT request.
  • Lines Searched
    The number of times the FOR TEXT clauses are searched for the FOR TEXT string.
  • Matches Found
    The number of times the FOR TEXT strings were found. This value represents the actual number of occurrences, not the number of lines that contain the search string.
  • Location Where Found
    The inventory location from which the element was retrieved.
  • Location of Add/Update Operation
    The inventory location to which the element was added or updated. This field is blank if the element did not contain the search string or if the utility is running in search-only mode.
Text Search and Replace Usage Scenarios
This section contains usage scenarios to show you how the Search and Replace utility performs in various situations. Three scenarios are presented:
  • Scenario 1--A simple search without any options.
  • Scenario 2--A simple search with replacement text, in search-only mode.
  • Scenario 3--A search in replacement mode, using the SEARCH ENVIRONMENT MAP feature, multiple FOR TEXT clauses, and the BOUNDS ARE parameter.
Three elements constitute the sample elements for demonstrating the effects of the SEARCH ELEMENT SCL statement and its optional parameters. The sample elements each represent a different type: C source code (type C), COBOL source code (type COB), and text (type TXT). To highlight the SEARCH ENVIRONMENT option, the type C and type COBOL elements are stored in Stages A and B, respectively, in the first environment. The type TXT element is stored at Stage D of the second environment. Stage A in this example is the entry stage for the first environment. Entry stages are defined through the C1DEFLTS environment table.
  • When the OPTIONS SEARCH ENVIRONMENT clause is not coded, the utility searches only Stage A of the first environment. This happens in Scenario 1.
  • When the OPTIONS SEARCH ENVIRONMENT ONLY clause is specified, the utility searches both Stages A and B of the first environment. This happens in Scenario 2.
  • When the OPTIONS SEARCH ENVIRONMENT MAP clause is specified, the entire map is searched. This happens in Scenario 3.
Test Elements
The utility is executed against three elements:
  • HELLO.C, which is a C program
  • HELLO.COB, which is a COBOL program
  • HELLO.TXT, which is a text file that further explains (sets) the scene
The elements are shown in the following sections.
The results of the search depend upon the attributes of each element as well as the information provided in the SEARCH ELEMENT request.
HELLO.C Element
Element HELLO.C
#include <stdio.h> void main() { printf("Hello, world!\n"); /* print 'Hello' message */ }
HELLO.COB Element
Element HELLO.COB
000100 ID DIVISION. 000200 PROGRAM-ID. HELLO. 000300 AUTHOR. DEVELOPMENT. 000400 INSTALLATION. CA. 000500 DATE-WRITTEN. FEBRUARY 14, 1994. 000600 DATE-COMPILED. 000700************************************************************* 000800* TRIVIAL PROGRAM TO DISPLAY 'HELLO' MESSAGE * 000900************************************************************* 001000 SKIP3 001100 ENVIRONMENT DIVISION. 001200 CONFIGURATION SECTION. 001300 SOURCE-COMPUTER. IBM. 001400 OBJECT-COMPUTER. IBM. 001500 INPUT-OUTPUT SECTION. 001600 FILE-CONTROL. 001700************** 001800 DATA DIVISION. 001900************** 002000************************************************ 002100 FILE SECTION. 002200************************************************ 002300************************************************ 002400 WORKING-STORAGE SECTION. 002500************************ 003000************************************************************** 003100************************************************************** 003200******************* 003300 PROCEDURE DIVISION. 003400******************* 003500 SKIP1 003900 DISPLAY 'HELLO, WORLD!' 004500 GOBACK.
HELLO.TXT Element
Element HELLO.TXT
Three elements, all named HELLO, comprise the sample elements for demonstrating the effects of the SEARCH ELEMENT SCL statement and its optional parameters. The sample elements are of type C, COB and TXT representing C source code, COBOL source code and this text document. To further highlight the SEARCH ENVIRONMENT option, the type C and COBOL elements will be stored in stages A and B, respectively, in the first environment and the type TXT element will be stored at stage D of the second environment; the environment mapping and the element location established for the sample reports is as follows: +--------+ +-----------------------------+ | | | | | V | V +------------+------------+ +-------------------------+ | STAGE A | STAGE B | | STAGE C | STAGE D | +------------+------------+ +------------+------------+ | SYS: SYS2 | | | | | | SBS: BASE | | | | | | TYP: C | | | | | | ELM: HELLO | | | | | | | SYS: SYS2 | | | | | | SBS: BASE | | | | | | TYP: COB | | | | | | ELM: HELLO| | | | | | | | | SYS:SYS2 | | | | | | SBS:BASE | | | | | | TYP:TXT | | | | | | ELM:HELLO | +------------+------------+ +------------+------------+ Environment: BATCHEN2 Environment: BATCHEN3 When OPTIONS SEARCH ENVIRONMENT is omitted, only stage A, the entry stage of the environment, is searched. When OPTIONS SEARCH ENVIRONMENT ONLY is specified, both stages A and B are searched, because A is the entry stage. (Note: If B is the entry stage, only B is searched.) Finally, when OPTIONS SEARCH ENVIRONMENT MAP is specified, the entire map is searched. In all cases, the first occurrence of an element is processed.
Scenario 1 Simple Search in Search-Only Mode
Scenario 1 is a simple search and demonstrates what happens when the SEARCH ELEMENT request contains no options, including the SEARCH ENVIRONMENT option. When the SEARCH ENVIRONMENT option is omitted, the utility searches only the entry stage of the specified environment. In this scenario, then, the utility searches only Stage A of environment BATCHEN2.
Simple Search SCL
The SCL for this request is shown here:
SEARCH ELEMENT HELLO FROM ENVIRONMENT BATCHEN2 SYSTEM SYS2 SUBSYSTEM BASE TYPE * FOR TEXT 'i'
Simple Search Output
The output from processing this request appears in the following sections.
The Search and Replace Control Statement Summary Report
No syntax or validation errors occurred. Processing continues for this request.
The Search and Replace Utility Execution Report
Only one element--HELLO.C--is searched for matches. The utility finds six matches for the FOR TEXT string in this element.
As mentioned above, the Search and Replace utility found 6 matches of the FOR TEXT string. The location in which the matches were found is listed.
Note that there is no entry in the LOCATION OF ADD/UPDATE OPERATION field. This is because the utility is operating in search-only mode. The element is not changed and not updated.
Scenario 2 Simple Search with Replace in Search-Only Mode
Scenario 2 is a simple search with replacement in search-only mode, demonstrating what happens in two situations:
  • You do not code the OPTIONS UPDATE ELEMENTS clause, but you do include a replacement string in the SCL.
    In this scenario, assume the ENSSCLOT DD statement has been allocated in the execution JCL. SEARCH ELEMENT SCL is generated for the element containing the search string.
  • You code OPTIONS SEARCH ENVIRONMENT ONLY.
    In this scenario, the utility searches both Stage A and Stage B of environment BATCHEN2.
Simple Search with Replace Mode SCL
The SCL for this request is shown here:
SEARCH ELEMENT HELLO FROM ENVIRONMENT BATCHEN2 SYSTEM SYS2 SUBSYSTEM BASE TYPE * FOR TEXT 'i' REPLACE WITH '<i>' OPTIONS CCID = "CCID-99" COMMENT = "Test scenario number 2" SEARCH ENVIRONMENT ONLY LIST DETAILS.
Simple Search with Replace Output
The utility generates SCL for any elements containing the search string, because a replacement string was provided in the SEARCH ELEMENT request and the ENSSCLOT DD statement was allocated. This SCL can be used as input when you run the utility again.
The utility also produces syntax, execution, and summary reports.
No syntax or validation errors occurred. Processing continues for this request.
The utility searched two elements, HELLO.C and HELLO.COB, but only element HELLO.C contains a match for the search string. Element HELLO.COB does contain the letter I, but not in lowercase format. Because the search string is case-sensitive, the utility does not consider the text a match.
The Search and Replace utility found three matches in element HELLO.C and no matches in HELLO.COB. The report lists the location where both elements were found. Note that the utility searched both Stage A and Stage B of environment BATCHEN2.
There is an entry in the LOCATION OF ADD/UPDATE OPERATION field, for element HELLO.C. This entry is for reference purposes only. The element is not modified and added or updated back into
CA Endevor
because the OPTIONS UPDATE ELEMENTS clause was not coded in the SEARCH ELEMENT request. The entry is provided to let you know what location will be affected should you decide to update the element with the replacement string.
The generated SCL statement is shown here:
SEARCH ELEMENT 'HELLO' FROM ENVIRONMENT 'BATCHEN2' SYSTEM 'SYS2' SUBSYSTEM 'BASE' TYPE 'C' FOR TEXT 'i' REPLACE WITH TEXT '<i>' OPTIONS CCID = 'CCID-99' COMMENT = 'Test scenario number 2' SEARCH ENVIRONMENT ONLY DATA TRUNCATION IS PROHIBITED LIST DETAILS UPDATE ELEMENTS .
Scenario 3 Search Environment Map, Replace, and Update
Scenario 3 is a search and replace operation, with several options coded to limit the search. This scenario demonstrates processing with the following:
  • The SEARCH ENVIRONMENT MAP feature
  • Multiple FOR TEXT clauses
  • The BOUNDS ARE clause (for one FOR TEXT clause)
  • The WHERE CCID clause
  • The LIST DETAILS clause
Search Environment Map SCL
The SCL for this request is shown here:
SEARCH ELEMENT HELLO FROM ENVIRONMENT BATCHEN2 SYSTEM SYS2 SUBSYSTEM BASE TYPE * FOR TEXT 'i' REPLACE WITH '*' FOR TEXT 'T' REPLACE WITH TEXT '$' BOUNDS ARE 1 TO LAST WHERE CCID = 'CCID-02' OPTIONS CCID = "CCID-99" COMMENT = "Test scenario number 3" SEARCH ENVIRONMENT MAP LIST DETAILS UPDATE ELEMENTS.
BOUNDS ARE is set to BOUNDS ARE 1 TO LAST to demonstrate type compare column checking in relation to the SCL statements.
WHERE CCID limits the search to those elements whose CCID is CCID-02.
The CCID and comment provided in the OPTIONS clause are assigned to the element when it is added (updated) back into
CA Endevor
.
LIST DETAILS tells the utility to print the original line of text where the search string is found and the line of text after the string is replaced.
UPDATE ELEMENTS indicates that the element is to be added or updated into
CA Endevor
after the text string is replaced.
Search Environment Map Output
The output from processing this request is shown next. Along with the syntax, execution, and summary reports is a copy of the updated element.
No syntax or validation errors occurred. Processing continues for this request.
The utility searched only one element--HELLO.TXT. The element was found up the map, in Stage D of BATCHEN3. Substitution was performed, as appropriate, for each FOR TEXT clause.
Note message ENBS048E (immediately after the SCL request). A matching element was found in Stage A of environment BATCHEN2, but the column values specified in the SEARCH ELEMENT request are outside the compare column values for the element. This is why only one element was searched.
Note the information message lines ENBS016I and ENBS017I. ENBS016I lines present the original line of text containing the search string. ENBS017I lines show the line of text after the search string has been replaced.
A processing code of 12 was returned for the request. The utility processes a request as long as the return code does not exceed 12.
The Search and Replace utility found a total of 66 matches for the search strings in the SEARCH ELEMENT request. All information for the element is presented on the first line for Statement 1. Statement line 1.1 indicates the number of matches found for the first FOR TEXT clause. Statement line 1.2 indicates the number of matches found for the second FOR TEXT clause.
Although the element was found in Stage D of environment BATCHEN3, it is added into
CA Endevor
at the entry stage (Stage A) of the base environment (BATCHEN2).
The result of the replace operation on element HELLO.TXT:
Three elements, all named HELLO, compr*se the sample elements for demonstrat*ng the effects of the SEARCH ELEMEN$S SCL statement and *ts opt*onal parameters. $he sample elements are of type C, COB and $X$ represent*ng C source code, COBOL source code and th*s text document. $o further h*ghl*ght the SEARCH ENVIRONMEN$ opt*on, the type C and COBOL elements w*ll be stored *n stages A and B, respect*vely, *n the f*rst env*ronment and the type $X$ element w*ll be stored at stage D of the second env*ronment; the env*ronment mapp*ng and the element locat*on establ*shed for the sample reports *s as follows: +--------+ +---------------------------------+ | | | | | V | V +------------+------------+ +-----------------------+ | S$AGE A | S$AGE B | | S$AGE C | S$AGE D | +------------+------------+ +------------+----------+ | SYS: SYS2 | | | | | | SBS: BASE | | | | | | $YP: C | | | | | | ELM: HELLO | | | | | | | SYS: SYS2 | | | | | | SBS: BASE | | | | | | $YP: COB | | | | | | ELM: HELLO | | | | | | | | |SYS: SYS2 | | | | | |SBS: BASE | | | | | |$YP: $X$ | | | | | |ELM: HELLO| +------------+------------+ +------------+----------+ Env*ronment: BA$CHEN2 Env*ronment: BA$CHEN3 When OP$IONS SEARCH ENVIRONMEN$ *s om*tted, only the entry stage of the env*ronment, *s searched. When OP$IONS SEARCH ENVIRONMEN$ ONLY *s spec*f*ed, both stages A and B of the entry env*ronment are searched. F*nally, when OP$IONS SEARCH ENVIRONMEN$ MAP *s spec*f*ed, the ent*re map *s searched. In all cases, the f*rst occurrence of an element *s processed.
Update Output Data Set Name in Component List
You can use the Search and Replace utility to update an element's component list to change the output data set name. This allows you to update the data set name to reflect the current location of the output, which became outdated when the element was moved and not regenerated. This data is updated in place. For example, if the element is at stage 2, it is not fetched back to stage 1, which would be done if the utility was used to update element source.
You might want to use this option to address problems that can occur when the component data contains out of date information. For example, an error occurs when using LL (List Listing) from the Quick Edit or List Element panels for an element that was moved but not regenerated. In that case, the component data points to the list lib used when the element was last generated, not to the current list lib in which the listing resides. This causes the LL to fail because the member is no longer present in that library. The same problem can exist for other output libraries (such as LOADLIBs) and automated CONDELE with 'PARM=*COMPONENTS'.
Any user with ESI security move authority for the element is authorized to update the component data at stage 2, if it is a non-entry stage. Any user with ESI security update authority for the element is authorized to update the component data at stage 1, even if stage 1 is a non-entry stage. As with element source changes, a history of component data changes is maintained. Therefore, a user can see who changed output component data and when the change was made.
The JCL used to execute this utility can be found in member ENBSRPL1, in the JCL library iprfx.iqual.CSIQJCL. To specify the changes you want, you need to code an SCL statement in the JCL. The SCL specifies what component lists will be searched, what data set names will be searched for, and what data set names they will be replaced with.
In addition to replacement mode, you have the option to run the utility in validate mode to ensure the SCL is properly coded, or in search-only mode, which produces a report showing the component lists that include the data set names that are the object of your search.
Follow these steps:
  1. Add a valid job card at the front of the ENBSRPL1 job stream.
  2. Change the data set names and other variables in the JCL to the appropriate values for your installation.
  3. Code a Search Element Component List statement in the JCL's ENSSCLIN DD statement, as appropriate for the action you want to perform.
    To search for and replace a data set name, code the For clause and the Replace With clause and run the utility in the replacement mode by including the Options clause with the Update option. To search for and replace more than one data set name, you can include multiple combinations of the For clause and Replace With clause in one Search Element Component List statement.
    Before you update the component list, you may want to produce a report that lists the data sets found by the search. To produce a report instead of updating the component list, make sure that your SCL does
    not
    include the Update option on the Options clause. To produce a report, code at least the required keywords and variables of the Search Element Component List statement, which includes specifying the complete location of the element and the FOR clause to specify the data set you are searching for. However, do not include the Options clause Update option. To search for more than one data set name, you can include more than one For clause in one Search Element Component List statement.
    The SCL statement you code is used to specify what action the utility performs.
  4. (Optional) Add the validate parameter in the execution JCL after the PARM=ENBS1000 statement:
    PARM='ENBS1000VALIDATE'
    You can abbreviate VALIDATE in the parameter, using any of the following entries: V, VA, VAL, VALID, VALIDA, or VALIDAT
    The utility will operate in validate mode.
  5. Execute the Search and Replace utility.
    The results of the Search and Replace utility depend on the how you coded the Search Element Component List statement and whether you included the validate parameter on the execution JCL.
    • If you specified the validate parameter, then the utility parses and verifies all the requests in the generated SCL statements for proper syntax, but does not execute the requests even if no syntax or validation errors are found. If no errors are found, the SCL statements are formatted, but processing stops after validation. The SCL actions are not performed. Errors other than syntax errors are not noted at this time.
    • If you did
      not
      specify the validate parameter, then the utility parses and validates all the requests before processing them. If the parser or validation routine detects an error, the utility will not execute any of the statements. The parsing routine attempts to parse all of the control statements before terminating. If no errors are found, then the SCL action is performed.
      • If the SCL does
        not
        include the Update option, then a report is produced.
      • If the SCL does include the Update option, then the component list's output data set name that is the object of the search (as specified in the FOR clause) is replaced with the data set name (specified in the Replace clause).
Search Element Component List
The Search Element Component List syntax for the Search and Replace utility, ENBSRPL1, is shown next:
►►─ SEArch ELEment COMPonent LIST ─ element-name ─────────────────────────────► ►─ ──┬──────────────────────────────┬─────────────────────────────────────────► └─┬─ THRough ─┬─ element-name ─┘ └─ THRu ────┘ ►─ FROm ─ ENVironment ─ env-name ─ SYStem ─ sys-name ─────────────────────────► ►─ SUBsystem ─ subsys-name ─ TYPe ─ type-name ────────────────────────────────► ►─┬─ STAge ─ stage-id ────────────┬─ FOR ─┬─────────────────┬─ 'dsname' ──────► └─ STAge NUMber ─ stage-number ─┘ └─ OUTput DSName ─┘ ►─┬──────────────────────────────────────────────────┬────────────────────────► └─ REPlace WITh ─┬────────────────────┬─ 'dsname' ─┘ └─ OUTput DSName ────┘ ►─┬──────────────────────────────┬────────────────────────────────────────────► └─ WHEre ─ ¤ ─┬──────────┬─ ¤ ─┘ ├─┤ CCID ├─┤ └─┤ PRO ├──┘ ►─┬───────────────────────────────────────────────────┬─ . ───────────────────┤ └─ OPTion ─ ¤ ─┬──────────────────────────────┬─ ¤ ─┘ ├─ CCId ─┬──────┬─ ccid ───────┤ │ ├─ EQ ─┤ │ │ └─ = ──┘ │ ├─ COMment ─┬──────┬─ comment ─┤ │ ├─ EQ ─┤ │ │ └─ = ──┘ │ ├─ LISt DETails ───────────────┤ └─ UPDate ─┬───────────┬───────┘ └─ ELEment ─┘
Parameters
This action uses the following parameters:
  • SEArch ELEment COMPonent LISt
    element
    Specifies one or more element component lists to be searched.
    • THRough
      element
    • THRu
      element
      (Optional) Indicates that a range of elements are to be searched, up to and including the element named in this clause. The element in the Search Element Component List clause specifies the first element in the range.
  • FROM
    Identifies the inventory location from which the search begins. You must use the keywords environment, system, subsystem, type, and either the stage or the stage number.
    • ENVironment
      env-name
      Identifies the environment. The environment must be fully specified, you cannot use a name mask.
    • SYStem
      sys-name
      Identifies the system. You can fully specify the name or use name mask.
    • SUBsystem
      subsys-name
      Identifies the subsytem. You can fully specify the name or use name mask.
    • TYPe
      type-name
      Identifies the type. You can fully specify the name or use name mask.
    • STAge
      stage-id
    • STAge NUMber
      stage-number
      Identifies the stage. You can use either the stage or the stage number, but not both. You must fully specify the stage or the stage number; name masking is not allowed. This value is the stage at which the element exists. Component data will be updated in place, that is there will be no copy back from stage 2 to stage 1.
  • FOR
    dsname
  • FOR OUTput DSName
    dsname
    Identifies the name of the data set that is the object of the search. You can specify FOR
    dsname
    or FOR OUTput DSName
    dsname
    ; the OUTput DSName keyword is optional. Name masking is not allowed.
  • REPlace WITh
    dsname
  • REPlace WITh OUTput DSnam
    dsname
    (Optional) Specifies a data set name to replace the data set name identified in the FOR clause. You can specify REPlace WIth
    dsname
    or REPlace WIth OUTput DSName
    dsname
    ; the OUTput DSName keyword is optional. The value must reference an existing data set name. Name masking is not allowed.
    If this option is not specified, then the utility will simply search for the output data set component name identified in the For clause.
    You can include more than one combination of For clause and Replace With clauses in a single Search Element action. The data set specified in the For clause is replaced with the data set specified in the immediately following Replace clause.
    If an invalid data set name is specified or an uncataloged Replace With data set name is specified, then none of the clauses will be processed.
  • WHEre
    (Optional) Specifies additional element selection criteria. Limits the search to only those elements whose CCID or processors group match the specified value.
    • CCID OF ANY|BASe|GENerate|LASt ACTion|RETrieve EQ|=
      ccid
      Specifies the CCID that must be associated with the element for the utility to search the element. You can use either the keyword EQ or the equal symbol (=) in this clause.The
      ccid
      value can be 1 to 12 characters. Name masking is allowed. If you fully wildcard the
      ccid
      value, or you do not specify this clause, elements are selected regardless of their CCID.
      You can specify a list of CCIDs, with each value separated by a comma and the entire list enclosed in parentheses. For an element to be selected for processing, the CCID associated with the element must match at least one CCID in the list. The utility checks only the current MCF for the CCID.
    • OF ANY|BASe|GENerate|LASt ACTion|RETrieve
      (Optional) Specifies where the matching CCID can be located to limit the search to only those elements whose base, generate, last action, or retrieve CCID match the CCID specified in the request.
    • ANY
      (Optional) All CCIDs in the current MCF are searched. The default.
    • BASe
      (Optional) All CCIDs in the current MCF associated with a base level element are searched.
    • GENerate
      (Optional) All CCIDs in the current MCF associated with a generate action on an element are searched.
    • LASt ACTion
      (Optional) All CCIDs in the current MCF associated with the last action on an element are searched.
    • RETrieve
      (Optional) All CCIDs in the current MCF associated with a retrieve action on an element are searched.
    • PROCessor GROup EQ|=
      group
      Specifies a 1- to 8-character processor group that must be associated with the element in order for the utility to search the element. Name masking is allowed. You can specify a list of processor groups, with each value separated by a comma and the entire list enclosed in parentheses. For an element to be selected for processing, the processor group associated with the element must match at least one of the processor groups in the list.
  • OPTions
    (Optional) The options clause allows you to further qualify your request. You can specify none, one, or more than one option. The CCID and COMMENT options maybe required depending on your element system record requirements. The Update Element option is required to run the utility in replacement mode.
    • CCID EQ|=
      ccid
      (Optional) Specifies the CCID to be associated with the element when the element is added (or updated) back into
      CA Endevor
      . This CCID is assigned to the last action CCID and the generate CCID. The CCID can be from 1 to12 characters in length, and must be explicit. This clause is optional except under the following condition: the element's system record requires that a CCID be coded and you code the REPLACE WITH clause in the request. It is optional to include either the EQ keyword or the equal sign (=), neighther are required.
    • COMMENT EQ|=
      comment
      (Optional) Specifies the comment to be associated with the element when the element is added (or updated) back into
      CA Endevor
      . The comment can be from 1-40 characters in length. If the comment contains imbedded spaces or punctuation marks, the text must be enclosed by string delimiters. This clause is optional except under the following condition: the element's system record requires that a comment be coded and you code the REPLACE WITH clause in the request.
    • LISt DETails
      (Optional) Indicates that you want to list, on the Search and Replace Utility Execution Report, each output data set name component found and, if run in replace mode, each new output data set name. Each element searched, along with the number of matches found in that element (0 to 99999), is printed to the execution and summary report, regardless of the LIST DETAILS option setting.
    • UPDate ELEment
      (Optional) Indicates that the utility is operating in replacement mode. The utility replaces the data set name specified in the For clause with the data set name specified in the Replace clause. The utility operates in search-only mode, if either the Replace With clause or the Update Element clause is not coded.