When writing a naming conventions table, be sure that your output data set names do not match any input data set names. If they match, you might receive unpredictable results. For example, suppose that you have erroneous entries in your naming conventions table that transform the following input data set names to the following output data set names:

When a data set named A.B.#ANY.THING is processed, it is transformed to B#.ANY.THING. If B#.ANY.THING is processed again as an input data set name, it will be transformed again, this time to C#.ANY.THING. You should avoid this type of coding in your naming convention table.

This is important because you cannot predict the input data set names that are passed to the naming convention table. In some cases, the table might receive the input data set name in "external" format, as provided by a user, such as from a LISTDSD DA('hlq.name') command. In other cases, it might receive the input data set name in "internal" format, as previously processed by the naming convention table, such as from an authorization check made during processing of SEARCH or LISTDSD PREFIX(hlq) when RACF has retrieved the data set name from the database.

An ICHNCONV DEFINE macro starts a naming convention and assigns it a name.

The format of the ICHNCONV DEFINE macro is:

[label] ICHNCONV  DEFINE,NAME=convention name

DEFINE

Identifies the start of a naming convention. The ICHNCONV DEFINE must start each naming convention and there must be only one per convention.

NAME=convention name

Specifies a unique name that you can use for the convention.

The convention name must be 1 to 8 characters long and follow the rules for symbols in assembly language.

An ICHNCONV SELECT macro specifies the conditions when the naming convention processes the data set name.

The format of the ICHNCONV SELECT macro is:

[label] ICHNCONV  SELECT,COND=(condition|compound condition)

SELECT

Identifies that this convention has selection criteria.

If the condition on the COND parameter is true, the actions on the ICHNCONV ACTION macros will be processed, and processing will continue as specified on the ICHNCONV END macro. If the condition on the COND parameter is not true, RACF bypasses the ICHNCONV ACTION macros and continues with the next convention in the table.

If an ICHNCONV SELECT macro is not coded, RACF unconditionally processes the actions specified on the ICHNCONV ACTION macros, and continues as specified on the ICHNCONV END macro.

All ICHNCONV SELECT macros for a naming convention must follow the ICHNCONV DEFINE macro and precede any ICHNCONV ACTION macros.

COND=(condition)

Specifies the conditions that have to exist before the naming convention processes the data set name.

The "condition" may be a simple comparison condition of the form:

COND=(variable,operator,operand)

You can also use a "compound condition" formed by linking two or more ICHNCONV SELECT macros with logical AND and OR operators:

COND=(variable,operator,operand,AND)

or

COND=(variable,operator,operand,OR)

If a naming convention contains more than one ICHNCONV SELECT macro, all of the SELECT macros except the last must contain either AND or OR to link it to the following macro. The last (or only) ICHNCONV SELECT cannot have AND or OR specified. RACF evaluates compound conditions in the order specified. AND and OR have equal precedence. Each operation is performed in order, with no “short-circuit” evaluation. The final result of a compound condition will always be:

(...(((conv1 op1 conv2) op2 conv3) op3 conv4)...opn convn+1) ...

where any “op” can be either AND or OR.

variable

Specifies the variables that the convention can reference. Valid variables are:

GQ

Input qualifiers

G

Input qualifier array subscript

UQ

Output qualifiers

U

Output qualifier array subscript

QUAL

Character qualifier

QCT

Initial number of qualifiers

NAMETYPE

Type of data set

EVENT

Event code

VOLUME

Volume serial numbers

V

Volume serial number array subscript

VCT

Number of volumes

OLDVOL

Volume serial of old volume

WKX

Temporary work variable

WKY

Temporary work variable

WKZ

Temporary work variable

WKA

Temporary work variable

WKB

Temporary work variable

WKC

Temporary work variable

RACUID

Caller's user ID

RACGPID

Caller's current connect group

RACUID3

User ID for third-party RACHECK

RACGPID3

Group used for the third-party RACHECK

RACF initializes the variables before the first convention. ICHNCONV passes any changes to a variable to subsequent conventions, but only changes made to the variables UQ, QUAL, and NAMETYPE are passed back to the RACF module that called the naming convention table processing module.

You can reference character and hexadecimal variables by substring; for example, (variable,subscript,substring-start,substring-end). If the variable does not accept subscripts or you omit the subscript, you must code a comma to show that the subscript is omitted. Variables cannot be used to define the extents of substrings. For example, (GQ,2,1,3) refers to the first three characters of the second input qualifier; (EVENT,,2,2) refers to the second byte of the event code.

