List from Archive Data Set Syntax

Processing Element Actions › The List Statement › List from Archive Data Set › List from Archive Data Set Syntax

List from Archive Data Set Syntax

►►─ LISt ELEment ─ element-name ─┬──────────────────────────────┬─ FROm ──────►
                                 └─┬─ THRough ─┬─ element-name ─┘
                                   └─ THRu ────┘

 ►─┬─ FILe ───┬─ dd-name ─┬──────────────────┬─ ENVironment ─ env-name ───────►
   └─ DDName ─┘           └─ SITe ─ site-id ─┘

 ►─ SYStem ─ sys-name ─ SUBsystem ─ subsys-name ─ TYPe ─ type-name ───────────►

 ►─ STAge NUMber ─ stage-no ──────────────────────────────────────────────────►

 ►─┬─────────────────────────────────────────────────────────────┬────────────►
   └─ TO ─┬─ SYSOut ◄ ─────────────────────────────────────────┬─┘
          ├─┬─ FILe ───┬─ dd-name ─────────────────────────────┤
          │ └─ DDName ─┘                                       │
          └─ DSName ─ dataset-name ─┬────────────────────────┬─┘
                                    └─ MEMber ─ member-name ─┘

 ►─┬──────────────────────────────────────────────────────┬───────────────────►
   └─ WHEre ─ ¤ ─┬──────────────────────────────────┬─ ¤ ─┘
                 ├─┤ CCID ├─────────────────────────┤
                 ├─┤ PRO ├──────────────────────────┤
                 └─ ARChive ─┬─┤ DATE ├───────────┬─┘
                             ├─┤ FROM ├───────────┤
                             ├─┤ THROUGH ├────────┤
                             └─┤ FROM - THROUGH ├─┘

 ►─┬─────────────────────────────────────┬────────────────────────────────────►
   └─ BUIld ─ ACTion ─┬─ &.&Action. ◄ ─┬─┘
                      └─ action-name ──┘

 ►─┬───────────────────────────────────────────────────┬─ . ──────────────────►◄
   └─ OPTion ─ ¤ ─┬──────────────────────────────┬─ ¤ ─┘
                  ├─ REPlace member ─────────────┤
                  ├─ DETail REPort ──────────────┤
                  └─ SHOw TEXt ─┬──────────────┬─┘
                                └─ PLUsnlines ─┘

Expansion of CCID

                       ┌─ , ────┐
├── CCId ─┬─ EQ ─┬─ ( ─▼─ ccid ─┴─ ) ──────────────────────────────────────────┤
          └─ = ──┘

Expansion of DATE

├── DATe ─┬─ EQ ─┬─ date ─┬────────────────────────┬───────────────────────────┤
          └─ = ──┘        └─ TIMe ─┬─ EQ ─┬─ time ─┘
                                   └─ = ──┘

Expansion of FROM

├── FROm ─ DATe ─┬─ EQ ─┬─ date ─┬────────────────────────┬────────────────────┤
                 └─ = ──┘        └─ TIMe ─┬─ EQ ─┬─ time ─┘
                                          └─ = ──┘

Expansion of THROUGH

├──┬─ THRough ─┬─ DATe ─┬─ EQ ─┬─ date ─┬────────────────────────┬─────────────┤
   └─ THRu ────┘        └─ = ──┘        └─ TIMe ─┬─ EQ ─┬─ time ─┘
                                                 └─ = ──┘

Expansion of PRO

                                  ┌─ , ──────────┐
├── PROcessor GROup ─┬─ EQ ─┬─ ( ─▼─ group name ─┴─ ) ─────────────────────────┤
                     └─ = ──┘

LIST ELEMENT element-name

Specifies the elements to be listed. You can specify a name-masked element name.

THROUGH (THRU) element-name

Specifies a range of elements to be listed, beginning with the element coded in the LIST ELEMENT clause, up to and including the element specified in this clause. You can specify a name-masked element name. If you code the THROUGH clause, you cannot enter a member name in the TO clause.

FROM FILE (DDNAME)dd-name SITE site-id ENVIRONMENT env-name SYSTEM system-name SUBSYSTEM subsys-name TYPE type-name STAGE NUMBER stage-no

