SMF ACCTRTE - Global Account Code Exit Routine
You must code the user exit routine ACCTRTE to populate account code values after they have been defined. This exit is invoked to build the ACCTNOx data elements, where x is the account code level. For example, if the ACCOUNT member defines three account code levels, the ACCTRTE exit routine is coded to populate data elements ACCTNO1, ACCTNO2, and ACCTNO3. The values assigned to the ACCTNOx data elements in ACCTRTE are global and, by default, these values are used in every observation written for every address space type for a particular job.
micsrm140cd
You must code the user exit routine ACCTRTE to populate account code values after they have been defined. This exit is invoked to build the ACCTNOx data elements, where x is the account code level. For example, if the ACCOUNT member defines three account code levels, the ACCTRTE exit routine is coded to populate data elements ACCTNO1, ACCTNO2, and ACCTNO3. The values assigned to the ACCTNOx data elements in ACCTRTE are global and, by default, these values are used in every observation written for every address space type for a particular job.
This routine executes only once for each RDRTS and JOB combination encountered, when
MICS
first merges the various SMF record types for each unique address space. The ACCTNOx values set in ACCTRTE will be used in the BATJOB observation for the job, and in each step or interval observation written to the step-level files. The ACCTNOx values can be overridden in the USRSPGM user exit for the step-level files, and in USRSSPL for the BATSPL files.Data element, ACCTMASK, which is kept in all batch information area files, shows which SMF record types were present when the ACCTRTE routine was executed to assign the ACCTNOx values. ACCTMASK can be used as a debugging tool if problems occur with your ACCTRTE routine code.
A similar data element found in the BATJOB file, JOBMASK, shows the SMF records that were present when the BATJOB observation was built. JOBMASK sometimes has more SMF record types present than ACCTMASK, because JOBMASK is updated daily for jobs suspended in the BAT_JS file when new SMF data is processed.
Preparation
Use SAS to code the ACCTRTE routine, and ensure there are no syntax errors. A sample ACCTRTE member is provided in sharedprefix.MICS.PARMS(ACCTRTE) as a template. For more information, see Notes on Coding
MICS
Parameters.Data Elements for Account Code Routine
MICS
merges the following list of SMF record types for each address space type input from the SMF raw data file. When ACCTRTE is invoked, it has access to all data elements in the first observation encountered for each unique SMF record type associated with the address space. At least one of these SMF record types is present when ACCTRTE is invoked.Useful for the ACCTRTE Exit
- Job Initiation (SMF record type 30 subtype 1)
- Job End (SMF record type 30 subtype 5)
- Job Purge (SMF record type 26)The job purge record has limited usefulness in the ACCTRTE exit. ACCTRTE is entered only once, whenMICSfirst encounters records for an address space. The purge record is often not available because it is the last record written for an address space. The scenarios that make the purge record useful for account code setting generally involve SYSOUT-only jobs, where no job execution SMF record types are encountered. To guarantee thatMICSwill wait for the purge record in these SYSOUT-only jobs, you should code an SPLLIMIT statement as described in SMF SPLLIMIT Statement.
- BATSFH Job Account Derivation Hold File observation
Useful for Step-Level Accounting
- Step/Interval (SMF record type 30 subtypes 2, 3, or 4)
Useful for Spool (Output Record) Level Accounting
- Output Writer (SMF record type 6)
Not Useful For Accounting
- MDS Mount (SMF record type 25 - JES3 only)
The Job Account Derivation Hold (BATSFH) file is a special file designed to supply accounting information for certain types of SYSOUT. It is fully described in the BATSFH - Job Account Derivation Hold File section. SYSOUT accountability is discussed in the SYSOUT Considerations section.
Setting global ACCTNOx values for an address space implicitly excludes dependence on data elements found in step, interval, and output writer records. A given address space may have numerous steps and SYSOUT data sets. The ACCTRTE is invoked only once, when the first step or interval record, and the first output writer record, if present, are in the SAS input data buffer. It does not make sense to set global, job-level account code values from SMF records that do not represent all aspects of the job. The ACCTNOx account code values set in the ACCTRTE exit are, by default, used for every
MICS
database observation written for the address space. Their values represent accountability for all system resources consumed by executing and printing the job. They should, therefore, be derived from sources that give information about the entire job, not just one step or output data set.Most account code schemes rely on information that is auditable during job read-in time or address space initialization time. JES2, JES3, MVS, and RACF all provide exit points to verify and control certain important value specifications, such as the job card account fields or RACF user ID. The most common fields used to set ACCTNOx values are shown below. Additionally, any data element in the Batch User Job Activity (BATJOB) file is available to the account code routine.
- Available from Job Initiation (SMF 30_1), Job End (SMF 30_5), and BATSFH File:
- ACTFLD1-5 - The first five SMF accounting fields from the JOB card (carried as 20-character fields). A field that was not specified will be blank.
- JOB - Job Name
- JOBCLASS - Job Input Class
- JOBPRTY - Job Input Priority
- PERFGRP - Performance Group Number
- JOBPRGNM - Job Programmer Name
- SYSID - SYSID where job executed
- PGMTYPE - Variable to define address space type:
- batch - PGMTYPE=1
- TSO - PGMTYPE=2
- started task - PGMTYPE=3
- APPC/MVS TP - PGMTYPE=4
- USS - PGMTYPE=5
- SA - PGMTYPE=6
- Available from Job Purge(SMF 26)
- JOBNETAC - NJE Network Account Number
The above fields represent the information that most sites use to set account codes and assign responsibility for system resource consumption. Because any combination of SMF record types may be present for a given address space,
MICS
provides a number of internal fields that you may reference within your account routine. These temporary data elements are populated prior to invoking the ACCTRTE exit and allow you to determine which SMF record types are present.I_AUDIT
Job Initiation Record Indicator
I_AUDIT='I' specifies record present
I_AUDIT='.' specifies no record present
S_AUDIT
Step Termination Record Indicator
S_AUDIT='S' specifies record present
S_AUDIT='.' specifies no record present
J_AUDIT
Job Termination Record Indicator
J_AUDIT='J' specifies record present
J_AUDIT='.' specifies no record present
W_AUDIT
Writer Record Indicator
W_AUDIT='W' specifies record present
W_AUDIT='.' specifies no record present
P_AUDIT
Job Purge Record Indicator
P_AUDIT='P' specifies record present
P_AUDIT='.' specifies no record present
JOBMASK/ACCTMASK
Five-byte fields defining the records present for this particular job. These fields are the concatenation of the above five fields and are provided to simplify status testing. For example, a job that has at least one record present for each record type would have a JOBMASK equal to ISJWP. A job consisting of NJE routed output writer records would have a JOBMASK equal to ...WP.
At the point where ACCTRTE is entered, both JOBMASK and ACCTMASK have identical values. Later, when the BATJOB observation is written to the
MICS
database, JOBMASK and ACCTMASK may not be equal. This inequality occurs because JOBMASK reflects all SMF record types that MICS
encounters for the job prior to output to the BATJOB file. These SMF records may be encountered over several MICS
daily update runs. ACCTMASK, on the other hand, never changes. Its value is set once, when MICS
encounters the job for the first time and enters ACCTRTE.H_AUDIT
Job Account Derivation Hold File Indicator -
H_AUDIT='H' specifies observation present -
H_AUDIT='.' specifies no observation present
ACCTINFO
Indicates the presence of job-level accounting information. If one of the following conditions are true then
MICS
sets ACCINFO=1 prior to the invocation of the ACCTRTE exit. Otherwise MICS
sets ACCTINFO=0.- Job initiation record (I_AUDIT='I')
- Job end record (J_AUDIT='J'),
- An observation from the Job Account Derivation Hold (BATSFH) file (H_AUDIT='H')
- An SMF type 26 purge record (P_AUDIT='P') and Job Card Account Fields Flag (SMF26ACT) isset to indicate job card account fields are present
- An SMF type 6 output writer record (W_AUDIT='W') and Job Card Account Fields Flag (SMF6CT) is set to indicate job card account fields are present.
FLUSHJOB
Set to 0 upon entry to the exit
If you want to discard the job being processed, set the FLUSHJOB indicator to 1. This setting prevents
MICS
from creating a BATJOB observation for the job. Step and interval records for the job still write to the step-level MICS
database files and output writer records still write to the BATSPL file. You should use the FLUSHJOB facility with great caution.The code written in ACCTRTE must only assign values to the ACCTNOx data elements. In other words, the only SAS assignment statements in your ACCTRTE should look like either of these:
ACCTNO1=ACTFLD1 ; ACCTNO2=RACFUSID ;
Never, under any circumstances, assign values to any data elements besides ACCTNOx.
Coding Considerations
In coding the ACCTRTE, consider the following information:
- Common data element Time Zone (ZONE) should not be referenced by your account routine. At the point that ACCTRTE is invoked, ZONE has not been determined. ZONE is calculated for each individual interval, step, and output writer record based on ENDTS and is available in the user exits invoked just prior to the output ofMICSdatabase observations.
- Always validate the information in the fields you use to set ACCTNOx values. When invalid information is encountered, set the ACCTNOx values to values representing your data center's overhead account.Note:Setting ACCTNOx values to invalid values increases the number of records and, therefore, increases the DASD space requirements of theMICSsummary database files. For example, if the first account field on a job card (ACTFLD1) represents the division and you know that there are only six divisions in the company, verify that ACTFLD1 contains one of the six division values before setting ACCTNO1=ACTFLD1. Failure to do so can result in unnecessarily large DASD requirements becauseMICScreates a summary observation for each unique value encountered in the account codes.
- You must verify that the information required to set account codes is available before assignment. For example, the job card accounting fields (ACTFLD1-5) are only available if one or more of the following are present when your account routine is entered:Job Initiation Record (SMF type 30 subtype 1) Job End Record (SMF type 30 subtype 5) BATSFH File Observation SMF Type 26 Purge RecordWhen the internal data element ACCTINFO=1, at least one of these four sources of job-level account information is available.Note:The BATSFH file is a special, customized, internalMICSfile that can provide accountability for certain types of SYSOUT that would otherwise be charged to overhead accounts. For information about SYSOUT accountability, see the SYSOUT Considerations section. For details about the BATSFH file and its customization, see BATSFH - Job Account Derivation Hold File.
- If you have decided to use either the LATEJOB or NJEJOB option statements to force the creation of BATJOB observations for SYSOUT, you should write code in ACCTRTE to supply ACCTNOx values for these SMF record sets. These record sets will never have a job initiation or job end record to provide the ACTFLDx and other job-related values traditionally used to set ACCTNOx values. If you have activated the BATSFH file, some of these record sets will be associated with a BATSFH file observation and be handled by your ACCTINFO=1 code. Some, however, will not. SYSOUT sent from a non-z/OS system such as VM will only produce SMF record sets consisting of one or more SMF type 6 records and an SMF type 26 purge record. The following ACCTRTE sample code handles these situations where ACCTINFO=0.
Sample ACCTRTE Exit
This sample account routine exit code is for a company with three account codes. The three account codes are defined in sharedprefix.MICS.PARMS(ACCOUNT) as follows:
* * ACCOUNT CODE STRUCTURE * 1 3 Division 2 5 Dept 3 8 User 4 1 Unused 4 5 1 Unused 5 6 1 Unused 6 7 1 Unused 7 8 1 Unused 8 9 1 Unused 9
- ACCTNO1 holds the Division, a three-character field.
- ACCTNO2 holds the Department, a five-character field.
- ACCTNO3 holds the User ID, and eight-character field.
- ACCTNO4-9 are defined but unused.
The Division and Department values are specified in the job card. User ID is set from the RACF User ID field. Started tasks (PGMTYPE=3), have valid RACF User ID values but no job card account fields.
This site has created two SAS formats, $GOODDIV and $GOODDPT that contain all valid division and department values for the company. These two formats return a value of YES if the division or department value is valid.
/* SAMPLE ACCOUNT ROUTINE EXIT CODE */ /* */ /* SET OVERHEAD VALUES */ /* */ ACCTNO1='***' ; ACCTNO2='*****' ; ACCTNO3='********' ; ACCTNO4=' ' ; ACCTNO5=' ' ; ACCTNO6=' ' ; ACCTNO7=' ' ; ACCTNO8=' ' ; ACCTNO9=' ' ; /* */ /* CHECK IF JOB CARD INFORMATION IS AVAILABLE. */ /* DATA ELEMENT ACCTINFO EQUALS 1 IF THE INITIATION */ /* OR JOB END SMF RECORD, A BATSFH FILE OBS IS */ /* AVAILABLE, OR AN SMF TYPE 26 PURGE RECORD IS */ /* PRESENT AND CONTAINS JOB CARD ACCOUNT INFORMATION.*/ /* */ IF ACCTINFO THEN DO ; /* INIT, JOB END, BATSFH, OR */ /* PURGE REC WITH ACTFLD'S */ IF PUT(ACTFLD1,$GOODDIV.)='YES' THEN ACCTNO1=ACTFLD1 ; IF PUT(ACTFLD2,$GOODDPT.)='YES' THEN ACCTNO2=ACTFLD2 ; ACCTNO3=RACFUSID ; END ; /* */ /* IF PURGE RECORD PRESENT, SET DIVISION AND DEPT */ /* FROM THE NJE NETWORK ACCOUNT FIELD IF POPULATED. */ /* ACCTNO3, USER ID, IS ONLY SET IF THE PURGE */ /* RECORD USER ID FIELD, SMF26UID, IS NON-BLANK. */ /* */ IF JOBMASK='...WP' OR JOBMASK='....P' THEN DO ; IF JOBNETAC NE ' ' THEN DO ; TEMPDIV=SUBSTR(JOBNETAC,1,3) ; TEMPDPT=SUBSTR(JOBNETAC,4,5) ; IF PUT(TEMPDIV,$GOODDIV.)='YES' THEN ACCTNO1=TEMPDIV ; IF PUT(TEMPDIV,$GOODDPT.)='YES' THEN ACCTNO2=TEMPDPT ; END ; IF SMF26UIF NE ' ' THEN ACCTNO3=SMF26UIF ; END ;
The most notable thing about this sample ACCTRTE exit code is that overhead values are assigned first. The overhead values are only overwritten if valid account code information is encountered. By using this technique you can systematically identify observations written with overhead account codes, determine why they received overhead values, and make appropriate adjustments to your ACCTRTE.
Use the following Batch Account Code Exit Routine worksheet to code your account code exit routine (ACCTRTE).
+--------------------------------------------------------------------------+ | INSTALLATION PREPARATION WORKSHEET: Account Code Routine Definition | | | | PARMS Library Member is ACCTRTE | | | +--------------------------------------------------------------------------+ | | | ________________________________________________________________________ | | | | ________________________________________________________________________ | | | | ________________________________________________________________________ | | | | ________________________________________________________________________ | | | | ________________________________________________________________________ | | | | ________________________________________________________________________ | | | | ________________________________________________________________________ | | | | ________________________________________________________________________ | | | | ________________________________________________________________________ | | | | ________________________________________________________________________ | | | | ________________________________________________________________________ | | | | ________________________________________________________________________ | | | | ________________________________________________________________________ | | | | ________________________________________________________________________ | +--------------------------------------------------------------------------+ | ....5...10...15...20...25...30...35...40...45...50...55...60...65...70.. | +--------------------------------------------------------------------------+
System Address Space Processing Considerations
The first time a new address space is encountered with a unique JOB/RDRTS combination, ACCTRTE executes. At this time, a job initiation record (SMF type 30 subtype 1) is expected. It contains the job card (ACTFLDx fields) required by ACCTRTE.
When ACCTRTE is executed, the ACCTNOx variables are populated with the ACTFLDx field values, and a flag (ACCTFLAG) is set to 1 in the BAT_JS (Batch Job Activity Suspend File) to indicate that this address space has been through ACCTRTE, and the ACCTNOx field values have been established. When ACCTFLAG equals 1, the address space will not go through ACCTRTE again. Once the address space has gone through ACCTRTE, and the ACCTNOx values are established, they are preserved in the BAT_JS file, and merged with new step/interval records in subsequent executions.
If ACCTRTE code is updated, address spaces that have already gone through ACCTRTE, and address spaces that are still executing, would be immune from any ACCTRTE updates. The BAT_JS01 record for the address space will propagate the ACCTNOx values set using the old ACCTNOx code.
To take advantage of the ACCTRTE updates for system address spaces, there are two options:
- IPL. This option restarts system address spaces, which would consider them as NEW, and thus go through ACCTRTE.
- Copy BAT_JS01 from the production complex to a test complex, and run a job to recreate the BAT_JS01 file:
DATA DETAIL.BAT_JS01; SET DETAIL.BAT_JS01; (additional code)
Additional code can be either of the following:
- The updated ACCTRTE code for system address spaces to reestablish new values in ACCTNOx field. In a test unit, run an update using the updated BAT_JS01. The updated ACCTNOx values propagate to the BAT_SA file observations.
- Code to change the value of ACCTFLAG from 1 to 0 in the BAT_JS01 file for system address spaces (JOBTYPE=6). Run an update using the updated BAT_JS01 file. The updated address spaces are forced to go through ACCTRTE.