Example: The definition of the data set BOB.SAMPLE.DATASET on volume 111111, when the naming convention table processing module was called during a TSO session when user RACUSR1 was connected to group RACGRP1, would lead to the following set of initial variables:

(GQ,1) = BOB
(GQ,2) = SAMPLE
(GQ,3) = DATASET
(GQ,4) to (GQ,22) = blank
(UQ,0) = blank
(UQ,1) = BOB
(UQ,2) = SAMPLE
(UQ,3) = DATASET
(UQ,4) to (UQ,22) = blank
QCT = 3
QUAL = BOB
NAMETYPE = UNKNOWN
EVENT = X'0201'
(VOLUME,1) = 111111
VCT = 1
G, U, V = -1
WKX, WKY, WKZ = 0
WKA, WKB, WKC = blank
OLDVOL = blank
RACUID = RACUSR1
RACUID3 = blank
RACGPID = RACGRP1
RACGPID3 = blank

GQ

input qualifiers of the data set name.

G

input qualifier array subscript.

UQ

output qualifiers of the data set name.

U

output qualifier array subscript.

GQ and UQ are arrays containing the qualifiers of the data set name with the high-level qualifier of the name in (GQ,1) and (UQ,1). G and U are halfword variables used to hold subscripts to the GQ and UQ arrays. G and U are initialized to negative one (-1), which is out of the range of valid subscripts.

Initially the input and output qualifiers are identical; but if the contents of the output qualifiers are changed, the new contents are used as the new data set name. Each qualifier is a 44-byte character field padded on the right with blanks. (The field does not include the periods that separate qualifiers.) Initially, (UQ,0) is blank and is reserved for the convention to set as the new high-level qualifier.

If the name produced by the naming conventions table is longer than 44 characters, it is truncated to 44 characters. Thus, the highest possible number of qualifiers (or the highest possible value for the subscripts G and U) is 22.

Naming conventions should ensure that none of the UQ fields contain anything after the 8th position, because RACF follows the MVS™ JCL rules for data set names not enclosed within quotes, and requires that qualifiers be at most 8 characters in length.

If you use GQ or UQ in an ICHNCONV SELECT macro without a subscript, RACF tests the condition for each qualifier in turn until the condition is true. The variables G and U are set to the subscript of the qualifier for which the condition was true, G for the conditions using GQ and U for those involving UQ. If the condition is not true, the subscript variable will be negative one (-1).

For all conditions except NE (not equal), the implied linkage is OR; for the NE condition, the implied linkage is AND. For example,

SELECT COND=(GQ,EQ,‘ABC’)     means

SELECT COND=((GQ,0),EQ,‘ABC’,OR)
SELECT COND=((GQ,1),EQ,‘ABC’,OR) ...

while

SELECT COND=(GQ,NE,‘ABC’)     means

SELECT COND=((GQ,0),NE,‘ABC’,AND)
SELECT COND=((GQ,1),NE,‘ABC’,AND) ...

You can use any numeric variable as a subscript for GQ or UQ. If RACF encounters an out-of-range subscript (for example, -1 or 23), RACF uses blanks for the comparison.

If GQ or UQ is in an ICHNCONV ACTION macro without a subscript, RACF uses the current value of G or U, in that order, as the subscript.

QUAL

An 8-byte character qualifier that RACF uses in authority checking to determine if the data set is the user's data set or a group data set.

QUAL is initially the data set high-level qualifier. If the high-level qualifier is not a user ID or group name, you should set QUAL to a user ID or group name. Setting QUAL, however, is not the same as setting the data set high-level qualifier. QUAL and the high-level qualifier are two separate fields, used for different RACF processing. Therefore, if you change QUAL, you probably want to set (UQ,0) to the same value as QUAL, especially for generic profile names.

QCT

A 2-byte binary field containing the initial number of qualifiers in the data set name.

NAMETYPE

Indicates whether the data set is a user or group data set.

NAMETYPE initially has the value UNKNOWN but a convention action may set the value to be USER or GROUP. The three special constant values UNKNOWN, USER, and GROUP may be used to test and set the value of this field. NAMETYPE is available only when the caller is RACDEF.

If the convention sets the value to USER or GROUP, RACF ensures that an appropriate user or group exists and fails the RACF or ADDSD if not.

EVENT

