ICHNCONV SELECT

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.

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

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
RACGPID = RACGRP1

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 an eight-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.

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 may 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 respectively 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 may have are:

X'0100' - RACHECK
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)
X'0602' - LISTDSD DATASET
X'0603' - LISTDSD ID or PREFIX
X'0701' - PERMIT TO-resource
X'0702' - PERMIT FROM-resource
X'0801' - SEARCH prelocate (see note)
X'0802' - SEARCH postlocate (see note)
X'0900' - ICHUT100
X'0D00' - RACXTRT

Note: Prelocate means before a profile is located; postlocate means after a profile is located but before it is displayed.
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.
RACGPID
The caller's current connect group.
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’