Creating and editing collections

Collections

A collection entity is created so that it can be input to a collection run. Running a collection collects metadata from a specific source— such as COBOL— and adds the collected metadata to a repository.

When a collection is run, the Metadata Analyzer determines whether any collected entities have been changed and if there are any new or deleted entities. If any updates have occurred, the Metadata Analyzer collects any new or updated entities and removes deleted entities accordingly. Any new or changed COBOL or PL/I programs are then submitted to the learning process to be learned.

If, for some reason, a collection is stopped or does not complete, a subsequent run of the collection will perform the updates necessary to reflect the current state of the collected application.

Collections are created by doing the following:

• Selecting the collection type— such as COBOL—based on the source from which you want to collect. Sources that the Metadata Analyzer collects from include:
  • COBOL
  • PL/I
  • Assembler
  • Programs in the Compuware DDIO source listing file
  • DB2
  • Batch JCL
  • CICS
  • IMS

Click the links above for information specific to each of these collection types.

• Specifying collection properties such as where you want to collect from and how you want the collection to operate.

For example, if you want to collect COBOL source, you would select the COBOL collection type. Then, you would specify the location of the COBOL source to include in the collection. Finally, you would indicate how you want the collection run to operate.

Tips about collections

Determining whether to have small collections or large collections

There are merits to having small collections and also to having large collections.

Small collections are required if you need to set up custom concatenation for the Include libraries. If the concatenation varies, then you will need separate collection for each variance.

Small collections also have the advantage of having that collection entity attached to all entities in the collection. This is useful if you want to search for all programs in that particular application for example.

On the other hand many small collections could make it harder to maintain. If you moved a copy library you would then have to go into each collection and change it.

Larger collections can be easier to administer, but you lose the ability to uniquely identify by individual collections and this would not work if you used difference concatenations.

The process to convert from small collections to larger collections is simple.

1. Creating the large collection that will encompass many smaller collections.
2. Run this collection. It will recollect, but should not redownload (unless there are changes). It will detect that these entities are currently in the database and it will add a relationship of the collection entity to them. Each of these entities will now be related to two different collections.
3. Delete the small collections. When you do this a message appears stating that deleting the collections could have the effect of deleting everything related to the collection. This is acceptable because it will delete the relationship of the collection to every entity in the collection. If an entity is only related to that collection, which should not be the case here, then it will in fact delete that entity. After you have deleted the small collections you will be left with the one larger collection that you can use to maintain the repository.

Collecting all versions of a program that resides in multiple libraries

If a collection includes multiple concatenation of source libraries and a given program exists in more than one of them, the Metadata Analyzer will only collect the first occurrence of a given program. Additional versions of the same-named program will not be collected. This allows you to use staging libraries and keep the currently used version of the program in the repository. If you need each of the versions of the program to be collected, set up separate collections to collect from each of the concatenated libraries.

To create a new collection

Use the Collection Setup Worksheet to help you gather the information to set up the collection.

1. Create a new collection from the File menu by selecting New>Collection. The Collection dialog box appears.

   Note

   Only an administrator can create a collection.

2. In the Name field, give the new collection entity a name.
3. In the Type field, select from the drop-down list the collection type that applies to the type of metadata you want to collect.
4. In the Connection field, select an existing connection name or set up a new connection by selecting New from the drop-down list. If you select New, a dialog will open so you can set up a new connection.
5. Complete the Collection Properties box by referring to the field descriptions for the type of collection you are creating. The collection properties reflect the collection type you chose. Some properties apply to what you want to collect. Others have to do with how you want the collection to operate when run.
   • Assembler
   • CICS
   • COBOL
   • DB2
   • DDIO
   • IMS
   • JCL
   • PL/I
6. To type or search for mainframe datasets to populate a dataset field (such as the Source Libraries field for a COBOL collection) click anywhere in that property's row. The field expands.
7. Do either of the following:
   • Type the dataset name
   • Click Search to open the Search Datasets dialog box to search for datasets.
8. If you chose to search for datasets, do the following:
   • In the Filter dialog box, enter in the Search Datasets dialog box a partial dataset name and click . The Found datasets box populates with datasets that match your filter.

   • Select the datasets you want added to the Collections dialog box then click  to add them to the Selected datasets box.

     Note

     A high-level qualifier is required in the Filter field. Following that, wildcarding can be used.

   • Click OK. The datasets are added to the Collections dialog box.

     Note

      adds all datasets to the Selected datasets box. removes the selected dataset. removes all datasets. moves the selected dataset higher in the list. moves the selected dataset lower in the list. When the collection is run, libraries are searched based on the order in which they appear in the Collections dialog box.

