How to map CICSPlex SM definitions

Use WUI maps to generate a visual representation of the relationships between resource definitions in the data repository.

The associations between CICS® resource definitions defined to CICSPlex® SM can be complex and difficult to visualize. For example, a CICS system can be associated with a specification and a specification might contain one or more groups. In turn groups can contain definitions. This type of structure is often portrayed as the branches of a tree. WUI maps are a method of generating a visual representation of this tree structure for a selected resource. This representation can portray business application services (BAS), resource monitoring (MON), real-time analysis (RTA), or workload management (WLM) definitions. Maps allow you to verify that the relationships between your definitions are what you expect.

All IBM®-supplied tabular and detail views that display resource definitions include a map button, which you click to generate a map. By default, the map displays definitions that are referred to by the selected definition, that is, it maps down-level. This operation is called a map right operation. For example, if the selected resource is a WLM specification, the map displays associated WLM groups, definitions and transaction groups. However, if your selected resource is already at the lowest level, for example a WLM transaction group or a BAS resource definition, the map displays all up-level relationships. In the case of a transaction group, the map displays associated definitions, groups and specifications. This operation is called map left.

How to interpret maps

A typical map is shown in Figure 1.
Figure 1. Diagram of a typical map view
Map of a CICS system definition showing its associated BAS resources including resource descriptions, resource groups, and resource definitions.
At the top of the map view are icons enabling you to do the following, from left to right:
  • Return to the previous detailed view.
  • Display a printer-friendly map view.
  • Switch to a map left view of the selected resource definition.
  • Switch to a map right view of the selected resource definition.
  • Expand all of the definitions on the map display.
  • Collapse all of the definitions on the map display.
There is no Add to favorites (add to favorites) icon on a map. You cannot bookmark a map as one of your favorites.

If you select more than one resource on a tabular view, you can click Next to display a map of the next selected resource.

By default, the map is normally displayed in the expanded state. However, you can alter this default behavior using the WUI server initialization parameter DEFAULTMAPCOLL, or for particular groups of users when specifying a user group profile.

The map is a table with between 4 and 18 columns. The map has two different types of columns; resource columns and connecting columns.

Resource columns contain the resource names of objects. The header shows the type of definition the column relates to; for example, WLM specification or WLM group. Resource names act as hyperlinks. If you click one, you open a detailed view of that resource.

Instead of a resource name, a resource column can contain one of the following symbols:
Horizontal line
Indicates that there is a higher-level resource name that is directly connected. No resource name corresponds to it.
Asterisks
Indicates that this row is in a collapsed state. This cell is at a lower level than the resource that performed the collapse.
Broken line ( - - - - - )
Displayed only in the RASINDSC column on a map of a BAS resource definition. It indicates that an association exists between the RESDESC and RESGROUP caused by the fields in a RASINDSC object. Without this symbol, it would imply that the association between the RESDESC and the RESGROUP was only a direct connection.
Connecting columns appear between resources on the map view. The header of a connecting column contains an icon showing the direction in which you must read the map, that is, an arrow pointing right for a map right (down-level) operation and an arrow pointing left for a map left (up-level) operation. Connecting columns contain one of the following symbols:
Horizontal bar
Shows that the values in the columns on either side of this bar are connected together. The bar might connect a resource to a blank space and vertical bar character, in which case it means that the resource is related to the first proper resource name encountered when moving up the table. For example, in Figure 1 resource group definition ATK2RG02 is connected to a cell with a bar character. This connection means that ATK2RG02 is associated with the first proper resource encountered when moving up the table, which is resource description DNMRKQ32.
Expand or collapse icon
Shows a connection in the same way as a horizontal bar. However, these icons are also used to expand and collapse parts of the map. If a resource has more than one lower-level resource associated with it, for example, a resource group with more than one resource definition, the connection column to the left of this resource contains a collapse icon (assuming it is in an expanded state). The collapse icon changes to an expand icon if you collapse the row.
Vertical bar
Indicates that a resource has a sibling and has more than one lower-level association. Each cell in the column displays a bar until the sibling resource name is rendered.

Some columns on a map, such as Resource definition, contain more than one resource type in the column. In such cases, an additional column is displayed containing the resource type of these resources.

You can initiate a map right or map left operation for most resources displayed on a map by selecting the adjacent radio button and clicking the map right or map left icon. The exceptions to this are CICS system or CICS group names because performing a further map operation on these resources does not result in any additional useful data. A map right command redisplays only the current data. A map left command produces a map with only the CICS system or CICS group name displayed.