Specifies the location of the element to be listed. You must code a FILE or DDNAME for the archive data set to be searched for the specified element. Enter this information first when coding the syntax. The SITE site-id is optional.You must specify an environment, system, subsystem, type, and stage number (either 1 or 2). The environment name must be explicit. You can name mask the system, subsystem, type, and stage.

The From clause and any preceding Set From statements determine the from criteria for the action. Specify the from criteria according to the following rules:

The from criteria must be fully specified, except for the SITE site-id. This includes the archive file ddname and all the inventory location specifications (Environment, System, Subsystem, Stage, Type, and Stage).
All the From fields can be specified on a single Set From statement, without the existence of the FROM clause or any FROM fields within the action syntax.
All the From fields can be specified within the action syntax, without the existence of a Set From statement.
To be valid, a Set From statement must specify the archive FILE ddname and one or more of the inventory location specifications, and no other Set From statements can exist before the action statement.
If the Set From statement is coded correctly, any of the FROM inventory location field values can be overridden in the action syntax. The FROM clause on the action must specify any of the criteria missing from the Set From statement.

In the following cases, an action with an invalid from criteria specification can complete processing, but list elements from the production inventory, instead of the archive data set:

If more than one Set From statement exists. In this case, only the last statement is used, but the location defaults to the production environment.
If any of the criteria are missing, the location defaults to the production environment.

Note: If the action executes against the archive file, the following message appears in the Action Execution Report:

C1G0213I        FROM ARCHIVE FILE: ARCHFILE

If the action executed, but you do not see this message, the action was performed against the production inventory location that is coded on the request. If the elements exist in the production environment, the action may complete successfully. However, the list will include elements found in the production environment, instead of the archive data set. If the elements do not exist in the production environment, a message is issued that indicates that the ENV env-name is not found.

Note: For more information about the from criteria and the SET FROM statement, see Examples: From Criteria Specification for List Element From Archive.

TO

Specifies where the element is to be listed. CA Endevor SCM uses both the TO clause in an action and any preceding SET TO clause to determine the "to" criteria for that action.

A TO clause in an action overrides values in a SET TO clause that precedes the action.
If the SET TO clause contains values that are not included in the TO clause, CA Endevor SCM uses these values.

TO SYSOUT-

SYSOUT is the default TO location. If you do not provide a TO clause, and no SET TO information has been coded, CA Endevor SCM writes the action cards to the Execution Report. The Execution Report appears immediately after the LIST action request and cannot be edited.

TO FILE (DDNAME) dd-name or DSNAME dataset-name-

You can tell CA Endevor SCM to write action cards to both the Execution Report and an external data set by providing a file name (DDname) or a data set name; if you enter a FILE or DDNAME, be sure the appropriate JCL is coded. Use this option if you want to edit the action cards.

TO MEMBER member-name-

Enter a member name. This clause is valid only if you are not specifying a sequential file.

CA Endevor SCM ignores a member specification if you have coded the TO SYSOUT option.

The action fails if you code a member name along with a file (DDname) or data set name that is sequential.
If you are using PDSs and do not provide a member name, CA Endevor SCM assigns a temporary name of TEMPNAME. If you wish to use the temporary naming capability, do not code multiple list requests to the same external data set.

If you are using a PDS and have multiple list statements with only one member name on a SET statement, then all lists go to same member name and only first LIST results are available.

WHERE

Use WHERE clauses to further qualify element selection criteria. CA Endevor SCM uses both the WHERE clause in an action and any preceding SET WHERE clause to determine the "where" criteria for that action.

A WHERE clause in an action overrides values in a SET WHERE clause that precedes the action.
If the SET WHERE clause contains values that are not included in the WHERE clause, CA Endevor SCM uses these values.

WHERE CCID ccid -

Limits the list to those elements that match one of the supplied CCIDs. You can use a name mask in this field.

If you need to select elements identified under more than one CCID, you can specify multiple CCIDs by enclosing the CCIDs with parentheses and separating them with commas. The CCIDs may extend over multiple lines if necessary.

