Building a Control-D Recipient Tree

This chapter includes the following topics:

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

Copy
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

Paragraph

Description

USER

Instructions to construct the user name.

PARENT

(Optional) Instructions to construct the parent name.

ADDRESS

(Optional) Instructions to construct the address text.

SYNONYM

(Optional) Instructions to construct synonyms. Can be used more than once to construct more than one synonym for each user.

AUTHORIZE

(Optional) Instructions to construct the authorized users.

DESC

(Optional) Instructions to construct the description text.

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

Paragraph

Description

POS

Starting character position of the string in the input report. A value of 0 (zero) indicates that the default value is used. Data from the report is not used for this parameter.

The POS value is relative to the first print column of the report (that is, for the first column of the report, POS is set to 1) and does not include print control characters or variable record length values.

DEFAULT

(Optional) The default value. Any position in the field of length LEN from the report that is blank is replaced by the corresponding character from parameter DEFAULT.

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

# Characters

Paragraph Type

8

USER

8

PARENT

52

ADDRESS

20

SYNONYM

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

Parameter

Description

PLEVEL

Level at which the parent is located.

TRANSLATE

(Optional) DD name referencing a file containing the USER/PARENT correspondence.

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.

  • USER=ABC*D matches users ABC123D, ABC12D, and ABCXD.

  • USER=ABC?D only matches user ABCXD from the above set.

TREE Construction Example

Suppose that the SYSIN file contains the following statements:

Figure 2 TREE Construction Example

Copy
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.