Using ICHEACTN with the DATAMAP=NEW and DATAMAP=OLD operands

Installations can choose between using the old datamap format and the release 1.8 datamap format. The following topics explain the relationship between the DATAMAP keyword and the RELEASE keyword. In addition, this topic explains how to use the ICHEACTN to retrieve and alter data when the ICHEINTY macro has DATAMAP=NEW specified and how to use ICHEACTN when the ICHEINTY macro has DATAMAP=OLD specified.

Using ICHEACTN to retrieve data when ICHEINTY has DATAMAP=NEW

The ICHEACTN macro retrieves data when used with the ICHEINTY macro which has a LOCATE, NEXT or NEXTC operand. With DATAMAP=NEW on the ICHEINTY and RELEASE=1.8 or later on the ICHEACTN, data retrieval and modification are compatible operations. That is, you can do an ICHEINTY LOCATE followed by an ICHEINTY ALTER (with the same ICHEACTN) and the profile ends up with its original data. Or alternatively, by changing the ENTRY name you could copy data from one profile to another. When using ICHEACTN to retrieve data, you must supply a work area on the ICHEINTY macro into which the retrieved data can be placed. The first fullword of the work area must be the length of the work area (including the first fullword itself). The minimum work area is 30 bytes, even if no data is being retrieved.

The format of the user work area is as follows:

Offset (hex)	Length	Description
0	4	Length of entire work area
4	6	RBA return area
A	1	Flags
B	1	Reserved
C	4	Duplicate data set name count
10	8	Reserved
18	4	Length of data returned into work area
1C	variable	Field value return area

Ensure that the storage in the work area from +4 to +1E is initialized to binary zeros. If the area is not initialized, it can be difficult to determine if the information returned by the RACF® manager is present.

If the profile located has a generic name, bit 0 (X'80') of the flag byte at offset (X'0A') is set to on.

An ICHEINTY macro can have several ICHEACTN macros associated with it. For each ICHEACTN macro, the RACF manager returns into the field value return area:

A 4-byte length field. This length field contains the length of the retrieved data for that particular ICHEACTN macro. Note that this 4-byte length field does not contain its own length.
The retrieved data from the RACF profile.
- Simple variable-length fields are not preceded by an additional length byte as in the old format.
- Within a combination field, each field is preceded by its respective four byte length field.
- An alias field (combination field made up of only one field) does not have an extra length field.
- Repeat group count fields are four bytes long, not two.
- When replacing or retrieving an entire repeat group using (GROUP=YES), the repeat group count field does not precede the data.

When multiple ICHEACTNs are used, each returns data immediately following the data (if any) returned by the preceding ICHEACTN.

Note that all the fields are byte-aligned. In addition, if the ICHEACTN contains RELEASE=1.8 or later, the manager places the data length in the fullword at offset 12(X'0C') of the ICHEACTN and places a pointer to the data in the fullword at offset 16(X'10') of the ICHEACTN parameter list if no tests are specified. You must increment these offsets by 4 for each test specified by the ICHEACTN TESTS= parameter.

The use of the TESTS= operand increments these offsets by four bytes for each test specified regardless of whether DATAMAP=NEW or DATAMAP=OLD is specified. The following examples show the format of the returned data (and the values that would be placed in the ICHEACTN if you specify RELEASE=1.8 or later).

Some examples of the different field types that the RACF manager can return in the field value return area are:

If a condition specified by an ICHETEST macro (that is associated with the ICHEACTN macro) was not satisfied or if the specified field was a repeat field that contained no members, or if the action was failed by field level access checking, the field value area will not be returned and the length area will be equal to X'00000000'.
If the field specified is a fixed-length field, a variable-length field, a flag field, or a repeat group count field (GROUP=NO), the return field contains the length of the field followed by the field value.
Note: A flag field is always one byte long. A repeat group count field is always four bytes long if GROUP=NO. An alias field is processed the same way as the simple field of which it is an alias.
If the field specified is a combination field, the return area contains the length of all the fields in the combination, followed by a concatenation of the individual simple fields in the combination. Each simple field is returned as described above in (2).
For example, if the combination contains two simple fields:
If the field specified is a field in a repeat group or a combination field made up of one or more fields in the same repeat group, the results returned depend upon whether
- An ICHETEST macro was associated with the ICHEACTN in order to position to a particular occurrence of the repeat group or
- No ICHETEST macro was associated and all occurrences are implied.
When an ICHETEST is associated, the format of the result is the same as if the field were not in a repeat group. When no ICHETEST is associated, the result is the four-byte length field followed by the concatenation of the values of every occurrence of the specified field in the format shown above. If the specified field is a combination field, the values of the fields in the combination are first concatenated for each occurrence, then these concatenations are concatenated in the order of their occurrence.