Some columns on a map screen do not display true resources but provide additional information about relationships (for example Scope type on a BAS map). Because these are not true resources, it is not possible to perform a map left or map right operation on them.
Tip: If you are using a screen reader, you must ensure that it is properly configured to correctly interpret the information contained in the map. In particular note the following items:
  • Set the screen reader's punctuation mode to voice or display all symbols. This is because the vertical bar symbol denotes relationships between elements on a map. If the screen reader is not set up to voice or display the vertical bar symbol, the screen reader cannot determine the relationships between map elements.
  • Use the table mode option of the screen reader. This ensures that the map is read in its intended logical sequence.
The WUI supplies four default map objects. They are named as follows:
  • EYUSTARTMAPBAS for generating maps of business application services definitions
  • EYUSTARTMAPMON for generating maps of monitoring definitions
  • EYUSTARTMAPRTA for generating maps of real-time-analysis definitions
  • EYUSTARTMAPWLM for generating maps of workload management definitions.
Each map object includes links from the resource columns to detailed views of the named resource. In maps you create yourself in the view editor, you can customize links to point to different destinations including to your own customized views.

You can also use the map function on WUI views that you design yourself. The WUI view editor gives you the option of including a map button on tabular or detailed views for definitional objects and to create and edit customized maps.

How to interpret a map in full-function BAS

Maps in full-function BAS can be quite complex and require some further explanation.

In full function BAS you can specify a target scope in three places:
  • On the resource assignment (RASGNDEF)
  • On the link between the resource assignment and the resource description (RASINDSC)
  • On the resource description itself (RESDESC).
If you specify a target scope on all 3, the resource assignment takes priority, followed by the link between the resource assignment and the resource description, and lastly the target scope on the resource description.
If you select a resource assignment in the Resource assignment definitions view and carry out a map left operation, this is portrayed as follow:
Table 1. Result of a map left operation on a resource assignment showing the resource description's scope overidden by the resource assignment
CICS system or system group Scope   Scope type   Resource description   Resource assignment in resource description   Resource assignment
SYSTEM1 TARGET __ ASIS __ MYDESC __ <-----> __ ASSIGN1
SYSTEM2 TARGET __ FILEDEF __ _________ __ __________ __  

This result indicates that FILEDEF resources in resource description MYDESC will not be installed in SYSTEM1 because the resource assignment ASSIGN1 has overriden it. It is instead installed into SYSTEM2. You can see that the association with SYSTEM1 is a simple physical relationship because of the <-----> symbol. You can infer that the second line in the diagram is an override because ASSIGN1 is directly associated with SYSTEM2 and no physical relationship exists as indicated by the absence of the <-----> symbol.

Duplication can occur in the system column as follows:
Table 2. Result of a map left operation on a resource assignment showing the resource description's scope not overidden by the resource assignment
CICS system or system group Scope   Scope type     Resource description   Resource assignment in resource description   Resource assignment
SYSTEM1 TARGET __ ASIS __ __ MYDESC __ <-----> __ ASSIGN1
SYSTEM1 TARGET __ FILEDEF __ __ _________ __ ________ __  

This result indicates that either the resource assignment has not overridden the target for the installation, or that the override is the same as MYDESCs target install.

The first example deals with the case in which the override is only on the resource assignment. You can also have an override on the link between the resource assignment and the resource description (RASINDSC). This can be portrayed as follows:
Table 3. Result of a map left operation on a resource assignment showing the scope specified on the RASINDSC overidden by the resource assignment
CICS system or system group Scope   Scope type   Resource description   Resource assignment in resource description   Resource assignment
SYSTEM2 TARGET __ FILEDEF __ ____________ __ <-----> __ ASSIGN1
SYSTEM1 TARGET __ ASIS __ MYDESC __   __  
SYSTEM3 TARGET __ FILEDEF   ____________ __ ____________ __  
In this case, the <-----> symbol shows that an override occurs in the RASINDSC resource. However, the last line, which indicates where the installation will take place, shows the resource assignment ASSIGN1 pointing to SYSTEM3. This line indicates that the target scope in the resource assignment is overriding the RASINDSC. If the override is removed, the result is as follows:
Table 4. Result of a map left operation on a resource assignment showing the RASINDSC not overidden by the resource assignment
CICS system or system group Scope   Scope type   Resource description   Resource assignment in resource description   Resource assignment
SYSTEM2 TARGET __ FILEDEF __ ____________ __ <-----> __ ASSIGN1
SYSTEM1 TARGET __ ASIS __ MYDESC __      
SYSTEM2 TARGET __ FILEDEF   ____________ __ ____________ __  
This arrangement can also be caused if the scopes in both the RASGNDEF and RASINDSC are the same.