Indirect reference or lookup

An indirect reference or lookup is the action of retrieving a different field from a database, where the action is based on the value of a base field. The general syntax for an indirect reference is shown here:

   [basefield]:lookup-specification[:lookup-specification …]

The lookup specification itself can contain one, two, or three qualifiers separated by a dot.

   targetfield | type.targetfield | type.keyfield.targetfield

The optional base field is followed by one or more levels of lookup. If you omit the base field, the operation is called an object property lookup or implicit lookup. If the base field is present, the operation is an explicit lookup. Explicit lookups can be an ID lookup, a general lookup, or a deftype lookup. If there is more than one lookup operator (:), the operation is a multi-level lookup. Since release 2.5, the target field can also be a custom field name as defined in the CFIELD class in a RACF database.

For multi-level lookups, the target field of the first lookup is used as a base field for the next lookup. Therefore, all lookups beyond the first one are by definition explicit lookups. The fields that are used as basefield must have a character format. There are no other specific limitations to the use of multi-level lookups.

There is a significant difference between the use of a lookup in a SELECT or EXCLUDE statement and the use of the same lookup in a LIST family command. For use in a SELECT statement, the lookup data must have been read by the program before processing the SELECT statement. For use in a LIST-type statement, the lookup data can be retrieved much later. This implies that not all lookups are supported, depending on the source and target newlist type. For DEFTYPE lookups, zSecure can automatically determine the best point to read the DEFTYPE data. However, combining two or more newlists that each include a SELECT statement that uses a lookup to the other newlist is not supported.

You can specify the following types of indirect references or lookups:

• Object property lookup
• ID lookup
• Deftype lookup
• General lookup

The default Object property lookup and the ID lookup both use the applicable security database as the target. For the ID lookup, the specified base field is used as an ID in the security database. For the Object property lookup, information about the main object in the current record (most often an SMF record) is automatically determined as the base for the lookup in the security database. For certain SMF records, the main object is an ID. In that case, the Object property lookup and an ID lookup might act on the same ID.

Object property lookup

RACF systems

This lookup is used to request properties of a security object. It is specified as:

:targetfield
:targettype.targetfield

In the first case, the target field is retrieved from the security database; in other words the target type is RACF. In the second case it can apply to information from the CKFREEZE system snapshot. The target newlist types can be AS, EXIT, RUN, SETROPTS, SYSTEM, MQ_REGION, DB2_REGION, DB2_TABLE, IMS_REGION, CICS_REGION, CLASS, ICSF_SYMKEY, and SPT. The object property lookup is supported only:

• To default (no targettype specified) from ACCESS, AS_DD, COMPLIANCE, DSN, ID, RACF, RACF_ACCESS, RACF_ACCESS_ID, REPORT_SCOPE, RESOURCE, SENSDSN, SMF, and TRUSTED newlist types.
• To AS from the AS_DD newlist type.
• To DB2_REGION from all other DB2_* newlist types.
• To CICS_REGION from all other CICS_* newlist types.
• To IMS_REGION from all other IMS_* newlist types.
• To MQ_REGION from all other MQ_* newlist types.
• To RUN from any newlist type.
• To SETROPTS: from ID, RACF_ACCESS, and RACF_ACCESS_ID newlist types.
• To SYSTEM: from AS, AS_DD, AUTAB, CICS_*, COMPLIANCE, CONSOLE, CSM, CSM_OWNER, DB2_*, DSN, DSNT, DYNEXIT, EXIT, ICSF_*, IMS_*, IOAPP, IP_*, JOBCLASS, MOUNT, MQ_*, MSG, NJE_NODE, PC, PPT, REPORT_AC1, REPORT_PADS, REPORT_PROGRAM, REPORT_STC, RESOURCE, ROUTER, RRNG, SENSDSN, SMF, SMFOPT, SPT (ICHRIN03), SUBSYS, SVC, SYSTEM, SYSTEM_VARIABLE, UNIX, UNIX_PS, VM_DEV, VM_MDISK, VSM, and VTAM_APPL

The applicable security database is determined automatically based on the available information, for example, from CKFREEZE files. The key that links the target field to the source object consists of the combination of the complex, class, and RACF profile that covers the resource. The target field can be only an existing field in the target database. It is also possible to use one of the target record identification fields (CLASS, PROFILE, and KEY) as the target field. If the target field specification is ambiguous (for example, present in multiple segments), the field value that is shown is not predictable. Defined variables are not supported.