If the field is a repeat-group count field, and the ICHEACTN specifies GROUP=YES, then the retrieved data contains all occurrences of the repeat group, in the following format:

Where nnnn is the total length of data returned, mmmm is the length of occurrence 1, and ppp is the length of occurrence 2.

Each occurrence will be formatted as though it were a combination field (see example 3) of all template fields defined for the group. For example, data set profiles have a field called ACLCNT; the fields in the group are USERID, USERACS, and ACSCNT. An ICHEACTN to retrieve ACLCNT, with GROUP=YES, would return the following data if ACLCNT has the value 2:

nnnn (length of data)               DC AL4(54)
mmmm (length of occurrence 1)       DC AL4(23)
Declares for occurrence 1           DC AL4(8)
                                    DC CL8 'userid1'
                                    DC AL4(1)
                                    DC AL1(useracs1)
                                    DC AL4(2)
                                    DC AL2(acscnt1)
pppp (length of occurrence 2)       DC AL4(23)
Declares for occurrence 2           DC AL4(8)
                                    DC CL8'userid2'
                                    DC AL4(1)
                                    DC AL2(useracs2)
                                    DC AL4(2)
                                    DC AL2(acscnt2)

Using ICHEACTN to alter data when the ICHEINTY has DATAMAP=NEW

The ICHEACTN macro alters data when used with the ICHEINTY macro having an ADD, ALTER, ALTERI, or RENAME operand. If the conditions specified by the TESTS keyword on the ICHEACTN macro are met, the field specified in the FIELD operand is assigned the value specified in the FLDATA operand. If the specified field in the RACF profile is in a repeat group, then:

If you specified a test with COND=EQ, the existing occurrence of the repeat group is altered.
If you specified a test with COND=NE, a new occurrence is added to the end of the repeat group.
If you did not specify a test, a new occurrence is added to the beginning of the repeat group.

When replacing data, the FLDATA parameter should describe the size of the data and its address in the same format as shown above for retrieving data. When specifying a combination field, the total size must equal the sum of the individual sizes, including the length fields or the request fails.

The specification of FLDATA=‘COUNT’ causes the specified fields to be treated as a positive integer and increased by one. If the field specified is variable length or has a fixed length greater than four, RACF ignores the specification and does not modify the field value.

If you specify FLDATA=‘DEL’, the specified field has a null value; that is:

For a fixed-length field that is not in a repeat group, the field is set to binary ones.
For a flag field that is not in a repeat group, the field is set to binary zeros.
For variable-length fields that are not in a repeat group, the length of the field is set to zero.
For fields within a repeat group, the entire occurrence is deleted.

If you specify zero as the "address" value, the result is the same as if you had specified FLDATA=‘DEL’, except that for fields in a repeat group, the field in the occurrence is set to a null value (the same as fields not in a repeat group).

If you specify FLDATA=‘DEL’ or FLDATA=‘COUNT’ on an ICHEACTN, the length field of the ICHEACTN is set to -1 or -2. If you also specify RELEASE=1.8 or later, and then uses the ICHEACTN to retrieve data, these new values will be lost. To avoid this, you should not use the same ICHEACTN for both DEL/COUNT and retrieval processing; or you should use the E-Form to re-establish DEL/COUNT after the data retrieval.

Using ICHEACTN to retrieve data when the ICHEINTY has DATAMAP=OLD

The ICHEACTN macro retrieves data when used with the ICHEINTY macro having a LOCATE, NEXT or NEXTC operand. When using ICHEACTN to retrieve data, you must supply a work area on the ICHEINTY macro into which the retrieved data can be placed. The first fullword of the work area must be the length of the work area (including the first fullword itself). The minimum work area is 30 bytes, even if no data is being retrieved.

The format of the user work area is as follows:

