Package Ship Facility › How to Enable Package Ship › Mapping Rules

Mapping Rules

When you create each destination, you define the staging data sets or USS directories that are built for each ship request to that destination. You must also create one or more mapping rules for each destination. A mapping rule maps production data sets or USS directories at the host to corresponding production data sets or USS directories at the remote site as follows:

• A data set mapping rule is a relationship between a host data set name or mask and a remote data set name or mask. Both the host and remote data set name or mask can be 1 – 44 characters in length.
• A USS mapping rule is a relationship between a host path name or mask and a remote path name or mask. Both the host and remote path name or mask can be up to 768 characters in length.

When creating mapping rules, consider the following factors:

• In order to match a mapping rule, CA Endevor SCM first checks that the number of qualifiers or sub-directories match. This means that the host data set name in the mapping rule must have the same number of qualifiers (separated by '.') as the input production names. For USS path names, the host path name must have the same number of sub-directories (separated by '/')as the input production path name.
• We recommend that the host names and their corresponding remote names in the mapping rule have the same number of qualifiers. This format makes the rules easier to understand and administer.

  Note: Matching begins with the highest to the lowest level qualifier. Therefore, a data set named testap.program.loadlib.clone would map to testap.program.*.* if the mapping rule options were as follows:

  testap.program.*.*
  Testap.*.loadlib.clone
  

  • For example, the following host data set names should be mapped to the following remote data set names:

• For example, the following host path name masks should be mapped to the following remote names:

• The remote data set name fields in the mapping rules can have any number of qualifiers. If the number of qualifiers is not the same, then generally both data set names align to the right before building a new data set name.
  • For example, assume this mapping rule where the remote data set has more qualifiers than the host:

This mapping rule would result in the following remote data set being built for the following host:

• For example, assume this mapping rule, where the host data set has more qualifiers than the remote:

This mapping rule would result in the following remote data set being built for the following host:

• If the target has more nodes than the host, and the host and target start with the same explicitly defined node, but do not end with the same explicitly defined node, then the data set names align to the left.
  • For example, assume this mapping rule, where the remote data set has more qualifiers than the host:

This mapping rule would result in the following remote data set being built for the following host:

• For example, assume this mapping rule, where the remote USS path has more qualifiers than the host:

This mapping rule would result in the following remote data set being built for the following host:

• An exception to the alignment rules occurs when both the host mask and the remote mask contain no wildcards. In this case, the remote mask becomes the remote data set name or path.
• When executing a shipment request, each input data set is compared to its list of data set mapping rules until the most specific match is found. For example, the input data set TESTAP.PROGRAM.LOADLIB matches the following three host masks. The first mask, TESTAP.*.LOADLIB, is the most specific and is the one that would be used.

• If the remote mask is null, data sets matching the host mask are excluded from the package shipment. This behavior is useful, for example, when only load modules are shipped. This behavior enables you to set up rules to prevent the shipment of source, listings, object modules, and so on.
• If no matching rule exists, then the remote data set defaults to the same name as the input data set when executing a shipment request. If your site does not require any name changes, then all you need is a single dummy mapping rule, which causes every data set to map to itself. A dummy mapping rule is a mapping rule that does not include a definition for the remote data set.

  Important: If you are using a dummy mapping rule with the local shipment method, the target and source file would be the same physical data set or path. This default behavior can cause results that had not been considered during the initial planning. For example, if a new file with a USS path name has one extra node than the input masks, the data set would map to itself.

Note: The Shipment Activity Report created at run time lists the remote data set name for each host data set, with the mapping rule that was used to generate it. A DSN cross reference data set is also shipped to the remote site.