Example object property lookup:

   newlist type=smf
     select exists(profile)
     display resource :instdata
     dsummary class * profile

Example cross-segment object property lookup:

   newlist type=racf
     s class=dataset segment=dfp
     display key complex :instdata
     dsummary resowner

Example object property lookup:

   newlist type=report_scope
     report scope=ibmuser
     display key(firstonly) complex :racf.instdata
     dsummary via

ACF2 systems

The default Object property lookup and the ID lookup both locate fields in the ACF2 logonid database. The Object property lookup is specified as:

   :targetfield

   :type.targetfield

The applicable security database is determined automatically based on the available information, for example, from CKFREEZE files. The object property lookup is supported only:

• to default: from COMPLIANCE, REPORT_SCOPE, SMF, and TRUSTED newlist types.
• to ACF2LID: from ACF2_LID_SYSTEM_SGRP, COMPLIANCE, ID, and SMF newlist types.
• to DB2_REGION from all other DB2_* newlist types.
• to CICS_REGION from all other CICS_* newlist types.
• to IMS_REGION from all other IMS_* newlist types.
• to MQ_REGION from all other MQ_* newlist types.
• to RUN from any newlist type
• to SYSTEM: from ACF2_CLASMAP, ACF2_FDE, ACF2_RES_INFORULE, ACF2_SAFDEF, ACF2_SENSDSN_ACCESS, AS, AS_DD, CICS_*, CLASS, COMPLIANCE, CONSOLE, CSM, CSM_OWNER, DB2_*, DSN, DYNEXIT, EXIT, ICSF_*, IMS_*, IOAPP, IP_*, JOBCLASS, MOUNT, MQ_*, MSG, NJE_NODE, PC, PPT, REPORT_AC1, REPORT_PROGRAM, REPORT_STC, RESOURCE, SENSDSN, SMF, SMFOPT, SUBSYS, SVC, SYSTEM, SYSTEM_VARIABLE, UNIX, UNIX_PS, VSM, and VTAM_APPL

The key that links the target field to the source object is the combination of the complex and a LID. The lookup supports only source records where a LID is used as a resource. Only the following target fields are supported:

• ACF2_UID (UIDstring)
• NAME
• NON-CNCL
• READALL
• RESTRICT
• SECURITY
• STC

If other fields are required, you might be able to use an explicit lookup through the ACF2LID newlist.

Example object property lookup:

   newlist type=smf
     s class=user
     dsummary resource(firstonly) :name :acf2_uid

ID lookup

RACF systems

In an ID lookup the base field is interpreted as a user or group, and the target field is retrieved from that user or group. Use the following code to specify the base and target field values for the lookup:

   basefield:targetfield

ID lookups are supported from all NEWLIST types. The target field is retrieved from the security database (RACF). The security database is determined automatically based on the available information, for example, from CKFREEZE files. The key (source) of the lookup is a user ID or group ID. That is, the value of the base field padded to 8 characters is used to look up a user or group in the same complex as the record.

The target field cannot be a variable. If the target field specification is ambiguous (for example, present in multiple segments), the field value that is shown is not predictable. The ID lookup can be repeated to create a multi-level lookup. It can also be added to extend any of the other lookup types to create a multi-level lookup.

Example ID lookup:

   newlist type=racf
     s  c=group s=base
     d key(8) supgroup owner owner:name owner:instdata

Example multi-level ID lookup:

   newlist type=racf
     s c=dataset s=base
     d class key owner owner:owner owner:owner:instdata

ACF2 systems

In an ID lookup the base field is interpreted as a LID and the target field is retrieved from that LID. Use the following code to specify the base and target field values for the lookup:

   basefield:targetfield

ID lookups are supported from all NEWLIST types. The target field is retrieved from the security database (ACF2). The security database is determined automatically, based on the available information, for example, in CKFREEZE files.

The source key of the lookup is a LID. The value of the base field is padded to 8 characters and used to look up a LID in the same complex as the source record. Only the following target fields are supported:

• ACF2_UID (UIDstring)
• NAME
• NON-CNCL
• READALL
• RESTRICT
• SECURITY
• STC

If other fields are required, you might be able to use an explicit lookup through the ACF2LID newlist.

Example ID lookup:

   newlist type=acf2_rule
     display key
     summary stored_by complex stored_by:name

deftype lookup

Indirect references are possible to any field defined through the DEFTYPE statement. All qualifiers in the lookup specification must be spelled out. The syntax is shown here:

basefield:type.keyfield.targetfield

