$RCUDSN macro

Member $RCUDSN is supplied in the product sample library to assist in the creation of the Data Set Name user exit routine.

While use of this macro is not required, BMC highly recommends that you use it because it follows BMC’s interface guidelines and restrictions. It also provides a powerful and flexible method of generating user data set names.

To create a CAP$DSN or RCU$DSN module using the $RCUDSN macro, specify an assembly language program using the program skeleton shown in the following figure.

The $RCUDSN macro consists of positional fixed and variable format parameters.

Fixed format

The fixed format has one required positional keyword parameter which can be one of four fixed values.

You can use one or more $RCUDSN statements with the fixed format. Only one fixed value is allowed per $RCUDSN statement. The four fixed values are ENTRY, DSECT, DOC, and EXIT. These values are defined as follows:

• ENTRY generates standard entry logic for the module, along with standard symbolic register name definitions (such as R0, R1, and so forth).Optional. If you omit this value and it is needed, the standard entry logic generates automatically.
• DSECT generates a DSECT defining the standard parameter area passed using register 0 from the Change Accumulation utility. Optional. If you omit this value and it is needed, a DSECT definition generates automatically.
• DOC generates a standard block of comments describing the use of the Data Set Name user exit routine. Optional.
• EXIT generates standard exit logic for the module, including appropriate error handling. Required. Specify the EXIT statement as the standard technique for returning to the Change Accumulation utility.

Variable format

You can use one or more $RCUDSN statements with the variable format to control the user data set name generated.

Include other assembly language statements as needed. The example in the following figure shows a $RCUDSN statement using the variable format.

The variable format, as represented by 'prototype' in above figure, consists of a string of characters which define a data set name mask. This string must be enclosed in apostrophes. Each character in the data set name mask, except for certain special characters, is placed into the corresponding position in the generated data set name. In the following example, OFFSIT will occupy its current position in the generated data set name:

Use these keyword parameters to provide substitution information:

• FIELDS
• SUB

Use these keyword parameters to define the prototype selection:

• GDG
• STKCA
• STKIC
• TYPE

Dynamic substitution

The FIELDS and SUB keyword parameters supply dynamic substitution information as described below.

The prototype data set name mask is scanned from left to right to locate dynamic substitution fields. Each group of consecutive occurrences of the substitution character defines a variable field. The length of the variable field is determined by the number of occurrences of the substitution character. The substitution fields in the prototype string are matched one-to-one with the addresses specified in the FIELDS keyword parameter. See RCUDSN-macro.

The FIELDS and SUB keyword parameters are defined as follows:

• The FIELDS keyword parameter defines a list of RX-type addresses. The entire list is enclosed within parentheses, and the items in the list are separated by commas. Each entry in the list identifies the starting address of a character string. These strings are used for dynamic substitution of variable text into the prototype.

  In the following example, the FIELDS keyword parameter will cause the data at symbolic address PREFIX to replace the first set of pound sign substitution characters when the data set name is generated (up to 17 bytes); the data at symbolic address CAGRP will replace the second set of substitution characters when the data set name is generated (up to 8 bytes):

  $RCUDSN '#################..########',
        FIELDS=(PREFIX,CAGRP)

• The SUB keyword parameter defines a single character char which functions as a dynamic substitution character within the mask. The default substitution character is the pound sign (#).

  Important

  Do not use the vertical broken bar sign (¦)

  In the following example, the pound signs will be replaced by characters determined by the FIELDS keyword parameter when the data set name is generated:

  $RCUDSN '############..####..####..OFFSIT..##'

The following figure shows Symbolic addresses referenced by FIELDS keyword parameter:

Use a single period to separate two adjacent substitution fields, such as ####.####. To include a period in the generated name between adjacent substitution fields, use two consecutive periods, such as ####..####. Other period characters not used to separate adjacent substitution fields are included in the generated data set name as a literal character.

After dynamic substitution occurs, all leading and embedded blanks are eliminated from the generated string.

Prototype format selection

GDG, STKCA, STKIC, and TYPE macro statement parameters determine prototype format selection (which of the multiple $RCUDSN statements to use to generate the user data set name).

Although you can specify multiple prototype statements with a variable format, only one of these statements is actually used to generate the user data set name. The first statement that matches the conditions specified by its parameters is the statement selected to generate the user data set name.

The GDG, STKCA, STKIC, and TYPE macro statement parameter descriptions are as follows:

• GDG selects a prototype based on whether the output change accumulation or incremental image copy data sets will be generated as a GDG. Specify GDG=Y to select a prototype for generation data sets and GDG=N for ordinary data sets. Omit GDG to select both types.
• STKCA selects a prototype based on stacking or nonstacking of output change accumulation data sets. Specify STKCA=Y to select the prototype for stacked change accumulation data sets; specify STKCA=N to select the prototype for nonstacked change accumulation data sets. Omit STKCA to select the same prototype for both stacked and nonstacked change accumulation data sets.
• STKIC selects a prototype based on stacking or nonstacking of output incremental image copies. Specify STKIC=Y to select the prototype for stacked incremental image copies; specify STKIC=N to select the prototype for nonstacked incremental image copies. Omit the STKIC keyword parameter to select the same prototype for both stacked and nonstacked incremental image copies.
• TYPE selects a prototype based on the type of file produced. For the Change Accumulation utility, valid types are CA, CA1, through CA10 for change accumulation and IC, IC1, through IC10 for incremental image copies. If you omit the TYPE keyword, the prototype is selected for all output data set types.

Examples for $RCUDSN macro

The following are a few examples for the $RCUDSN macro.

In the following figure: the first prototype format is used if the data set name produced is a change accumulation data set and is a member of a GDG.

• The first prototype format is used if the data set name produced is a change accumulation data set and is a member of a GDG.
• The second prototype format is used if the data set produced is a change accumulation data set and is not a member of a GDG.
• If none of the above are true, the Data Set Name user exit returns to the main task with a nonzero return code. The main task will indicate that the copy for which the exit was invoked will be disabled. In this example, the exit will generate data set names for all TYPES of change accumulation data sets (stacked, nonstacked; GDG, non-GDG; and CA, CA1 through CA10).

The following figure shows an example of how both change accumulation and image copy data set names can be generated from a single Data Set Name user exit.

• The first prototype format is used if the data set is a change accumulation and a member of a GDG: GDG=Y.
• The second prototype format is used if the data set is a change accumulation but not a member of a GDG: GDG=N.
• The third prototype format is used if the data set name is an incremental image copy data set, stacking of the output image copies is requested, and the data set is not a member of a GDG: TYPE=IC1, STKIC=Y, GDG=N.
• The fourth prototype format is used if the data set is an incremental image copy data set, stacking of the output image copies is requested, and the data set is a member of a GDG: TYPE=IC1, STKIC=Y, GDG=Y.
• The fifth prototype is used if the data set is an incremental image copy data set and stacking is not requested: TYPE=IC.
• If none of the prototypes are selected, the Data Set Name user exit returns to the main task with a RC=8. The main task indicates that the change accumulation or incremental image copy for which the exit was invoked is disabled.

In the following example, the Data Set Name user exit generates data set names for all types of change accumulation and image copy data sets (stacked, nonstacked; GDG, non-GDG; and copy 1 through copy 10).

The following figure shows an example of an exit routine that handles data set naming for data set group or area data sets.

The example in the following figure shows assembler coding used as part of the $RCUDSN macro. The second prototype includes a user-defined literal string, OFFSIT, in the generated data set name. A field offset reference, TYPE+2, completes the generated data set name.