Examples of ICHEINTY, ICHETEST, and ICHEACTN macro usage

The following examples illustrate some of the functions provided by the ICHEINTY, ICHETEST, and ICHEACTN macros:

Example 1. Determining if a user is defined to RACF®:

*        .
*        .
*        .
         LA    15,WEND-W     LENGTH OF WORK AREA.
         ST    15,W          INITIALIZE WORK AREA.
         XC    WR,WR         CLEAR RESERVED AREA.
         ICHEINTY LOCATE,TYPE='USR',ENTRY=USR1,WKAREA=W
         LTR   15,15         R15=0 IF USER DEFINED TO
                             RACF
         BNZ   NOTDEFD
*        .
*        .
*        .
*    DATA AREAS
USR1     DS    AL1           LENGTH OF USERID (1 TO 8)
         DS    CL8           USERID
W        DS    0F
         DS    F             LENGTH OF WORK AREA.
WR       DS    CL24          RESERVED.
         DS    F
WEND     EQU   *             END OF WORK AREA.

The ICHEINTY macro identifies the user profile to be located. A return code of 0 (X'00') in register 15 indicates that the user is defined to RACF. A return code of 12 (X'0C') indicates that the user is not defined. Note that this ICHEINTY macro contains a work area. By also coding an ICHEACTN macro in this example, you can retrieve current field values from this user profile into the work area.

Example 2. Adding a user ID to a data set access list:

*        .
*        .
*        .
         ICHEINTY ALTER,TYPE='DS',ENTRY=DSN1,            *
               ACTIONS=AACL
         LTR   15,15             0 RETURNED IF DS IS RACF
                                 DEFINED
         BNZ   DSNOTDEF          DS NOT RACF DEFINED OR
                                 ERROR
         CLI   TUSERID+1,X'00'   WAS USER ALREADY IN LIST
         BNZ   INLIST            YES.  USER WAS IN LIST
                                 ALREADY
*        .
*        .
*        .
*     DATA AREA
AACL     ICHEACTN FIELD=ACL,FLDATA=(11,ACL),             *
               TESTS=TUSERID,MF=L
TUSERID  ICHETEST FIELD=USERID,FLDATA=(8,USER),COND=NE,  *
               MF=L
DSN1     DS    AL1               DATA SET NAME LENGTH
                                 (1 TO 44)
         DS    CL44              DATA SET NAME
ACL      DS    0CL11             ACCESS LIST ENTRY
USER     DS    CL8               USERID TO BE ADDED
USERACS  DS    XL1               ACCESS TO BE GIVEN:
*                                X'80' FOR ALTER
*                                X'40' FOR CONTROL
*                                X'20' FOR UPDATE
*                                X'10' FOR READ
*                                X'01' FOR NONE
ACSCNT   DC    XL2'0000'         ZERO ACCESS COUNT

The ICHEINTY macro identifies the data set profile whose access list is to be updated. It also points to an ICHEACTN macro that describes how the profile is to be updated. In this example, RACF adds a user ID to the access list.

The ICHEACTN macro, in turn, points to an ICHETEST macro that tests for certain conditions before the profile can be updated. In this example, ICHETEST tests to determine if the specified user ID already exists in the access list. (The second byte of the test block at TUSERID is 0 if the user ID is not in the access list.) If the user ID does not exist, RACF adds the user ID (with the specified access authority) to the access list and updates the data set profile. If the user ID already exists, no profile update occurs.

Example 3. Changing the access authority of a user in a data set access list:

*        .
*        .
*        .
         ICHEINTY ALTER,TYPE='DS',ENTRY=DSN1,            *
               ACTIONS=AUSRACS
         LTR   15,15             0 RETURNED IF DS IS RACF
                                 DEFINED
         BNZ   DSNOTDEF          DS NOT RACF DEFINED OR
                                 ERROR
         CLI   TUSERID+1,X'00'   WAS USER IN LIST
         BNZ   NOTINLST          NO.  USER WAS NOT IN
                                 LIST