The next examples illustrate the use of this clause.

Example 1:  WHERE CCID EQ PROJ00V
Example 2:  WHERE CCID (PROJ001, PROJ002, PROJ004)

WHERE ARCHIVE-

This clause allows you to select elements based on the date and, optionally, time that an element was archived. There are four possible forms for this clause:

WHERE ARCHIVE DATE mm/dd/yy [TIME hh:mm ]

This clause tells CA Endevor SCM to list only those elements with this archive date, and optionally, time stamp.

WHERE ARCHIVE FROM DATE mm/dd/yy [TIME hh:mm ]

This clause tells CA Endevor SCM to list all elements with an archive date and, optionally, time stamp on or after the specified date and time stamps.

WHERE ARCHIVE THROUGH DATE mm/dd/yy [TIME hh:mm]

This clause tells CA Endevor SCM to list all elements with an archive date and, optionally, time stamp earlier than and including the specified date and time stamp.

WHERE ARCHIVE FROM DATE mm/dd/yy [TIME hh:mm ] THROUGH DATE mm/dd/yy [TIME hh:mm ]

This clause tells CA Endevor SCM to list only those elements with archive date, and optionally, time stamps within the specified range. If you enter a time, you must enter the date with it.

WHERE PROCESSOR GROUP group name-

This clause allows you to select elements according to a specified processor group. You can use a name mask when specifying the processor group name.

If you need to select elements identified under more than one processor group, you can specify multiple distinct processor group selectors by enclosing the processor groups with parentheses and separating them with commas. The processor groups may extend over multiple lines if necessary.

The next examples illustrate the use of this clause.

Example 1:  WHERE PROCESSOR GROUP  (COBVS, COBII)
Example 2:  WHERE PROCESSOR GROUP  (COBV)

BUILD ACTION&&ACTION. | action-name

Determines the action that appears in the LIST action syntax for the specified element. If you do not enter required BUILD information here, CA Endevor SCM looks for a SET BUILD clause containing the appropriate information. If a SET BUILD clause has not been coded, the system defaults to &&ACTION.

You can enter a specific action (for example, ADD or MOVE) in this clause or the variable &&ACTION. &&ACTION. indicates that a specific action will be designated for this element at a later time. This action can be entered manually or using the SET ACTION statement.

OPTIONS

OPTIONS clauses allow you to further specify action requests.

REPLACE MEMBER-When you specify a PDS and member name in the TO clause, LIST requests fail if the member already exists. Use the REPLACE MEMBER option if you want to replace the existing member in the TO location library.

DETAIL REPORT-By default, in the Execution Report, CA Endevor SCM lists only those elements matching the selection criteria you specify. If you select the DETAIL REPORT option, every element searched is listed in the report-whether or not a match is found.

SHOW TEXT [ PLUS n LINES ]-This option allows you to print the line of source code that contains a specified text string, plus a designated number of lines of code before and after the text string.

Examples: From Criteria on List Element from Archive Action

The following examples show valid and invalid from criteria specifications for the List Element From Archive statement.

These examples work as expected to perform the action against the archive location:

All the FROM fields can be coded on a single SET statement, as shown next.

SET FROM FILE                     
    ARCHFILE                      
    ENV ENV1                      
    SYS 'P7015'                   
    SUB 'P7015'                   
    TYP 'P7015'                   
    STA NUM 1.                      
LIST ELEMENT *                    
    TO DDNAME SCLSTMTS MEMBER LIST1
BUILD ACTION &&ACTION             
 .

All the FROM fields can be coded within the action syntax without the existence of a SET FROM statement containing inventory location information, as shown next:

SET STOPRC 16 .                                                       
LIST ELEMENT *                                                        
    FROM FILE                                                         
    ARCHFILE                                                          
    ENV 'ENV1' SYSTEM 'P7015' SUBSYSTEM 'P7015' TYPE 'P7015' STA NUM 1
    TO DDNAME SCLSTMTS MEMBER LIST2                                    
BUILD ACTION &&ACTION                                                 
 .

When mixing the FROM fields between a SET statement and the action, the SET FROM FILE and at least one of the FROM inventory location fields must be specified in a single SET statement and no other SET statement containing FROM inventory location information can exist. A valid example is shown next:

