technical: A Beginners Guide to Exits

If you're currently upgrading your system to z/OS 2.3 system, you'll be working through all of the migration steps that are published by IBM.

One of these steps is "Examine your IEFUSI exit routine for possible changes." And it won't be first time you've heard the term "exit." But what are these exits, and why do we have them? For us z/OS systems programmers, exits are hooks. A place where we can insert our own code to be executed during normal systems operations. Let's take an example.

IEFACTRT

With z/OS, if you submit a job, then your output will include something like this:

07.39.02 JOB38089 IEF404I JOB001 = ENDED = TIME=07.39.02 
07.39.02 JOB38089 $HASP395 JOB001   ENDED = RC=0000

I know what you're thinking: "our output doesn't look like this." In fact, almost no z/OS site will see this. And that makes sense. This doesn't tell us much does it? Did all the steps execute or not? Any non-zero return codes? How much CPU did they consume? This doesn't help us.

The chances are that you'll see something a bit more like this:

07.39.02 JOB38089                                    ---TIMINGS (SEC)---
07.39.02 JOB3808 -STEPNAME PROCSTEP PROGRAM  RC EXCP   TCB  SRB  CLOCK
07.39.02 JOB3808 -STEP001           IEFBR14  00   45   .00  .00    .06
07.39.02 JOB3808 -STEP002  SAS      SAS      00 155K 69.07  .00 242.46
07.39.02 JOB3808 IEF404I JOB001 = ENDED = TIME=07.39.02
07.39.02 JOB3808 -JOB001  ENDED. TOTAL CPU=69.07. TOTAL ELAP TIME= 242.52
07.39.02 JOB3808 $HASP395 JOB001   ENDED = RC=0000

How is this done? By an exit called IEFACTRT.

IEFACTRT is an SMF exit: it runs at set points during SMF processing. SMF is our z/OS recording feature: writing records when notable events happen. One of these notable events is the end of a job. IBM provide us with an 'exit point:' a point in normal SMF processing where we can execute our own code. IBM gives every exit point a name: IEFACTRT in our case.

So, when a job ends, SMF will write a record: a type 30 subtype 5 to be precise. This record has all sorts of information about the job: return codes, CPU used, I/Os performed, memory used, and more. They're great for systems programmers wanting to find out what has happened in the past. Most sites would like to see this information in the job log. So, rather than go through our SMF type 30 records, we can see this information right now. This is where we use the IEFACTRT exit.

We write a module (usually called IEFACTRT, but we can use another name) that does what we want: output some information to the joblog when the job ends. We then 'install' this exit. Now, every time a job ends, this code will be run, and will output what we want.

Every exit will be documented by the vendor. This includes information about when the exit is run, how it is activated, why we may want to use it, and more. In particular, this documentation will tell us about the rules that must be followed by the exit, and what information is provided to the exit.

Let's look at IEFACTRT. According to the IBM documentation, it is executed when the following SMF records are created:

• SMF types 4, 5, and 30 for background jobs and started tasks.
• SMF types 30, 32, 34, and 35 for TSO/E users.
• SMF types 30 (subtypes 4 and 5) for work initiated by the IBM-supplied APPC/MVS transaction scheduler (ASCH).

• Job name and job class.
• If the job has been cancelled.
• Job or step completion code.
• Relevant SMF record (e.g. SMF type 30 subtype 5 for the end of a batch job).
• Type of task (job, started task, UNIX process, TSO user etc).
• Why the exit was called (e.g. step end, job end, TSO/E session end).

• Cancel remaining job steps (for step termination).
• Do not write an SMF record.

• Must be re-entrant.
• Cannot use the z/OS WAIT macro.
• Must set return codes in registers 1 and 15.

What Exits Can Do

There are a lot of potential exit points that can be used. The IBM MVS Installation Exits manual for z/OS has 55 exits, not including DFSMS, JES, RMF, VTAM and TSO. Exits are not limited to z/OS; many other program products (IBM and ISV) provide exits points. For example, RACF has 19 exit points, CA-ACF2 32, Connect:Direct 8.

Let's look at some examples of exits.

• Websphere MQ: Websphere MQ channel exits can be used when data is input or output over MQ channels. These exits can change data (for example, convert from EBCDIC to ASCII), or provide security.
• CICS: The CICS network error program (DFHZNEP) can be coded to provide tailored processing when a VTAM session fails. For example, it could automatically re-enable a printer if the VTAM session crashes.
• IMS: The IMS Automated Operator Interface provides exits for exactly that. They get control when IMS commands are issued, command responses are returned, or IMS messages are issued.
• SMF: The SMF exit IEFUSI is often used to limit the memory a user can request using the REGION parameter on JCL.
• JES2: JES2 provides exits that can be used to enforce JCL coding standards. For example, the MSGCLASS parameter could be automatically inserted if missing, or the job could be cancelled if the job name did not start with the submitter's userid.
• SORT: DFSORT provides exit points to allow user programs to get control in the middle of DFSORT sort processing.

Creating Exits

Exits are normally programmed in assembler, but this is not always the case. For example, IBM MQ channel exits can be coded in C or assembler. IBM Metal C can also be used in place of assembler for most exits.

Exits are powerful. They get control in the middle of z/OS and other subsystem processing, and can change how that processing occurs. For example, the RACF password exit ICHDEX01 can determine how RACF passwords are encrypted in the RACF database. Exits often gain control in supervisor state, so they have 'superuser' authority: securing each exit is critical. Checking who has access to create or modify exits is one of the first things any security auditor will check.

Equally important is that anyone writing or modifying an exit must have sufficient skills to stop the exit from destroying anything. An error in an exit can quickly crash your z/OS system. Exits must not only perform processing required, but have robust error handling and recovery logic.

Because of the security and reliability issues, many sites minimize the use of exits. We talk more about the best practices in creating, using and maintaining exits in our partner article.

Conclusion

Whenever we buy software, there's often things we want it to do that it doesn't. Or things that it does do, but we want done differently. Exits give us the ability to fix this, and tailor the software to our needs.

But this power comes at a price. Exits must be secured, and should only be created or modified with those that have the right skills and experience. An error in an exit can have catastrophic consequences.

David Stephens

LongEx Quarterly is a quarterly eZine produced by Longpela Expertise. It provides Mainframe articles for management and technical experts. It is published every November, February, May and August.

The opinions in this article are solely those of the author, and do not necessarily represent the opinions of any other person or organisation. All trademarks, trade names, service marks and logos referenced in these articles belong to their respective companies.

Although Longpela Expertise may be paid by organisations reprinting our articles, all articles are independent. Longpela Expertise has not been paid money by any vendor or company to write any articles appearing in our e-zine.