*        .
*        .
*        .
*     DATA AREA
AUSRACS  ICHEACTN FIELD=USERACS,FLDATA=(1,USERACS),      *
               TESTS=TUSERID,MF=L
TUSERID  ICHETEST FIELD=USERID,FLDATA=(8,USER),COND=EQ,  *
               MF=L
DSN1     DS    AL1               DATA SET NAME LENGTH
                                 (1 TO 44)
         DS    CL44              DATA SET NAME
UACC     DS    XL1               ACCESS TO BE GIVEN:
*                                X'80' FOR ALTER
*                                X'40' FOR CONTROL
                                 X'20' FOR UPDATE
                                 X'10' FOR READ
                                 X'01' FOR NONE

This example is similar to the previous example. However, if the user ID exists in the data set access list, RACF changes that user's access authority to the value specified in USERACS and updates the data set profile. If the user ID does not exist, no profile update occurs.

Note that you can use this example to delete a user ID from the data set access list by changing the ICHEACTN macro to read:

AUSRACS  ICHEACTN FIELD=USERID,FLDATA='DEL',             *
               TEST=TUSERID,MF=L

Example 4. Retrieving owner names of all data set profiles:

The following example program shows an ICHEINTY coded to retrieve the owner names of all data set profiles in the RACF database.

EXAMPLE  CSECT
*
*        entry linkage
*
         STM   14,12,12(13)              push caller registers
         BALR  12,0                      establish ...
         USING *,12                      ... addressability
         GETMAIN R,LV=DYNLEN             get dynamic storage
         LR    11,1                      move getmained address to R11
         USING DYNAREA,11                addressability to DSECT
         ST    13,SAVEAREA+4             save caller save area address
         LA    15,SAVEAREA               get address of own save area
         ST    15,8(13)                  store in caller save area
         LR    13,15                     get address of own save area
*
*        initialize variables in dynamic storage area
*
         MVC   ENTBLEN,H44               set buffer length to 44
         MVC   ENTNLEN,H1                set entity length to 1
         XC    ENTNAME,ENTNAME           clear entity name area
         MVC   RETALEN,F40               set return area length
*
*        copy static ICHEINTY and ICHEACTN to dynamic GETMAINed areas
*
         MVC   DYNICH(ICHLEN),STATICH
         MVC   DYNACT(ACTLEN),STATACT
         ICHEINTY RELEASE=1.9,ACTIONS=(DYNACT),WKAREA=RETAREA,         *
               OPTIONS=(FLDEF,NOEXEC),GENERIC=NO,MF=(E,DYNICH)
*
*        loop to retrieve all data set profiles
*          for each high level qualifier, generic profiles are
*            retrieved first
*
LOOP     EQU   *                         start of loop
         XC    RETDATA,RETDATA           clear ICHEINTY return data
         ICHEINTY NEXTC,ENTRYX=ENTBUFF,RELEASE=1.9,MF=(E,DYNICH)
         LTR   15,15                     check return code
         BNZ   DONE                      exit on non zero return code
*               .
*               .
*        process data set profiles
*               .
*               .
         TM    RETFLAGS,X'80'            check generic bit
         BO    GENERIC                   branch if generic bit is on
         ICHEINTY OPTIONS=(NOEXEC),GENERIC=NO,MF=(E,DYNICH)
         B     LOOP                      process next profile
*
GENERIC  EQU   *                         profile name is generic
         ICHEINTY OPTIONS=(NOEXEC),GENERIC=UNCOND,MF=(E,DYNICH)
         B     LOOP                      process next profile
*
*        return to caller
*

DONE     EQU   *                         return to caller
         L     13,SAVEAREA+4             caller's save area address
         FREEMAIN R,LV=DYNLEN,A=(11)     free dynamic storage
         LM    14,12,12(13)              pop registers
         SLR   15,15                     clear return code
         BR    14                        return to caller
