Building a Control-D Recipient Tree

This chapter includes the following topics:

• Overview

• Defining the Levels

• Additional Considerations for the PARENT Paragraph

• TREE Construction Example

Overview

Use the CTDBLDTR utility to create or modify the Control-D Recipient Tree. This utility uses input from two sources: a report (referenced by DD statement REPORT), and a set of instructions (referenced by DD statement SYSIN) specifying how the data in the report is used to create users in the Recipient Tree.

This utility produces a list (referenced by DD statement SYSPRINT) summarizing the structure (input supplied by the user in SYSIN), and the Recipient Tree (referenced by DD statement TREE). TREE is a member of a partitioned dataset. If TREE is an empty member, the utility creates the Recipient Tree. If TREE contains an existing Recipient Tree, the utility modifies it.

The utility scans each line of the REPORT input and processes it according to the specifications included in the SYSIN data.

For sample JCL programs to execute utility CTDBLDTR, see the CTDBLDDC and CTDBLDJB members in the IOA SAMPLE library.

Defining the Levels

The instruction syntax for building the Recipient Tree is as follows:

Figure 1 Instruction Syntax for Building the Recipient Tree

LEVEL=xxUSER -
POS=n
LENGTH=n
{    DEFAULT=ccc }
{       POS=n
LENGTH=n
{    DEFAULT=ccc } }
.
.
.
{       POS=n
LENGTH=n
{    DEFAULT=ccc } }
{ PARENT -
PLEVEL=xx
POS=n
LENGTH=n
{    DEFAULT=ccc }
{    TRANSLATE=tabledd } }
{ ADDRESS -
POS=n
LENGTH=n
{    DEFAULT=ccc } }
{ SYNONYM -
POS=n
LENGTH=n
{    DEFAULT=ccc } }
{ SYNONYM -
POS=n
LENGTH=n
{    DEFAULT=ccc } }
END

Each LEVEL command can contain four types of paragraphs:

Table 12 LEVEL Command Paragraphs

Parameters define how to process the paragraph. These parameters are repeated for the same paragraph if the data to be constructed consists of data contained in more than one string in the report line.

The use of these parameters is as follows:

Table 13 LEVEL Command Parameters

The combined total length of the data constructed from all the repetitions of the parameters, for each paragraph, must not exceed the number of characters shown in the table below:

Table 14 Maximum Number of Characters for Paragraph Types

The utility constructs the users based on these definitions and searches the Recipient Tree to see if the constructed user is already defined. If the user is not found, the utility adds the user. If the user is found, the utility updates the Recipient Tree. This utility is especially useful if the only changes required are the addition of synonyms.

Additional Considerations for the PARENT Paragraph

The PARENT paragraph has two additional parameters:

Table 15 PARENT Paragraph Parameters

If the parent of a user cannot be identified from the data on the report line, but can be determined from the user name, a file containing a table relating parent names to user names is supplied.

Each line in the external table is in the format USER=usermask PARENT=parent

In the usermask field, masking characters have the following meaning:

• * (asterisk): Matches any number of consecutive characters.

• ? (question mark): Matches any one character.

TREE Construction Example

Suppose that the SYSIN file contains the following statements:

Figure 2 TREE Construction Example

LEVEL=20USER -
POS=0
LENGTH=1
DEFAULT=L
POS=10
LENGTH=2
DEFAULT=03
PARENT -
PLEVEL=10
POS=0
LENGTH=6
DEFAULT=CDTREE
LEVEL=30
PARENT -
PLEVEL=20
POS=0
DEFAULT=L
LENGTH=1
POS=10
LENGTH=2
TRANSLATE=TABLE1
USER -
POS=0
LENGTH=1
DEFAULT=L
POS=1
LENGTH=4
DEFAULT=CKJ
SYNONYM -
POS=0
LENGTH=4
DEFAULT=USER
POS=1
LENGTH=4
SYNONYM -
POS=0
LENGTH=5
DEFAULT=SYN1-
POS=1
LENGTH=4

The Recipient Tree is constructed as follows:

For each line in REPORT file:

1. For a user at level 20 with the name Lxy, where xy are the contents of columns 10 and 11 in the report line:

   • If column 10 is blank, the name is ‘L0y’.

   • If column 11 is blank, the name is ‘Lx3’.

   • If both are blank, the name is ‘L03’.

2. The parent of this user is at level 10 with the name CDTREE.

3. For a user at level 30 with the name Labcd, where abcd are the contents of columns 4 through 7 in the report line:

   Default CKJ is used in a manner similar to default 03 in item 1 above.

4. An attempt is made to determine a level 20 parent from the value ‘L’ plus the contents of columns 10 and 11. If this does not succeed, then the file referenced by DDNAME TABLE1 is scanned line by line until a match is found for the user name and the parent name are taken from the file.

   Two synonyms are created: ‘USERabcd’ and ‘SYN1-abcd’, where abcd represents the contents of columns 1 through 4 in the report line.