Extending Security Through the z/OS Security Interface › Dynamic Extract/Update Facility

Dynamic Extract/Update Facility

Use the Dynamic Extract/Update Facility (DUF) to extract and update INSTALLATION data area user‑dependent data such as counts, statistics, totals, and CPU usage.

The installation data (INSTDATA) is maintained in the user’s security record. Installation data for any ACID can be maintained using DUF:

• The current ACID as defined by an ACEE
• Any ACID on the Security File.

Use the RACROUTE REQUEST=AUTH call to extract, maintain, and update the installation data. The program name must be defined by the DUFPGM control option or the caller of these functions must be authorized through the TSS ADDTO parameters DUFXTR and/or DUFUPD.

An example of INSTDATA is:

INSTDATA(‘ID=Q477,CPU=00104,CODE=A,BAL=$00366.00')

The Class Names and their functions are listed in the following table.

The ACID field of the entity (offset 0) indicates whether an in‑memory or an on‑file extract/update takes place. If the ACID field is blank, an in‑memory extract/update occurs based on the executing user’s ACID and security record. Otherwise, the INSTDATA for the ACID name is obtained from the Security File and used.

In‑memory INSTDATA is chained from the ACEE for the current ACID in RACF‑compatible format:

+0(1) length of INSTDATA including this length byte
+1(?) installation data for this user

When used with DUF, the length must not appear in the entity field reserved for the installation data.

CA Top Secret automatically updates INSTDATA upon job/session termination if it was previously changed in‑memory. This example shows an in‑memory extract/update.

* Update some code
* Note that this is an in‑memory update
* Installation data will be automatically updated on file when the
* current session ends
         MVC   INSTDATA+0(8),=8C' '     indicate in‑memory extract/update
         MVC   RAUTHL,RAUTHSKL          transfer skeleton
         RACROUTE REQUEST=AUTH,
               CLASS='DUFXTR',
               ENTITY=INSTDATA,
               WORKA=TSSWORK,
               MF=(E,RAUTHL)
         LTR   15,15                    successful extract?
         BNZ   DUFERROR                 branch if unsuccessful
         MVI   INSTDATA+23,C'A'         set operation code
         RACROUTE REQUEST=AUTH,
         ENTITY=INSTDATA,
         MF=(E,RAUTHL)

The installation data area contains the ACID followed by data:

INSTDATA DS    CL8,CL255                acid and data

RAUTHL   RACROUTE REQUEST=AUTH,         Skeletal parameter list
         CLASS='DUFUPD',
         MF=L

To perform an INSTDATA extract/update for any ACID on the Security File, the first line of the above code reads:

MVC INSTDATA+0(8),=CL8'acid'     acid is the name of a
                                        particular ACID

Error Return Codes

If feedback is used, possible detail error return codes are:

x'1E'

Invalid parameter

x'1F'

No DUFXTR/DUFUPD authority

x'46'

ACID undefined

x'4E'

ACID has no INSTDATA

DUF Tips

When using DUF:

• Do not try to reduce or extend the size of the INSTDATA. To change the size of INSTDATA use TSS REPLACE or TSS ADD INSTDATA.
• To enable the TSS command to display meaningful information, maintain EBCDIC information only.
• Keep counters in unpacked numeric format.
• Use fixed format fields or user free‑format with identifiers.
• Use your installation exit (TSS command call) to enforce INSTDATA standards. When updating, the entire INSTDATA field must be replaced.