A 2-byte hexadecimal field containing the event code that is currently passed to the exit routine.

Values that EVENT can have are:

X'0100' - RACHECK (see note 1)
X'0201' - RACDEF DEFINE (RENAME new name)
X'0202' - RACDEF RENAME (OLD name)
X'0203' - RACDEF ADDVOL
X'0204' - RACDEF DELETE
X'0205' - RACDEF CHGVOL
X'0301' - ADDSD SET
X'0302' - ADDSD NOSET
X'0303' - ADDSD MODEL
X'0401' - ALTDSD SET
X'0402' - ALTDSD NOSET
X'0501' - DELDSD SET
X'0502' - DELDSD NOSET
X'0601' - LISTDSD prelocate (see note 2)
X'0602' - LISTDSD DATASET postlocate (see note 2)
X'0603' - LISTDSD ID or PREFIX postlocate (see note 2)
X'0701' - PERMIT TO-resource
X'0702' - PERMIT FROM-resource
X'0801' - SEARCH prelocate (see note 2)
X'0802' - SEARCH postlocate (see note 2)
X'0900' - IRRUT100 postlocate (see note 2)
X'0D00' - RACXTRT

Note:

1. RACHECK may be called by the RACROUTE interface or internally by RACF commands such as LISTDSD and SEARCH. If RACHECK is invoked by the RACROUTE macro, the name passed to naming conventions is in external user-specified format. However, if the command processors call RACHECK, the name may be in either format. Because no indicator of the type of call being made is passed to the naming conventions table, the naming conventions table must determine if the name is in internal format and switch it to external format (or if the name is in external format it must switch it to internal format) for this event code.
2. Prelocate means before a profile is located; these events (as well as all of those without a note) are passed a name in the external, user-specified format.

   Postlocate means after a profile is located but before it is displayed; these events are passed a name in the internal RACF format and the naming conventions processing should include converting it back to the external, user format.

3. Error messages displayed by the command processors may use the RACF internal format of the name so the message may be used to determine the real profile name that RACF attempted to locate.

VOLUME

An array of volume serial numbers for volumes containing the data set. Each volume is a 6-byte character field.

V

A 2-byte variable that contains a subscript to the volume array. V is initialized to -1.

VOLUME is not available for generic data set profiles and is not available from commands if the VOLUME keyword was not specified. An attempt to reference nonexistent volumes (subscript 0 or greater than the number of volumes in the VOLUME array) results in a VOLUME parameter which contains *BLANK as a character string.

If you reference VOLUME in an ICHNCONV SELECT macro without a subscript, RACF tests the condition for each volume in turn until the condition is true. The variable V is set to the subscript of the volume for which the condition was true. If the condition is not true, the subscript variable will be negative one (-1).

For all conditions except NE (not equal), the implied linkage is OR; for the NE condition, the implied linkage is AND. For example,

SELECT COND=(VOLUME,EQ,‘ABC’)     means

SELECT COND=((VOLUME,1),EQ,‘ABC’,OR)
SELECT COND=((VOLUME,2),EQ,‘ABC’,OR) ...

while

SELECT COND=(VOLUME,NE,‘ABC’)     means

SELECT COND=((VOLUME,1),NE,‘ABC’,AND)
SELECT COND=((VOLUME,2),NE,‘ABC’,AND) ...

You may use any numeric variable as a subscript for VOLUME. If VOLUME is in an ICHNCONV ACTION macro without a subscript, RACF uses the current value of V as the subscript.

VCT

A 2-byte binary field containing the number of volumes in the VOLUME array. If volume information is not available, VCT has a value of zero.

OLDVOL

A 6-byte character field containing the volume serial number of the volume that the data set currently resides on. This field is available during a RACDEF ADDVOL or RACDEF CHGVOL request.

WKX, WKY, WKZ

These are 2-byte binary fields that may be used as temporary work variables to save subscripts and other numeric data within and between conventions.

WKA, WKB, WKC

These are 8-byte character fields that may be used as temporary work variables to save qualifiers and other non-numeric data within and between conventions.

RACUID

The caller's user ID.

Note: If naming convention table processing is invoked from an environment where no ACEE is present to define the current user, a default value of * is used for RACUID.

RACGPID

The caller's current connect group.

Note: If naming convention table processing is invoked from an environment where no ACEE is present to define the current user, a default value of * is used for RACGPID.

RACUID3

The user ID used for third-party RACHECK.