The newlist type is the type that is specified on the DEFTYPE statement. The keyfield is the defined field that should contain the value that corresponds to the value in the basefield. The targetfield is the defined field that contains the required value.

For example, a data set is allocated that contains two fields: the user ID and the email address of the user. The records in the data set are defined with DEFTYPE TYPE=EMAIL and the two fields are defined as USER and ADDRESS:

   deftype type=email
   define  type=email user    as word(record,1,’ ’)
   define  type=email address as word(record,2,’ ’)

To report on the address of the users in the SMFUSER field, the specification is:

   SMFUSER:EMAIL.USER.ADDRESS

Deftype lookups are performed without case translation. Consequently, the value of the basefield must match the case of the key-values present in the external data file. Because most base fields are uppercase, it is a good idea to use uppercase key-values for the USER field in the email address lookup.

General lookup

A general lookup is an explicit lookup where the value of the base field is used to obtain information from another newlist. Use the following syntax to specify the base and target fields:

   basefield:type.keyfield.targetfield

For the General lookup, all components in this specification are required. Only a limited number of combinations between the newlist of the basefield and the target newlist type and keyfield are supported. The supported combinations are shown in table Table 1. The general lookup can use as targetfield any non-repeated field that is present in the target newlist type.

Examples of using the General lookup are shown here:

Example 1

To select SMF records for a CLASS that is now inactive, you could specify:

   newlist type=smf
   select class:class.class.active=no

The CLASS properties are taken from the default system for the complex that the record belongs to, not necessarily from the system the record pertains to. Typically, this is the same system.

Example 2

To select SMF records from RACF systems based on the &SYSCLONE system variable, you could specify:

   newlist type=smf
   select system:system.system.sysclone=’01’

The wanted value is located by using the SMF ID (which can be found in the CARLa SYSTEM field) as the name of the system. The settings for the system within the current complex and version are used.

Example 3

To show if program protection is active, the following lookup to SETROPTS settings can be used:

   newlist type=REPORT_PROFILE
   sortlist key complex complex:setropts.complex.whenprogram

The value for the base field is interpreted as a complex name. You can use this lookup to retrieve system-wide options from a RACF database inventory control block (ICB) associated with the complex specified in the base field. The lookup to SETROPTS is supported only for the REPORT_PROFILE NEWLIST.

Table 1. Supported sources for an explicit lookup operation to target newlists CLASS, SYSTEM, SETROPTS, ACF2_LID, and ACF2_FDE