Offset (hex)	Length	Description
0	4	Length of entire work area
4	6	RBA return area
A	1	Flags
B	1	Reserved
C	4	Duplicate data set name count
10	8	Reserved
18	4	Length of data returned into work area
1C	variable	Field value return area

If the profile located has a generic name, bit 0 (X'80') of the flag byte at offset (X'0A') is on. This flag bit is useful when performing NEXT or NEXTC operations to process many profiles.

An ICHEINTY macro can have several ICHEACTN macros associated with it. For each ICHEACTN macro, the RACF manager returns into the field value return area:

A 2-byte length field. This length field contains the length of the retrieved data for that particular ICHEACTN macro. Note that this 2-byte length field does not contain its own length.
The retrieved data from the RACF profile.

Note that all the fields are byte-aligned. In addition, if the ICHEACTN contains RELEASE=1.8 or later, the manager will place the data length in the fullword at offset 12(X'0C') of the ICHEACTN, and will place a pointer to the data in the fullword at offset 16(X'10') of the ICHEACTN parameter list if no tests are specified. You must increment these offsets by 4 for each test specified by the ICHEACTN TESTS= parameter.

For example, with two tests, the length is returned at X'14' and the address is returned at X'18'. The addresses specified in TESTS= are placed before the FLDATA entries within the parameter list. Therefore, for each address noted within TESTS=, the FLDATA entries are displaced by four bytes. The use of the TESTS= operand increments these offsets by four bytes for each test specified regardless of whether DATAMAP=NEW or DATAMAP=OLD is specified.

The following examples show the format of the returned data (and the values that would be placed in the ICHEACTN if you specify RELEASE=1.8 or later).

Some examples of the different field types that the RACF manager can return in the field value return area are:

If a condition specified by an ICHETEST macro (that is associated with the ICHEACTN macro) was not satisfied or if the specified field was a repeat field that contained no members, the field value area will not be returned and the length area will be equal to X'0000'.
If the field specified is a fixed-length field, the return field contains the length of the field followed by the field value.
If the field specified is a flag field, the return field contains the length of the field (X'0001') followed by a 1-byte value.
If the field specified is a variable-length field, the return field contains the length of the field followed by a 1-byte length field (that does not include its own length) followed by the field value.
If the field specified is a combination field, the return area contains the length of all the fields in the combination, followed by a concatenation of values of each of the individual fields in the combination. If a field in the combination is in a repeat group, all the fields in the combination must be in the same repeat group. (Example 6 shows how the RACF manager returns combinations containing fields of a repeat group.)
If the field specified is a field in a repeat group or a combination field made up of one or more fields in the same repeat group, the results returned depend on whether (1) an ICHETEST macro was associated with the ICHEACTN in order to position to a particular occurrence of the repeat group or (2) no ICHETEST macro was associated and all occurrences are implied.
When an ICHETEST is associated, the format of the result is the same as if the field were not in a repeat group. When no ICHETEST is associated, the result is the two-byte length field followed by the concatenation of the values of every occurrence of the specified field. If the specified field is a combination field, the values of the fields in the combination are first concatenated for each occurrence, then these concatenations are concatenated in the order of their occurrence.

Using ICHEACTN to alter data when ICHEINTY has DATAMAP=OLD

If you specified a test with COND=EQ, the existing occurrence of the repeat group is altered.
If you specified a test with COND=NE, a new occurrence is added to the end of the repeat group.
If you did not specify a test, a new occurrence is added to the beginning of the repeat group.

RACF uses the length specified as a subfield of the FLDATA keyword only when you specify GROUP=YES. For fixed-length fields, the data length is the field length in the template. For variable-length fields, the data length is the first data byte (it does not include its own length). RACF handles combination fields as a succession of fields, either fixed or variable length. If the combination field contains some but not all of the fields in a repeat group, the fields not included are set to null values.

The specification of FLDATA=‘COUNT’ causes the specified field to be treated as a positive integer and increased by one. If the field specified is variable length or has a fixed length greater than four, RACF ignores the specification and does not modify the field value.

If you specify FLDATA=‘DEL’, the specified field is given a null value; that is:

For a fixed-length field that is not in a repeat group, the field is set to binary ones.
For a flag field that is not in a repeat group, the field is set to binary zeros.
For variable-length fields that are not in a repeat group, the length of the field is set to zero.
For fields within a repeat group, the entire occurrence is deleted.