RACGPID3

The group used for third-party RACHECK

Note: For RACROUTE REQUEST=AUTH (event code X'0100'):

• RACUID and RACGPID are the user and group used for non-third-party authorization checking. They are acquired from an address space level ACEE, a task level ACEE, or the ACEE= parameter on the RACROUTE REQUEST macro.
• RACUID3 and RACGPID3 are used for third-party authorization checking. They contain blanks for all other event codes. If the REQUEST=AUTH specifies a GROUP and no USERID, RACUID3 is *NONE*. If USERID is specified and no GROUP, RACGPID3 is blanks. RACUID3 and RACGPID3 might not contain a valid user or group. Their values are obtained from the RACROUTE REQUEST=AUTH parameters and have not been validated by RACF at the time the naming convention was called.

operator

Specifies the conditional operator: Valid operators are:

EQ

Equal

GT

Greater than

LT

Less than

GE

Greater than or equal

LE

Less than or equal

NE

Not equal

operand

Specifies a variable, a literal, or one of the following special symbols for use with the NAMETYPE variable:

• USER
• GROUP
• UNKNOWN

The operand used should match the length and type of the variable. If the length does not match, RACF performs padding or truncation in the normal manner. If the type does not match, the results are unpredictable.

If operand is specified as a literal, it can be:

• A character string enclosed in quotes
• A decimal number
• A hexadecimal string in the form X‘string’

An ICHNCONV ACTION macro changes the value of variables. Use these macros to convert the data set name to the standard RACF format. RACF processes the ACTION macros in sequence.

The format of the ICHNCONV ACTION macro is:

 [label] ICHNCONV  ACTION,SET=(variable,value)

ACTION

Identifies a naming convention action. You can code multiple ICHNCONV ACTION macros.

SET=(variable,value)

Changes the qualifiers of a data set name and other variables.

variable

Specifies the variables that the convention can reference and set. See the preceding description of ICHNCONV SELECT for a description of these variables.

The following variables can be set:

• UQ
• QUAL
• G
• U
• V
• NAMETYPE
• WKA, WKB, WKC
• WKX, WKY, WKZ

value

Specifies the value given to the variable. Value can be another variable, a literal, or one of the following special symbols for use with the NAMETYPE variable:

• USER
• GROUP
• UNKNOWN

The value assigned to a variable should match the length and type of the variable. If the length does not match, RACF performs padding or truncation in the normal manner. If the type does not match, the results are unpredictable.

If you specify value as a variable, it can be any of the variables defined in the description of ICHNCONV SELECT.

If value is a literal, it can be:

• A character string enclosed in quotes
• A decimal number
• A hexadecimal string of the form X‘string’

An ICHNCONV END macro terminates the naming convention.

The format of the ICHNCONV END macro is:

 [label] ICHNCONV  END,NEXT=(convention name|'SUCCESS'|'NEXT'|'ERROR')

END

Identifies the end of the naming convention. Each convention must have one ICHNCONV END.

NEXT= (convention name|‘SUCCESS’|‘NEXT’|‘ERROR’)

Specifies where control goes after this convention executes, if the conditions specified in the ICHNCONV SELECT macros have been met or if there are no ICHNCONV SELECT macros in this convention.

If NEXT=convention name, processing continues with the specified convention and skips intervening conventions in the table. The specified convention must not precede the current convention in the table; otherwise, the RACF request fails.

If NEXT=‘NEXT’, processing continues with the next convention in sequence. If NEXT=‘NEXT’ is coded or defaulted to on the last convention in the table, processing is the same as if NEXT=‘SUCCESS’ was coded.

If NEXT=‘SUCCESS’, then the convention processing routine bypasses further convention processing and returns "a successful name processing" return code to the RACF routine that called it. The RACF routine will continue to process normally using the name returned by the convention processing routine.

If NEXT=‘ERROR’, then the convention processing routine bypasses further processing and returns "an invalid data set name" return code to the RACF routine that called it. The RACF routine will terminate processing and fail the request.

An ICHNCONV FINAL macro terminates the naming convention table. (The naming convention table has one ICHNCONV FINAL macro.)

The format of the ICHNCONV FINAL macro is:

 [label] ICHNCONV  FINAL

FINAL

Identifies the end of the naming conventions table. There must be only one ICHNCONV FINAL macro in the table and it must be the last entry in the table.

The following example of a naming convention table illustrates some ways that a table could be coded.