|
You can use the ICHEACTN macro
together with the ICHEINTY macro
to retrieve or alter data in a specified RACF® profile. ICHEACTN builds a parameter list
containing the RACF profile
field name and, optionally, the addresses of ICHETEST macros that
control the data processing.
The ICHEACTN macro must be issued
from a task running in non-cross-memory
mode with no locks held. The issuing task must be authorized (APF-authorized,
in system key 0-7, or running in supervisor state).
The format
of the ICHEACTN macro is: [label] ICHEACTN FIELD=field-name | address
,FLDATA=(length,address) | 'DEL' | 'COUNT'
[,TESTS=(address[,AND,address]…)]
[,RUN=YES | NO]
[,GROUP=YES | NO]
[,ENCRYPT=TEMPLATE | YES | NO]
[,MF=L | (E,address) | I]
[,RELEASE=number | (,CHECK) | (number,CHECK)]
- FIELD=field-name | address
- Specifies the
field-name in the RACF profile
whose value is to be retrieved or updated. The field must be one that
is defined in the RACF database
template.
Do not specify FIELD to be the first field in a database
segment because the user cannot retrieve or update the first field
in a segment. In the database templates, this field has a field ID
of 001, and is usually described in the ‘Field being described’
column as ‘Start of segment fields’.
If you use the LIST form
of the macro, specify the name of the field. The name must be 1 to
8 characters long, and not enclosed in quotes.
If you use the
EXECUTE or INLINE form of the macro, specify the address of the name
of the field to be retrieved or updated. The address can be an A-type
address or register (2 through 12). For EXECUTE and INLINE, you can
also specify the field name as a constant (for example, ‘OWNER’).
Do
not alter a repeat group count field. Doing so causes unpredictable
results and could corrupt the profile.
- FLDATA=
(length,address) | ‘DEL’ | ‘COUNT’
- Updates or deletes data in a specified RACF profile. This operand is valid when used
with the ALTER, ALTERI, ADD, and RENAME operations on the ICHEINTY
macro. It is also valid with LOCATE, NEXT, or NEXTC if RELEASE=1.8
or later. The ICHEACTN macro will have eight bytes reserved to hold
the length and address of the retrieved data. In no case will a LOCATE,
NEXT, or NEXTC return data into a field whose address is given in
the ICHEACTN macro.
When you use ICHEACTN to replace modify data,
the address points to a field that contains the value that is to replace
the data in the specified FIELD of the profile. The address can be
an A-type address or general register ((2) through (12)). The length
specifies the size of the replacement field, and must be an integer
constant or register ((2) through (12)).
When you use ICHEACTN
to retrieve data and you specify RELEASE=1.8 or later, the RACF manager places the size of
the retrieved field in the word at offset 12(X'0C') and the
address of the data in the word at offset 16(X'10') of the
ICHEACTN parameter list if no tests are specified. 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.
‘DEL’ causes
the field named in the FIELD operand to be given a null value or causes
an occurrence of a repeat group to be deleted, or (if GROUP=YES is
coded) deletes all occurrences of a repeat group.
If you are
deleting an encrypted field, you must specify ENCRYPT=NO.
‘COUNT’
causes field-name in the FIELD operand to be treated as a positive
integer and increased by one, unless the high-order bit is on, in
which case, "COUNT" is reset to the value zero.
‘COUNT’ is intended
for integer values only. Nor should ‘COUNT’ be used for repeat group
count fields.
When replacing or adding data, the length and
address are processed as follows: - If DATAMAP=OLD is specified
or defaulted on the ICHEINTY:
If
the address is 0 or omitted, the specified field is given a null value
(a variable-length field is set to a length of 0; a flag field is
set to X'00'; other fixed-length fields are set to all ‘FF’).
If
the length is 0 or omitted, and the address is specified, the result
depends upon whether the specified field is a variable-length field
or a fixed-length field. - For a variable-length field, the
field is given a null value.
The length of the field is set to 0.
- For a fixed-length field
or a flag field, the field is given the
value pointed to by the specified address. The length of the field
is taken from the template.
- If DATAMAP=NEW is
specified on the ICHEINTY:
If the length
is 0 or omitted, or the address is 0 or omitted, the field is given
a null value as indicated above. Otherwise, the field is set from
the data specified, with the length specified. For a fixed-length
field, if the specified length is less than the length given in the
template, the value will be left-adjusted and filled with X'00's
to the template length. If the length is greater than the template
length, the operation will fail. For variable-length fields, the specified
length is used; the first byte of the data is not used as the data
length, but rather is considered to be data.
- TESTS= (address[,[AND],address]...)
- Specifies preliminary
testing that must occur before any data
retrieval or updating takes place. Each address specified must be
the address of a list built by an ICHETEST macro. The address can
be an A-type address or register (2 through 12). Multiple addresses
indicate that all conditions (tests) must be satisfied. If not, RACF suppresses further processing
of the macro. If you omit the logical connector ‘AND’, you must use
a comma to indicate its omission.
Note: If GROUP=YES is also coded
on the ICHEACTN macro, all tests specified by the TESTS parameter
are ignored unless RELEASE=1.8 or later is also specified.
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.
- RUN= YES | NO
- Specifies if a data retrieval or update is to be actually performed.
This operand allows you to code an ACTION operand on the ICHEINTY
macro without the action being performed for this particular execution.
The default is RUN=YES.
- GROUP= YES | NO
- Specifies whether an update for a repeat group is for a single
occurrence of the group or for the entire group, including the repeat
count that contains the number of occurrences. If FIELD=field-name
contains the name of a repeat group count field and GROUP=YES, ICHEACTN
replaces or deletes the entire repeat group, including the count field.
The data format used with GROUP=YES depends on the DATAMAP value on
the ICHEINTY. See Using ICHEACTN to alter data when the ICHEINTY has DATAMAP=NEW and Using ICHEACTN to alter data when ICHEINTY has DATAMAP=OLD for details.
Note: If GROUP=YES is also
coded on the ICHEACTN macro all tests specified by the TESTS parameter
are ignored unless RELEASE=1.8 or later is specified.
- ENCRYPT= TEMPLATE | YES | NO
- Specifies whether
the data specified by FLDATA is to be encoded.
If ENCRYPT=YES, the data is encoded regardless of whether the template
flag associated with the field specifies that it is to be encoded.
If ENCRYPT=NO, RACF does not
encode the data regardless of the template flag value. If ENCRYPT=TEMPLATE,
the template flag determines whether the data is encoded.
- MF= L | (E,address)
| I
- Specifies the form of the macro as either LIST, EXECUTE or INLINE.
The
LIST form reserves and initializes storage. MF=L is the default. If
RELEASE=1.8 or later is specified, the storage must be modifiable,
that is, not within a re-entrant module.
The EXECUTE form modifies
a list defined elsewhere. If you use the EXECUTE form, you must specify
the address of the list to be modified. The address can be an A-type
address or register (2 through 12).
The INLINE form is similar
to a STANDARD form, except that it generates code to branch around
the parameter list. In the MF=I form, the label names the first location
of the parameter list, not the preceding instruction.
- RELEASE=number
- RELEASE=(,CHECK)
- RELEASE=(number,CHECK)
- Specifies
the release number. The release numbers you can specify
with the ICHEACTN macro are 7790, 7780, 7770,
7760, 7750, 7740, 7730, 7720, 7709, 7708, 7707, 7706, 7705, 7703,
2608, 2.6, 2.4, 2.3, 2.2, 2.1, 1.9.2, 1.9, 1.8.1, 1.8, or 1.7.
When you specify 1.8 or
later, the RACF manager returns
data using the 1.8 user work area format (documented in the topic Using ICHEACTN to retrieve data when ICHEINTY has DATAMAP=NEW). In effect, DATAMAP defaults to DATAMAP=NEW,
if you specify RELEASE=1.8 or later and omit DATAMAP.
If you
specify RELEASE=1.7 or allow the release parameter to default to 1.7,
the RACF manager returns data
using the 1.7 user work area format. In this case, DATAMAP defaults
to DATAMAP=OLD if you omit it.
If you want to use 1.8 parameters,
and the 1.7 user work area format, you must specify RELEASE=1.8 or
later and DATAMAP=OLD.
To use the 1.8 parameters, you must specify
RELEASE=1.8 or later. If you specify RELEASE=1.8 or later, the ICHEINTY
parameter list must be in modifiable storage. The parameter list includes
at offset 3 a byte whose low order bit (X'01') will be set
if the action failed because of field level access checking.
The
default is RELEASE=1.7. Table 1. ICHEACTN
parametersParameter |
RELEASE=1.7 and earlier |
RELEASE=1.8 or later |
---|
ENCRYPT= |
X |
X |
FIELD= |
X |
X |
FLDATA= |
X |
X |
GROUP= |
X |
X |
MF= |
X |
X |
RUN= |
X |
X |
TESTS= |
X |
X |
|