*
*        static ICHEACTN and ICHEINTY areas
*
STATACT  ICHEACTN FIELD=OWNER
ACTLEN   EQU   *-STATACT                 length of ICHEACTN
*
STATICH  ICHEINTY NEXTC,TYPE='DS',ENTRYX=*-*,RELEASE=1.9,DATAMAP=NEW,  *
               ACTIONS=(STATACT),WKAREA=*-*,MF=L
ICHLEN   EQU   *-STATICH                 length of ICHEINTY
*
*        constants
*
H1       DC    H'1'
H44      DC    H'44'
F40      DC    F'40'
*
*        dynamic area
*
DYNAREA  DSECT
*
SAVEAREA DC    18F'0'
DYNICH   DS    17F                       dynamic ICHEINTY area
DYNACT   DS    6F                        dynamic ICHEACTN area
*
*        ENTITYX structure
*
ENTBUFF  DS    0CL48
ENTBLEN  DS    H
ENTNLEN  DS    H
ENTNAME  DS    CL44
*
*        return work area
*
RETAREA  DS    0CL40
RETALEN  DS    F                         return area length
RETDATA  DS    0CL36
RETRBA   DS    CL6                       RBA return area
RETFLAGS DS    CL1                       flags
RETRES1  DS    CL1                       reserved
RETDDSC  DS    F                         duplicate data set name count
RETRES2  DS    CL8                       reserved
RETDLEN  DS    F                         returned data length
RETOWNLN DS    F                         returned owner name length
RETOWNER DS    CL8                       returned owner name
*
DYNLEN   EQU   *-DYNAREA                 dynamic area length
*
         END

Example 5. Updating the installation fields:

The RACF template defines a repeat group of fields for installation use. There are four of these fields:

USRCNT: Contains the number of repeat members in the group. A repeat member is one USRNM field, one USRDATA field, and one USRFLAG field.
USRNM: Describes the contents of the USRDATA field.
USRDATA: Contains any information that you choose.
USRFLAG: Is a flag associated with USRNM.

The following example shows how the installation fields are used:

USRCNT = 2
             USRNM   ACCTNMBR
             USRDATA K83-1234/DQ3
             USRFLG  00

             USRNM   ADDRESS
             USRDATA RFD 4, Box 7711, Phoenicia, NY
             USRFLG  00

The following example shows how to add or update a repeat group member. This code will first delete an existing occurrence, based on the name in USRNM, and then add a new occurrence with the wanted new (or updated) data. The code is assumed to be preceded by code that initializes the UDATANM, UDATAL1 and UDATAV fields.

In the part of the example not shown, the ACTN3 and ACTN4 macros are addressed by an ICHEINTY-ALTER macro. The ACTN3 and ACTN4 macros must be specified in the ICHEINTY-ACTIONS keyword in the order ACTN3,ACTN4.

        ICHEACTN MF=(E,ACTN3),TESTS=TEST3
        ICHETEST MF=(E,TEST3),FLDATA=(,UDATANM)
        ICHEACTN MF=(E,ACTN4),FLDATA=((Rx),UDATA),TESTS=TEST4
        ICHETEST MF=(E,TEST4),FLDATA=(,UDATANM)
           .
           .
           .
        --- Invoke ICHEINTY ---
           .
           .
           .
ACTN3   ICHEACTN FIELD=USRNM,FLDATA='DEL',TESTS=*-*
TEST3   ICHETEST FIELD=USRNM,FLDATA=(8,*-*)                 COND=EQ is default.
ACTN4   ICHEACTN FIELD=USERDATA,FLDATA=(*-*,*-*),TESTS=*-*

TEST4   ICHETEST FIELD=USRNM,FLDATA=(8,*-*),COND=NE

UDATA   DS    0C            Start of USERDATA area.
UDATANM DS    CL8           Contents of USRNM field.
UDATAL1 DS    AL1           Length of USRDATA field.
UDATAV  DS    CL--          Contents of USRDATA field.
*
* The USRFLG field will be at an offset of UDATAL1+1 from
*  the beginning of the UDATAV field.
*