SET FROM FILE                      
    ARCHFILE                       
    ENV ENV1                       
    TYP 'P7015'                    
    STA NUM 1.                     
LIST ELEMENT *                     
FROM SYSTEM 'P7015' SUBSYSTEM P7015
    TO DDNAME SCLSTMTS MEMBER LIST4 
BUILD ACTION RESTORE                
 .

SET FROM FILE                      
    ARCHFILE                       
    ENV ENVZ                       
    TYP 'ZZZZ'                    
    STA NUM 1.                     
LIST ELEMENT *                     
FROM ENV ENV1 SYSTEM 'P7015' SUBSYSTEM P7015 TYPE P7015 STA NUM 2 
    TO DDNAME SCLSTMTS MEMBER LIST4 
BUILD ACTION TRANSFER                
 .

In the following example the BUILD ACTION value is DELETE. This is supported, but the FROM FILE ddname and WHERE ARCHIVE DATE SCL clauses are suppressed in the generated SCL so they can be executed against an CA Endevor SCM Environment instead of an archive file. DELETE is the only action that works this way.

SET FROM FILE                                         
    ARCHFILE                                          
    SUBSYSTEM 'P7015' .                               
LIST ELEMENT *                                        
FROM ENV 'ENV1' SYSTEM P7015 SUBSYSTEM P7015 TYPE 'P7015'  STA NUM 1
    TO DDNAME SCLSTMTS MEMBER DELETE                  
BUILD ACTION DELETE.                                                            
 .

Generated SCL statements;

SET FROM ENVIRONMENT  ENV1      SYSTEM  P7015     SUBSYSTEM  P7015
         TYPE  P7015     STAGE NUMBER 1
.                           
DELETE   ELEMENT   P7015A        .                           
DELETE   ELEMENT   P7015B        .                           
DELETE   ELEMENT   P7015C        .

These examples are coded incorrectly and do not perform the action against the archive location:

In the following example, more than one SET FROM statement exists. The second SET FROM clears the first and CA Endevor SCM assumes the list action is against the production inventory location instead of an ARCHIVE file. This action may execute successfully depending on whether elements exist at the production inventory location, but it is probably not what the request was intended to do. Message C1G0213I will not be found in the CA Endevor SCM Execution Report associated with this action.
```
SET FROM FILE                                         
    ARCHFILE.                                         
SET FROM                                              
    SUBSYSTEM 'P7015' .                               
LIST ELEMENT *                                        
FROM ENV 'ENV1' SYSTEM 'P7015' TYPE 'P7015' STA NUM 1
    TO DDNAME SCLSTMTS MEMBER DELETES                  
BUILD ACTION &&ACTION                                   
 . 
```

In the following example the second SET FROM statement cancels out the first SET FROM statement. Therefore the SET FROM including the subsystem is ignored and the action fails due to the missing subsystem specification.

SET FROM FILE                                         
    ARCHFILE                                          
    SUBSYSTEM 'P7015' .                               
SET FROM                                              
    SYSTEM    'P7015' .                               
LIST ELEMENT *                                        
FROM ENV 'ENV1'                TYPE 'P7015'  STA NUM 1
    TO DDNAME SCLSTMTS MEMBER TRANSFER                  
BUILD                                                            
 .                                                               
C1BM4100: E010 SUBSYSTEM REQUIRED ON "FROM" CLAUSE FOR THIS ACTION

In the following example the action fails due to the mixed coding (SET and action syntax) of the FROM information. The action is confused and issues message C1G0218E that is not very informative as to the actual issue.

SET FROM                            
    ENV ENV1                        
    SYS 'P7015'                     
    SUB 'P7015'                     
    TYP 'P7015'                     
    STA NUM 1                       
.                                   
LIST ELEMENT *                      
    FROM FILE ARCHIVE               
    TO DDNAME SCLSTMTS MEMBER BLDMOV
BUILD ACTION MOVE                   
 .

C1G0218E  LIST ACTION NOT ALLOWED AGAINST SEQUENTIAL DATA SET