9. Complete the User Label field if you want to flag all entities collected by this collection. The Properties view for each entity this collection collects will have this user label.
10. When you have completed this dialog box, click OK to save your collection. If you chose an existing connection, you may be asked to provide your connection password.

To edit a collection

If you want to change any of the properties of a collection, simply edit the collection. If certain criteria of a collection is changed, all entities related to the collection are deleted from the repository the next time the collection is run. Changing the following criteria causes entities to be deleted:

1. Open the collection by doing one of the following:
   • In the Entities view, select the collection. Then, from the File menu, select Open.

   • In the Entities view, right-click the collection and select Open.

     The Collection dialog box appears and is populated with information about the collection.

2. Make changes to the collection as needed.
3. Click OK to save the collection to the repository.
   If the connection used by the collection has a password, you will be asked to provide this password before your changes to the collection are saved.

To copy a collection

To save time when you want to create a new collection that is similar to an existing collection, just copy the existing collection.

1. Open the existing collection by doing one of the following:
   • In the Entities view, select the collection. Then, from the File menu, select Open.

   • In the Entities view, right-click the collection and select Open.

     The Collection dialog box appears and is populated with information about the collection.

2. Click Save As to open the Save As dialog box and change the existing name to the name you want for the new collection.

   If the connection used by the collection has a password, you will be asked to provide this password before you can copy the collection.

3. Make changes to the collection information and properties as needed to customize them to the new collection.
4. Click OK to save the collection to the repository.

To rename a collection

Do the following to rename a collection.

1. Open the existing collection by doing one of the following:
   • In the Entities view, select the collection. Then, from the File menu, select Open.
   • In the Entities view, right-click the collection and select Open.
   • The Collection dialog box appears and is populated with information about the collection.

2. Click Rename and change the existing name to the new name.

   If the connection used by the collection has a password, you will be asked to provide this password before you can rename the collection.

3. Click OK to save the collection to the repository.

Wildcarding the Filter field

Robust ISPF 3.4 wildcarding functionality is available in the Search dialog box's Filter field. The following symbols, when specified within the dataset name filter, are interpreted as follows:

• A single asterisk by itself (*) indicates that either a qualifier or one or more characters within a qualifier can occupy that position. An asterisk can precede or follow a set of characters.
• A double asterisk (**) indicates that zero or more qualifiers can occupy that position. A double asterisk cannot precede or follow any characters; it must be preceded or followed by either a period or a blank.
• A single percent sign by itself (%) indicates that exactly one alphanumeric or national character can occupy that position.
• One to eight percent signs (%%) can be specified in each qualifier.

For example:

• ABCDEFG.DS%
   will return ABCDEFG.DS1 and ABCDEFG.DS2
   but not ABCDEFG.DS10
• ABCDEFG.DS%%
   will return ABCDEFG.DS10 and ABCDEFG.DS11
   but not ABCDEFG.DS1
• ABCDEFG.*.DS
   will return ABCDEFG.MY.DS
   but not ABCDEFG.MY.DS.FILE
• ABCDEFG.*A
   will return ABCDEFG.A and ABCDEFG.BA and ABCDEFG.BBA
   but not ABCDEFG.B or ABCDEFG.AB
• ABCDEFG.DATA.*
   will return ABCDEFG.DATA.SET1 and ABCDEFG.DATA.SET2
   but not ABCDEFG.DATA.SET.FILE
• ABCDEFG.DATA*
   will return ABCDEFG.DATA1and ABCDEFG.DATA23
   but not ABCDEFG.DATA.SET
• ABCDEFG.**
   will return ABCDEFG and ABCDEFG.DATA.SET1and ABCDEFG.DATA.SET2 and ABCDEFG.DATA.SET.KSDS
   but not ABCDEFG1.DATA.SET
• ABCDEFG.DATA.SET
   will return ABCDEFG.DATA.SET only
• **.DATA
   will return entry names whose low level qualifier is DATA, such as ABCDEFG.DATA and HIJKLMN.WORK.DATA