Source newlist	CLASS (class)	SYSTEM (system)	SETROPTS (complex)	ACF2_LID (lid)	ACF2_FDE (fieldname)	EXIT (module, program)
ACCESS	Yes	Yes
ACF2_CLASMAP		Yes
ACF2_INFO				Yes	Yes
ACF2_INFORULE, ACF2_INFOLINE				Yes
ACF2_FDE		Yes
ACF2_LID_SYSTEM_SGRP				Yes
ACF2_RES_INFORULE		Yes
ACF2_RULE, ACF2_RULELINE				Yes
ACF2_SAFDEF		Yes
ACF2_SENSDSN_ACCESS		Yes
AS		Yes		Yes
AS_DD		Yes
AUDIT		Yes
AUTAB		Yes
CF_STRUCT		Yes
CICS_PROGRAM	Yes	Yes
CICS_REGION	Yes	Yes		Yes
CICS_TRANSACTION	Yes	Yes
CLASS	Output	Yes
COMPLIANCE		Yes		Yes
CONSOLE		Yes		Yes
CSM		Yes
CSM_OWNER		Yes
DB2_ACCESS		Yes		Yes
DB2_BUFFERPOOL	Yes	Yes
DB2_COLLECTION	Yes	Yes
DB2_DATABASE	Yes	Yes
DB2_DATATYPE	Yes	Yes
DB2_JAR	Yes	Yes
DB2_PACKAGE	Yes	Yes
DB2_PLAN	Yes	Yes
DB2_REGION	Yes	Yes		Yes
DB2_ROUTINE	Yes	Yes
DB2_SCHEMA	Yes	Yes
DB2_SEQUENCE	Yes	Yes
DB2_STOGROUP	Yes	Yes
DB2_TABLE	Yes	Yes
DB2_TABLESPACE	Yes	Yes
DB2_VARIABLE	Yes	Yes
DSN		Yes
DSNT		Yes
DYNEXIT		Yes
EXIT		Yes
ICSF_PUBKEY		Yes
ICSF_SYMKEY	Yes	Yes
ICSF_TOKEN		Yes
ID				Yes
IMS_PSB	Yes	Yes
IMS_REGION	Yes	Yes		Yes
IMS_TRANSACTION	Yes	Yes
IOAPP		Yes
IP_AUTOLOG		Yes
IP_FTP_REGION		Yes		Yes
IP_INTERFACE		Yes
IP_NETACCESS	Yes	Yes
IP_PORT	Yes	Yes
IP_RESOLVER		Yes
IP_ROUTE		Yes
IP_RULE		Yes
IP_STACK		Yes
IP_TELNET_PORT		Yes		Yes		Yes
IP_TELNET_REGION		Yes		Yes
IP_VIPA	Yes	Yes
JOBCLASS		Yes
MOUNT		Yes
MQ_AUTHINFO		Yes
MQ_CHANNEL		Yes
MQ_CHLAUTH		Yes
MQ_CONNECT		Yes
MQ_INIT		Yes
MQ_NAMELIST	Yes	Yes
MQ_PROCESS	Yes	Yes
MQ_QUEUE	Yes	Yes
MQ_REGION	Yes	Yes		Yes
MQ_TOPIC	Yes	Yes
MSG		Yes
NJE_NODE		Yes
PC		Yes
PPT		Yes
RACF	Yes
RACF_ACCESS	Yes
REPORT_AC1		Yes
REPORT_PADS		Yes
REPORT_PROFILE	Yes		Yes
REPORT_PROGRAM		Yes
REPORT_SCOPE	Yes
REPORT_STC		Yes
RESOURCE	Yes	Yes
ROUTER	Yes	Yes
RRNG		Yes
RRSFNODE		Yes
SENSDSN		Yes
SMF	Yes	Yes		Yes
SMFOPT		Yes
SPT ICHRIN03		Yes
SUBSYS		Yes
SUPSESS_REGION_CP	Yes	Yes
SVC		Yes
SYSTEM		Yes
SYSTEM_VARIABLE		Yes
TRUSTED	Yes	Yes		Yes
UNIX		Yes
UNIX_PS		Yes
VM_DEV	Yes	Yes
VM_MDISK	Yes	Yes
VSM		Yes
VTAM_APPL		Yes

In the next table, partial means that the lookup is supported for output only, not for selection.

Table 2. Supported sources for an explicit lookup operation to target newlists AS, DB2_REGION, ICSF_SYMKEY, ID, MQ_REGION, and SPT

Target newlist and keyfield
Source newlist	AS (asid)	DB2_REGION (db2id)	ICSF_SYMKEY (label)	ID (id)	MQ_REGION (mqid)	SPT (procname)
ACF2_SENSDSN_ACCESS				Yes
ACF2_RESOURCE_ACCESS				Yes
AS_DD	Yes
CICS_PROGRAM	Yes
CICS_REGION	Yes
CICS_TRANSCTIONS	Yes
COMPLIANCE				Yes
CONSOLE				Partial
CSM_OWNER	Yes
DB2_BUFFERPOOL		Yes
DB2_COLLECTION		Yes
DB2_CONTROL		Yes
DB2_DATABASE		Yes
DB2_DATATYPE		Yes
DB2_JAR		Yes
DB2_PACKAGE		Yes
DB2_PLAN		Yes
DB2_REGION	Yes
DB2_ROUTINE		Yes
DB2_SCHEMA		Yes
DB2_SEQUENCE		Yes
DB2_STOGROUP		Yes
DB2_TABLE		Yes
DB2_TABLESPACE		Yes
DB2_VARIABLE		Yes
DEFTYPE						Yes
DSN			Yes
IMS_PSB	Yes
IMS_REGION	Yes
IMS_TRANSACTION	Yes
MQ_AUTHINFO					Yes
MQ_CHANNEL					Yes
MQ_CHLAUTH					Yes
MQ_CONNECT	Yes				Yes
MQ_INIT					Yes
MQ_NAMELIST					Yes
MQ_PROCESS					Yes
MQ_REGION	Yes
MQ_TOPIC					Yes
RACF				Yes
RACF_ACCESS				Yes
RACF_ACCESS_ID				Yes
REPORT_PROFILE				Yes
REPORT_SCOPE				Yes
REPORT_STC				Yes
RESOURCE				Yes
SENSDSN			Yes	Yes
SMF			Yes	Yes
SUPSESS_REGION_CP	Yes
UNIX_PS	Yes
VTAM_APPL	Yes